Guias
Primeiros passos
O mesmo percurso do tutorial «Comece com a API passo a passo» de Desenvolvedores, para quem programa. Crie uma chave de testes (pt_test_…) com permissões somente de leitura, verifique a conexão, leia dados reais e, quando a integração estiver pronta, passe para uma chave live com as permissões justas. Os avisos automáticos (webhooks) e as escritas exigem o plano Developer ou superior.
1. Crie uma chave em «Minhas chaves»
Escolha o ambiente de testes e apenas permissões de leitura (por exemplo budgets:read). A chave completa é exibida uma única vez: guarde-a em um gerenciador de senhas e envie-a no cabeçalho Authorization: Bearer.
2. Verifique a conexão
GET /api/v1/ping
Responde com o nome da chave, suas permissões e o ambiente. Um 401 significa chave inválida; um 403, que falta uma permissão.
3. Leia seus dados reais
GET /api/v1/budgets
?limit=3
As listagens são paginadas por cursor: repita a chamada com cursor=<next_cursor> até que has_more seja false. Cada resposta traz X-RateLimit-Remaining com as requisições que restam na janela.
4. Receba avisos automáticos
POST /api/v1/webhooks
{ "url": "https://seu-sistema.com/avisos-da-oficina", "events": ["lead.accepted", "vehicle.ready"] }Também podem ser criados na aba Webhooks sem programar. Guarde o segredo de assinatura e verifique X-PT-Signature em cada entrega; responda 2xx em menos de 5 segundos.
5. Passe para produção
Antes, se quiser, teste escritas, aceitações, faturas e mensagens sem risco no ambiente de testes (https://demo.programa-taller.es/desarrolladores-sandbox): dados fictícios e nada sai de verdade. Crie uma chave live com as permissões mínimas e, se for gravar dados, adicione Idempotency-Key a cada POST. Os limites e o plano de API da oficina aparecem na aba Consumo; os planos Developer e Business são contratados no próprio sistema.
Guia: criar um orçamento e propor um agendamento
Fluxo típico de um CRM ou de um site de agendamento. Todas as requisições POST levam Idempotency-Key (um UUID novo por operação; repita-o só ao tentar de novo a mesma). Você precisa de uma chave live com clients:write, vehicles:write, budgets:write, appointments:read e appointments:write.
1. Cliente: criar ou recuperar o existente
POST /api/v1/clients
{ "name": "Laura Gómez", "phone": "600111222", "email": "laura@ejemplo.com" }Com ?on_conflict=return_existing, se o telefone, o e-mail ou o NIF já existirem, você recebe esse cliente (200) em vez de 409.
2. Veículo do cliente
POST /api/v1/vehicles
{ "client_id": 1204, "plate": "1234KLM", "brand": "Seat", "model": "León" }Se a placa for de outro cliente: 409 vehicle_belongs_to_other_client (a oficina decide).
3. Orçamento com seus itens
POST /api/v1/budgets
{ "client_id": 1204, "vehicle_id": 871, "lines": [{ "description": "Troca de óleo e filtro", "quantity": 1, "unit_price": 65 }] }A resposta traz os totais calculados. O cliente aceita e assina pelo link que a oficina envia (a API nunca fornece esse link); se ele confirmar a você por outra via, aceite em nome dele com POST /budgets/{id}/accept (permissão budgets:accept).
4. Horários livres
GET /api/v1/appointments/availability
?from=2026-10-14&to=2026-10-18&duration_minutes=60
5. Propor o agendamento
POST /api/v1/appointments
{ "budget_id": 1234, "start": "2026-10-14T09:00:00+02:00", "duration_minutes": 60 }No modo «propor» fica status=proposed até a oficina confirmar (você recebe appointment.confirmed por webhook). Se o horário já foi ocupado: 409 slot_unavailable com alternativas.
Guia: seu bot ou IA nos canais da oficina
Seu assistente responde por WhatsApp, SMS, chat do site ou e-mail no lugar do assistente do sistema. Você precisa de uma chave live com communications:read, messages:send, settings:write e webhooks:manage (plano Business ou Partner). Teste antes no ambiente de testes com POST /sandbox/simulate/message.
1. Assine message.received
POST /api/v1/webhooks
{ "url": "https://seu-bot.com/oficina", "events": ["message.received"] }Cada mensagem do cliente chega assinada com a chave da conversa (key), o cliente, o orçamento ativo, o texto e os anexos.
2. Ative o modo assistente externo
PUT /api/v1/settings/assistant
{ "external_channels": ["whatsapp", "chat"], "fallback_minutes": 10 }Nesses canais o assistente do sistema deixa de responder. Se você não responder a tempo, ou sua chave ou seu webhook deixarem de funcionar, ele volta a responder a essa mensagem.
3. Leia o histórico se precisar
GET /api/v1/conversations/{key}/messages
4. Responda
POST /api/v1/conversations/{key}/messages
{ "text": "Amanhã às 9:00 temos horário. Posso reservar para você?" }Fora da janela de 24 h do WhatsApp envie template_id (GET /messages/templates). Para fechar a venda: POST /appointments, POST /budgets/{id}/accept ou POST /budgets/{id}/invoice conforme suas permissões.
Ambiente de testes
https://demo.programa-taller.es é uma instância com dados fictícios que são restaurados a cada 2 horas. Toda chave de lá é de testes com todas as permissões: pode gravar, aceitar, faturar e «enviar», mas nada sai de verdade (os envios são registrados como simulados) e os webhooks são emitidos normalmente para testar o ciclo completo. Suas chaves, webhooks e registro de requisições são mantidos entre as reinicializações.
1. Peça sua chave
POST /api/v1/sandbox/keys
{ "email": "dev@exemplo.com", "company": "Integrações Exemplo Ltda", "name": "Ana Souza" }Também pela página https://demo.programa-taller.es/desarrolladores-sandbox. A chave é exibida uma única vez e vale 30 dias.
2. Simule um cliente escrevendo
POST /api/v1/sandbox/simulate/message
{ "channel": "whatsapp", "from": "+34600111222", "text": "Vocês têm horário amanhã?" }3. Mude para produção
Troque a URL base pela da instância da oficina e use uma chave live criada na seção Desenvolvedores dela.
Clientes
GET /api/v1/clients clients:read
Listar clientes
Ordenados por id crescente. Os clientes apagados a pedido (RGPD) aparecem anonimizados, com erased_at preenchido.
Permissão necessária: clients:read.
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
search | string | Não | Busca em nome, telefone, e-mail e NIF/CIF (mínimo de 2 caracteres). |
expand | string [vehicles] | Não | Relações opcionais a incluir. |
limit | integer · default 50 | Não | Resultados por página (1–200). |
cursor | string | Não | Cursor opaco devolvido em next_cursor da página anterior. |
Exemplo
curl "https://sua-oficina.example/api/v1/clients" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"data": [
{
"id": 1204,
"name": "Laura Gómez",
"phone": "+34600111222",
"phone_secondary": null,
"whatsapp_phone": null,
"email": "laura@ejemplo.com",
"billing_email": null,
"tax_id": "12345678Z",
"address": "C/ Mayor 12",
"city": "Barcelona",
"zip": "08001",
"province": "Barcelona",
"country": "ES",
"preferred_language": "es",
"preferred_contact_method": "whatsapp",
"vip": false,
"marketing_opt_out": false,
"channel_opt_out": {
"email": false,
"sms": false,
"whatsapp": false,
"call": false
},
"erased_at": null,
"vehicles": [
{
"id": 871,
"client_id": 1204,
"client": null,
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"km": 84500,
"itv_expiry_date": "2027-03-15",
"status": "activo"
}
]
}
],
"next_cursor": "aWQ6MTIzNA",
"has_more": true
}
POST /api/v1/clients clients:write
Criar um cliente
Nunca mescla com um cadastro existente: se o NIF/CIF, o e-mail ou o telefone já estiverem em outro cliente, responde 409 client_exists com existing_id (ou 200 com esse cliente se você passar ?on_conflict=return_existing). O telefone é salvo como no cadastro (Espanha com 9 dígitos, outros países com o código do país) e o e-mail em minúsculas; erros de digitação não são corrigidos. As recusas de marketing ficam no registro de consentimentos.
Permissão necessária: clients:write.
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
on_conflict | string [error, return_existing] · default error | Não | error (padrão): 409 se já existir. return_existing: 200 com o cliente existente. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"name": "Laura Gómez",
"phone": "600111222",
"phone_secondary": null,
"email": "laura@ejemplo.com",
"billing_email": null,
"tax_id": "12345678Z",
"address": "C/ Mayor 12",
"city": "Barcelona",
"zip": "08001",
"province": "Barcelona",
"country": "ES",
"preferred_language": "es",
"preferred_contact_method": "whatsapp",
"marketing_opt_out": false,
"channel_opt_out": {
"email": false,
"sms": false,
"whatsapp": false,
"call": false
}
}
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/clients" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"Laura Gómez","phone":"600111222","phone_secondary":null,"email":"laura@ejemplo.com","billing_email":null,"tax_id":"12345678Z","address":"C/ Mayor 12","city":"Barcelona","zip":"08001","province":"Barcelona","country":"ES","preferred_language":"es","preferred_contact_method":"whatsapp","marketing_opt_out":false,"channel_opt_out":{"email":false,"sms":false,"whatsapp":false,"call":false}}'
Resposta
{
"id": 1204,
"name": "Laura Gómez",
"phone": "+34600111222",
"phone_secondary": null,
"whatsapp_phone": null,
"email": "laura@ejemplo.com",
"billing_email": null,
"tax_id": "12345678Z",
"address": "C/ Mayor 12",
"city": "Barcelona",
"zip": "08001",
"province": "Barcelona",
"country": "ES",
"preferred_language": "es",
"preferred_contact_method": "whatsapp",
"vip": false,
"marketing_opt_out": false,
"channel_opt_out": {
"email": false,
"sms": false,
"whatsapp": false,
"call": false
},
"erased_at": null,
"vehicles": [
{
"id": 871,
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"km": 84500,
"itv_expiry_date": "2027-03-15",
"status": "activo"
}
]
}
GET /api/v1/clients/{id} clients:read
Detalhe de um cliente
Permissão necessária: clients:read.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do cliente. |
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
expand | string [vehicles] | Não | Relações opcionais a incluir. |
Exemplo
curl "https://sua-oficina.example/api/v1/clients/1234" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"id": 1204,
"name": "Laura Gómez",
"phone": "+34600111222",
"phone_secondary": null,
"whatsapp_phone": null,
"email": "laura@ejemplo.com",
"billing_email": null,
"tax_id": "12345678Z",
"address": "C/ Mayor 12",
"city": "Barcelona",
"zip": "08001",
"province": "Barcelona",
"country": "ES",
"preferred_language": "es",
"preferred_contact_method": "whatsapp",
"vip": false,
"marketing_opt_out": false,
"channel_opt_out": {
"email": false,
"sms": false,
"whatsapp": false,
"call": false
},
"erased_at": null,
"vehicles": [
{
"id": 871,
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"km": 84500,
"itv_expiry_date": "2027-03-15",
"status": "activo"
}
]
}
PATCH /api/v1/clients/{id} clients:write
Modificar um cliente
Só mudam os campos enviados (null limpa o campo). É possível mudar e-mail ou telefone, e fica o valor anterior → novo na atividade do cliente com o nome da chave; emite client.updated. Não é possível usar o e-mail, telefone ou NIF de OUTRO cadastro (409 client_exists). Cadastros apagados a pedido (RGPD) respondem 409 client_erased.
Permissão necessária: clients:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do cliente. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Não | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"name": "Laura Gómez Ruiz",
"phone": "600111222",
"phone_secondary": null,
"email": "laura@ejemplo.com",
"billing_email": null,
"tax_id": "12345678Z",
"address": "C/ Mayor 12",
"city": "Barcelona",
"zip": "08001",
"province": "Barcelona",
"country": "ES",
"preferred_language": "es",
"preferred_contact_method": "whatsapp",
"marketing_opt_out": false,
"channel_opt_out": {
"email": false,
"sms": false,
"whatsapp": false,
"call": false
}
}
Exemplo
curl -X PATCH "https://sua-oficina.example/api/v1/clients/1234" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"name":"Laura Gómez Ruiz","phone":"600111222","phone_secondary":null,"email":"laura@ejemplo.com","billing_email":null,"tax_id":"12345678Z","address":"C/ Mayor 12","city":"Barcelona","zip":"08001","province":"Barcelona","country":"ES","preferred_language":"es","preferred_contact_method":"whatsapp","marketing_opt_out":false,"channel_opt_out":{"email":false,"sms":false,"whatsapp":false,"call":false}}'
Resposta
{
"id": 1204,
"name": "Laura Gómez",
"phone": "+34600111222",
"phone_secondary": null,
"whatsapp_phone": null,
"email": "laura@ejemplo.com",
"billing_email": null,
"tax_id": "12345678Z",
"address": "C/ Mayor 12",
"city": "Barcelona",
"zip": "08001",
"province": "Barcelona",
"country": "ES",
"preferred_language": "es",
"preferred_contact_method": "whatsapp",
"vip": false,
"marketing_opt_out": false,
"channel_opt_out": {
"email": false,
"sms": false,
"whatsapp": false,
"call": false
},
"erased_at": null,
"vehicles": [
{
"id": 871,
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"km": 84500,
"itv_expiry_date": "2027-03-15",
"status": "activo"
}
]
}
Veículos
GET /api/v1/vehicles vehicles:read
Listar veículos
Inclui a última quilometragem registrada e o vencimento da inspeção técnica (ITV).
Permissão necessária: vehicles:read.
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
plate | string | Não | Placa exata (espaços e hifens são ignorados). |
client_id | integer | Não | Filtrar por cliente. |
status | string [activo, baja_temporal, baja] | Não | Status do veículo. |
limit | integer · default 50 | Não | Resultados por página (1–200). |
cursor | string | Não | Cursor opaco devolvido em next_cursor da página anterior. |
Exemplo
curl "https://sua-oficina.example/api/v1/vehicles" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"data": [
{
"id": 871,
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"km": 84500,
"itv_expiry_date": "2027-03-15",
"status": "activo"
}
],
"next_cursor": "aWQ6MTIzNA",
"has_more": true
}
POST /api/v1/vehicles vehicles:write
Cadastrar um veículo
Sempre em nome de um cliente existente (client_id). A placa é normalizada (maiúsculas, sem espaços nem hifens). Se já estiver no cadastro de OUTRO cliente: 409 vehicle_belongs_to_other_client. Se o mesmo cliente já a tiver: 409 vehicle_exists com existing_id (ou 200 com ?on_conflict=return_existing).
Permissão necessária: vehicles:write.
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
on_conflict | string [error, return_existing] · default error | Não | error (padrão) ou return_existing. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"client_id": 1204,
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"itv_expiry_date": "2027-03-15",
"status": "activo"
}
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/vehicles" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"client_id":1204,"plate":"1234 KLM","vin":"VSSZZZ5FZJR123456","brand":"Seat","model":"León","variant":"1.5 TSI","year":2019,"registration_date":"2019-03-15","fuel":"Gasolina","transmission":"Manual","engine_code":"DADA","horsepower":130,"displacement":"1498","color_code":null,"environmental_label":"C","itv_expiry_date":"2027-03-15","status":"activo"}'
Resposta
{
"id": 871,
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"km": 84500,
"itv_expiry_date": "2027-03-15",
"status": "activo"
}
GET /api/v1/vehicles/{id} vehicles:read
Detalhe de um veículo
Permissão necessária: vehicles:read.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do veículo. |
Exemplo
curl "https://sua-oficina.example/api/v1/vehicles/1234" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"id": 871,
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"km": 84500,
"itv_expiry_date": "2027-03-15",
"status": "activo"
}
PATCH /api/v1/vehicles/{id} vehicles:write
Modificar um veículo
Alterações parciais. client_id não aceita null: um veículo nunca é desvinculado do proprietário pela API (mas pode passar para outro cliente existente).
Permissão necessária: vehicles:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do veículo. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Não | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"client_id": 1204,
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"itv_expiry_date": "2027-03-15",
"status": "activo"
}
Exemplo
curl -X PATCH "https://sua-oficina.example/api/v1/vehicles/1234" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"client_id":1204,"plate":"1234 KLM","vin":"VSSZZZ5FZJR123456","brand":"Seat","model":"León","variant":"1.5 TSI","year":2019,"registration_date":"2019-03-15","fuel":"Gasolina","transmission":"Manual","engine_code":"DADA","horsepower":130,"displacement":"1498","color_code":null,"environmental_label":"C","itv_expiry_date":"2027-03-15","status":"activo"}'
Resposta
{
"id": 871,
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"km": 84500,
"itv_expiry_date": "2027-03-15",
"status": "activo"
}
GET /api/v1/vehicles/{id}/history vehicles:read
Histórico do veículo
Visitas à oficina (todos os orçamentos, exceto os de uso interno, do mais recente ao mais antigo) com status, entrada e saída, quilometragem, valor, nº da fatura e itens das linhas; mais as intervenções registradas em outras oficinas. Nunca inclui custos.
Permissão necessária: vehicles:read.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do veículo. |
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
limit | integer · default 50 | Não | Máximo de visitas (1–200). |
Exemplo
curl "https://sua-oficina.example/api/v1/vehicles/1234/history" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"vehicle": {
"id": 871,
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"plate": "1234 KLM",
"vin": "VSSZZZ5FZJR123456",
"brand": "Seat",
"model": "León",
"variant": "1.5 TSI",
"year": 2019,
"registration_date": "2019-03-15",
"fuel": "Gasolina",
"transmission": "Manual",
"engine_code": "DADA",
"horsepower": 130,
"displacement": "1498",
"color_code": null,
"environmental_label": "C",
"km": 84500,
"itv_expiry_date": "2027-03-15",
"status": "activo"
},
"visits": [
{
"budget_id": 1234,
"status": "Facturado",
"created_at": "2026-10-06T09:30:00.000Z",
"checked_in_at": "2026-09-02T07:30:00.000Z",
"delivered_at": "2026-09-03T16:00:00.000Z",
"km": 84210,
"amount": 245.3,
"invoice": "F26/118",
"category": "Mantenimiento",
"works": [
"Troca de óleo e filtro"
]
}
],
"external_interventions": [
{
"title": "Troca de pneus",
"date": "2025-11-20",
"km": 78000,
"workshop_name": null,
"warranty_until": null
}
]
}
Orçamentos
GET /api/v1/budgets budgets:read
Listar orçamentos
Nunca inclui os orçamentos de uso interno da oficina nem dados de custo. O detalhe (com itens e totais) está em /budgets/{id}.
Permissão necessária: budgets:read.
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
status | string | Não | Status exato, com o valor em espanhol (Pendiente, Enviado, Aprobado, Finalizado, Facturado, Rechazado…). |
client_id | integer | Não | Filtrar por cliente. |
vehicle_id | integer | Não | Filtrar por veículo. |
from | string (date-time) | Não | Criados a partir desta data. |
to | string (date-time) | Não | Criados até esta data. |
updated_since | string (date-time) | Não | Só registros modificados a partir desta data (ISO 8601). |
limit | integer · default 50 | Não | Resultados por página (1–200). |
cursor | string | Não | Cursor opaco devolvido em next_cursor da página anterior. |
Exemplo
curl "https://sua-oficina.example/api/v1/budgets" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"data": [
{
"id": 1234,
"status": "Aprobado",
"created_at": "2026-10-06T09:30:00.000Z",
"updated_at": "2026-10-06T09:30:00.000Z",
"channel": "web",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"subcategory": {
"id": 5,
"name": "Mantenimiento"
},
"assigned_user": {
"id": 3,
"name": "Marta"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"appointment": {
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"status": "confirmed",
"client_confirmed_at": null,
"estimated_duration_minutes": 60,
"box": null
},
"date_in": null,
"date_out": null,
"km": 84500,
"client_reference": null,
"waiting_parts": false,
"on_hold": false,
"hold_until": null,
"client_signed_at": null,
"estimated_ready_at": null,
"delivered_at": null,
"reject_reason": null
}
],
"next_cursor": "aWQ6MTIzNA",
"has_more": true
}
POST /api/v1/budgets budgets:write
Criar um orçamento
Entra como «Pendiente» com canal «API», igual a um cadastro feito no programa (registro, marco de abertura, webhook lead.created). Os totais são calculados no servidor com o imposto da oficina; se um item não trouxer tax_rate, usa o da oficina. O veículo, se informado, deve ser do cliente. Não aceita categorias de uso interno. Com notify_client=true (e permissão communications:send) o cliente recebe a confirmação com o link de acompanhamento.
Permissão necessária: budgets:write.
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"client_id": 1204,
"vehicle_id": 871,
"category_id": 5,
"subcategory_id": 51,
"client_reference": "PED-2026-118",
"public_notes": "Verificar também o ruído da suspensão.",
"lines": [
{
"description": "Troca de óleo e filtro",
"quantity": 1,
"unit_price": 65,
"tax_rate": 21,
"discount_pct": 0,
"line_type": "labor",
"reference": null,
"group_title": null
}
],
"notify_client": false
}
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/budgets" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"client_id":1204,"vehicle_id":871,"category_id":5,"subcategory_id":51,"client_reference":"PED-2026-118","public_notes":"Verificar também o ruído da suspensão.","lines":[{"description":"Troca de óleo e filtro","quantity":1,"unit_price":65,"tax_rate":21,"discount_pct":0,"line_type":"labor","reference":null,"group_title":null}],"notify_client":false}'
Resposta
{
"id": 1234,
"status": "Aprobado",
"created_at": "2026-10-06T09:30:00.000Z",
"updated_at": "2026-10-06T09:30:00.000Z",
"channel": "web",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"subcategory": {
"id": 5,
"name": "Mantenimiento"
},
"assigned_user": {
"id": 3,
"name": "Marta"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"appointment": {
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"status": "confirmed",
"client_confirmed_at": null,
"estimated_duration_minutes": 60,
"box": {
"id": 2,
"name": "Elevador 2"
}
},
"date_in": null,
"date_out": null,
"km": 84500,
"client_reference": null,
"waiting_parts": false,
"on_hold": false,
"hold_until": null,
"client_signed_at": null,
"estimated_ready_at": null,
"delivered_at": null,
"reject_reason": null,
"public_notes": "Verificar também o ruído na suspensão.",
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 5501,
"description": "Troca de óleo e filtro",
"extended_detail": null,
"reference": null,
"line_type": "labor",
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"price_estimated": false,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
]
}
GET /api/v1/budgets/{id} budgets:read
Detalhe de um orçamento
Itens (descrição, quantidade, preço unitário, imposto, tipo, desconto), totais detalhados, agendamento, datas de entrada e saída, responsável e URL pública de acompanhamento.
Permissão necessária: budgets:read.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do orçamento. |
Exemplo
curl "https://sua-oficina.example/api/v1/budgets/1234" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"id": 1234,
"status": "Aprobado",
"created_at": "2026-10-06T09:30:00.000Z",
"updated_at": "2026-10-06T09:30:00.000Z",
"channel": "web",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"subcategory": {
"id": 5,
"name": "Mantenimiento"
},
"assigned_user": {
"id": 3,
"name": "Marta"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"appointment": {
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"status": "confirmed",
"client_confirmed_at": null,
"estimated_duration_minutes": 60,
"box": {
"id": 2,
"name": "Elevador 2"
}
},
"date_in": null,
"date_out": null,
"km": 84500,
"client_reference": null,
"waiting_parts": false,
"on_hold": false,
"hold_until": null,
"client_signed_at": null,
"estimated_ready_at": null,
"delivered_at": null,
"reject_reason": null,
"public_notes": "Verificar também o ruído na suspensão.",
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 5501,
"description": "Troca de óleo e filtro",
"extended_detail": null,
"reference": null,
"line_type": "labor",
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"price_estimated": false,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
]
}
GET /api/v1/budgets/{id}/activity budgets:read
Histórico do orçamento
O que aconteceu no orçamento, do mais recente ao mais antigo: mudanças de status, envios, aceitação (com a origem), agendamentos, mensagens do cliente, faturamento… O mesmo registro que a oficina vê na ficha; public=true marca o que o cliente também vê. Os códigos de uso único e os links de acesso saem ocultos.
Permissão necessária: budgets:read.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do orçamento. |
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
visibility | string [all, public] · default all | Não | all: todo o registro; public: somente o que o cliente vê. |
limit | integer · default 50 | Não | Resultados por página (1–200). |
cursor | string | Não | Cursor opaco devolvido em next_cursor da página anterior. |
Exemplo
curl "https://sua-oficina.example/api/v1/budgets/1234/activity" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"data": [
{
"id": 88123,
"at": "2026-10-06T09:30:00.000Z",
"event": "web_accepted",
"detail": "Orçamento aceito pelo cliente na página de acompanhamento",
"source": "client",
"public": true,
"user": {
"id": 3,
"name": "Marta"
}
}
],
"next_cursor": "aWQ6MTIzNA",
"has_more": true
}
POST /api/v1/budgets/{id}/lines budgets:write
Adicionar um item
Os demais itens mantêm o id. Deixa um instantâneo anterior e registro como qualquer edição no programa. 409 budget_locked se o orçamento estiver Facturado, Facturado externamente, Cancelado, Rechazado, Desistido ou já tiver fatura.
Permissão necessária: budgets:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do orçamento. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"description": "Troca de óleo e filtro",
"quantity": 1,
"unit_price": 65,
"tax_rate": 21,
"discount_pct": 0,
"line_type": "labor",
"reference": null,
"group_title": null
}
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/budgets/1234/lines" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"description":"Troca de óleo e filtro","quantity":1,"unit_price":65,"tax_rate":21,"discount_pct":0,"line_type":"labor","reference":null,"group_title":null}'
Resposta
{
"line": {
"id": 5501,
"description": "Troca de óleo e filtro",
"extended_detail": null,
"reference": null,
"line_type": "labor",
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"price_estimated": false,
"base": 65,
"currency": "EUR",
"sort_order": 0
},
"budget": {
"id": 1234,
"status": "Aprobado",
"created_at": "2026-10-06T09:30:00.000Z",
"updated_at": "2026-10-06T09:30:00.000Z",
"channel": "web",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"subcategory": {
"id": 5,
"name": "Mantenimiento"
},
"assigned_user": {
"id": 3,
"name": "Marta"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"appointment": {
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"status": "confirmed",
"client_confirmed_at": null,
"estimated_duration_minutes": 60,
"box": {
"id": null,
"name": null
}
},
"date_in": null,
"date_out": null,
"km": 84500,
"client_reference": null,
"waiting_parts": false,
"on_hold": false,
"hold_until": null,
"client_signed_at": null,
"estimated_ready_at": null,
"delivered_at": null,
"reject_reason": null,
"public_notes": "Verificar também o ruído na suspensão.",
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 5501,
"description": "Troca de óleo e filtro",
"extended_detail": null,
"reference": null,
"line_type": "labor",
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"price_estimated": false,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
]
}
}
PATCH /api/v1/budgets/{id}/lines/{lineId} budgets:write
Modificar um item
Permissão necessária: budgets:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do orçamento. |
lineId | integer | Sim | Id do item. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Não | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"description": "Troca de óleo e filtro",
"quantity": 1,
"unit_price": 65,
"tax_rate": 21,
"discount_pct": 0,
"line_type": "labor",
"reference": null,
"group_title": null
}
Exemplo
curl -X PATCH "https://sua-oficina.example/api/v1/budgets/1234/lines/5501" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"description":"Troca de óleo e filtro","quantity":1,"unit_price":65,"tax_rate":21,"discount_pct":0,"line_type":"labor","reference":null,"group_title":null}'
Resposta
{
"line": {
"id": 5501,
"description": "Troca de óleo e filtro",
"extended_detail": null,
"reference": null,
"line_type": "labor",
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"price_estimated": false,
"base": 65,
"currency": "EUR",
"sort_order": 0
},
"budget": {
"id": 1234,
"status": "Aprobado",
"created_at": "2026-10-06T09:30:00.000Z",
"updated_at": "2026-10-06T09:30:00.000Z",
"channel": "web",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"subcategory": {
"id": 5,
"name": "Mantenimiento"
},
"assigned_user": {
"id": 3,
"name": "Marta"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"appointment": {
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"status": "confirmed",
"client_confirmed_at": null,
"estimated_duration_minutes": 60,
"box": {
"id": null,
"name": null
}
},
"date_in": null,
"date_out": null,
"km": 84500,
"client_reference": null,
"waiting_parts": false,
"on_hold": false,
"hold_until": null,
"client_signed_at": null,
"estimated_ready_at": null,
"delivered_at": null,
"reject_reason": null,
"public_notes": "Verificar também o ruído na suspensão.",
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 5501,
"description": "Troca de óleo e filtro",
"extended_detail": null,
"reference": null,
"line_type": "labor",
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"price_estimated": false,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
]
}
}
DELETE /api/v1/budgets/{id}/lines/{lineId} budgets:write
Remover um item
Devolve o orçamento com os totais recalculados. O item fica no instantâneo anterior do histórico de versões.
Permissão necessária: budgets:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do orçamento. |
lineId | integer | Sim | Id do item. |
Exemplo
curl -X DELETE "https://sua-oficina.example/api/v1/budgets/1234/lines/5501" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"id": 1234,
"status": "Aprobado",
"created_at": "2026-10-06T09:30:00.000Z",
"updated_at": "2026-10-06T09:30:00.000Z",
"channel": "web",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"subcategory": {
"id": 5,
"name": "Mantenimiento"
},
"assigned_user": {
"id": 3,
"name": "Marta"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"appointment": {
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"status": "confirmed",
"client_confirmed_at": null,
"estimated_duration_minutes": 60,
"box": {
"id": 2,
"name": "Elevador 2"
}
},
"date_in": null,
"date_out": null,
"km": 84500,
"client_reference": null,
"waiting_parts": false,
"on_hold": false,
"hold_until": null,
"client_signed_at": null,
"estimated_ready_at": null,
"delivered_at": null,
"reject_reason": null,
"public_notes": "Verificar também o ruído na suspensão.",
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 5501,
"description": "Troca de óleo e filtro",
"extended_detail": null,
"reference": null,
"line_type": "labor",
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"price_estimated": false,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
]
}
POST /api/v1/budgets/{id}/status budgets:write
Alterar o status
Aceita Pendiente/En cotización/Enviado (antes da aceitação), En curso (orçamento já aceito), Finalizado (a partir de Aprobado, En curso ou En espera) e Cancelado. «Aprobado» responde 403 client_acceptance_required: a aceitação é assinada pelo cliente pelo link que a oficina envia, ou registrada pela sua integração em nome dele com POST /budgets/{id}/accept (permissão budgets:accept). Rejeitar é por POST /budgets/{id}/reject e faturar por POST /budgets/{id}/invoice (permissão invoices:write); aqui respondem 403 status_transition_forbidden, assim como desistir; a partir de Facturado ou Cancelado, 409 budget_locked. «Enviado» exige também communications:send e sent_via: registra que o SEU sistema já o enviou (não o envia). Nenhuma alteração avisa o cliente, exceto Finalizado com notify_client=true e communications:send.
Permissão necessária: budgets:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do orçamento. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"status": "En curso",
"sent_via": "email",
"notify_client": false
}
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/budgets/1234/status" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"status":"En curso","sent_via":"email","notify_client":false}'
Resposta
{
"id": 1234,
"status": "Aprobado",
"created_at": "2026-10-06T09:30:00.000Z",
"updated_at": "2026-10-06T09:30:00.000Z",
"channel": "web",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"subcategory": {
"id": 5,
"name": "Mantenimiento"
},
"assigned_user": {
"id": 3,
"name": "Marta"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"appointment": {
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"status": "confirmed",
"client_confirmed_at": null,
"estimated_duration_minutes": 60,
"box": {
"id": 2,
"name": "Elevador 2"
}
},
"date_in": null,
"date_out": null,
"km": 84500,
"client_reference": null,
"waiting_parts": false,
"on_hold": false,
"hold_until": null,
"client_signed_at": null,
"estimated_ready_at": null,
"delivered_at": null,
"reject_reason": null,
"public_notes": "Verificar também o ruído na suspensão.",
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 5501,
"description": "Troca de óleo e filtro",
"extended_detail": null,
"reference": null,
"line_type": "labor",
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"price_estimated": false,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
]
}
POST /api/v1/budgets/{id}/accept budgets:accept
Aceitar em nome do cliente
Para quando o cliente aceita por outra via (telefone, pessoalmente, seu site…). A evidência é obrigatória: accepted_by e channel (phone, in_person, email, whatsapp, other); note é opcional. Passa pela mesma regra de aceitação do sistema: status Aprobado, transição, dados fiscais mínimos do cliente (se faltarem, 422 fiscal_data_incomplete com missing), desconto de campanha, aviso interno à oficina, confirmação ao cliente conforme os avisos configurados e webhooks lead.accepted e budget.accepted. Somente a partir de «Enviado» (se já estiver aceito responde 200 com already=true); Cancelado, Rechazado, Desistido, Finalizado ou Facturado respondem 409 budget_locked. Se a oficina exigir assinatura, a API aceita mesmo assim e deixa registrado: «sem assinatura, aceito por integração» (signature=waived_by_integration). No histórico fica «Aceito por API em nome do cliente · integração <chave> · <accepted_by> por <canal>».
Permissão necessária: budgets:accept.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do orçamento. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"accepted_by": "Laura Gómez",
"channel": "phone",
"note": "Confirmado por telefone às 10:12"
}
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/budgets/1234/accept" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"accepted_by":"Laura Gómez","channel":"phone","note":"Confirmado por telefone às 10:12"}'
Resposta
{
"budget": {
"id": 1234,
"status": "Aprobado",
"created_at": "2026-10-06T09:30:00.000Z",
"updated_at": "2026-10-06T09:30:00.000Z",
"channel": "web",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"subcategory": {
"id": 5,
"name": "Mantenimiento"
},
"assigned_user": {
"id": 3,
"name": "Marta"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"appointment": {
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"status": "confirmed",
"client_confirmed_at": null,
"estimated_duration_minutes": 60,
"box": null
},
"date_in": null,
"date_out": null,
"km": 84500,
"client_reference": null,
"waiting_parts": false,
"on_hold": false,
"hold_until": null,
"client_signed_at": null,
"estimated_ready_at": null,
"delivered_at": null,
"reject_reason": null,
"public_notes": "Verificar também o ruído na suspensão.",
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 5501,
"description": "Troca de óleo e filtro",
"extended_detail": null,
"reference": null,
"line_type": "labor",
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"price_estimated": false,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
]
},
"already": false,
"signature": "not_required"
}
POST /api/v1/budgets/{id}/reject budgets:accept
Rejeitar em nome do cliente
Com motivo obrigatório. Mesma regra da rejeição do cliente: a partir de Pendiente, En cotización, Enviado ou Aprobado (se o veículo ainda não entrou). Emite lead.rejected e budget.rejected e fica no histórico com o nome da chave.
Permissão necessária: budgets:accept.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do orçamento. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"reason": "Fará em outra oficina",
"rejected_by": "Laura Gómez",
"channel": "phone"
}
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/budgets/1234/reject" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"reason":"Fará em outra oficina","rejected_by":"Laura Gómez","channel":"phone"}'
Resposta
{
"budget": {
"id": 1234,
"status": "Aprobado",
"created_at": "2026-10-06T09:30:00.000Z",
"updated_at": "2026-10-06T09:30:00.000Z",
"channel": "web",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"subcategory": {
"id": 5,
"name": "Mantenimiento"
},
"assigned_user": {
"id": 3,
"name": "Marta"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"appointment": {
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"status": "confirmed",
"client_confirmed_at": null,
"estimated_duration_minutes": 60,
"box": null
},
"date_in": null,
"date_out": null,
"km": 84500,
"client_reference": null,
"waiting_parts": false,
"on_hold": false,
"hold_until": null,
"client_signed_at": null,
"estimated_ready_at": null,
"delivered_at": null,
"reject_reason": null,
"public_notes": "Verificar também o ruído na suspensão.",
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 5501,
"description": "Troca de óleo e filtro",
"extended_detail": null,
"reference": null,
"line_type": "labor",
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"price_estimated": false,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
]
},
"already": false,
"signature": "not_required"
}
POST /api/v1/budgets/{id}/documents budgets:write
Anexar um documento
multipart/form-data com o campo «file» (JPEG, PNG, WebP ou PDF, verificado pelo conteúdo; máximo de 4 MB). Por padrão só a oficina vê; client_visible=true mostra no link de acompanhamento e mechanic_visible=true no app do mecânico. A impressão de idempotência inclui o arquivo.
Permissão necessária: budgets:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do orçamento. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo (multipart/form-data)
| Nome | Tipo | Obrigatório | Descrição |
|---|
file | string (binary) | Sim | Fichero |
client_visible | string [true, false] | Não | |
mechanic_visible | string [true, false] | Não | |
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/budgets/1234/documents" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-F "file=@fichero.pdf" \
-F "client_visible=false" \
-F "mechanic_visible=false"
Resposta
{
"id": 991,
"budget_id": 1234,
"filename": "parte-de-trabajo.pdf",
"content_type": "application/pdf",
"size": 182044,
"url": "https://…/leads/1234/api-parte-de-trabajo.pdf",
"client_visible": false,
"mechanic_visible": false,
"created_at": "2026-10-06T09:30:00.000Z"
}
Faturas
POST /api/v1/budgets/{id}/invoice invoices:write
Faturar um orçamento
Usa o mesmo faturamento do sistema: copia as linhas e o imposto do orçamento, cria o lançamento contábil e, com issue=true (padrão), emite a fatura com a série correspondente, número sequencial, hash encadeado e QR Verifactu. O orçamento passa a Facturado. Fatura-se um Aprobado, En curso, En espera ou Finalizado com valor; se já tiver fatura, devolve-se essa (created=false), nunca uma segunda. Emite invoice.created e invoice.issued. As faturas retificativas não estão disponíveis por API: são feitas no sistema.
Permissão necessária: invoices:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id do orçamento. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"issue": true,
"pay_method": "TARJETA"
}
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/budgets/1234/invoice" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"issue":true,"pay_method":"TARJETA"}'
Resposta
{
"invoice": {
"id": 412,
"number": 87,
"series": "F26",
"full_number": "F2687",
"kind": "invoice",
"rectifies_number": null,
"status": "issued",
"date": "2026-10-06",
"issued_at": "2026-10-06T09:30:00.000Z",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"budget_id": 1234,
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"plate": "1234 KLM",
"km": 84500,
"total": 78.65,
"currency": "EUR",
"payments": {
"paid": 78.65,
"pending": 0,
"settled": true
},
"payment_method": "Tarjeta",
"rebu": false,
"verifactu_hash": "3f9a…",
"registered_externally": false,
"billing": {
"name": "Laura Gómez",
"tax_id": "12345678Z",
"address": "C/ Mayor 12",
"city": "Barcelona",
"zip": "08001",
"province": "Barcelona"
},
"date_in": null,
"date_out": null,
"public_notes": null,
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 9001,
"description": "Troca de óleo e filtro",
"reference": null,
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
],
"payment_list": [
{
"id": 77,
"date": "2026-10-06T09:30:00.000Z",
"amount": 78.65,
"currency": "EUR",
"method": "Tarjeta"
}
]
},
"created": true
}
GET /api/v1/invoices invoices:read
Listar faturas
Faturas emitidas e rascunhos, ordenados por id. Inclui o resumo de recebimentos.
Permissão necessária: invoices:read.
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
from | string (date-time) | Não | Data da fatura a partir de. |
to | string (date-time) | Não | Data da fatura até. |
client_id | integer | Não | Filtrar por cliente. |
status | string [draft, issued, cancelled] | Não | Status da fatura. |
series | string | Não | Série exata. |
limit | integer · default 50 | Não | Resultados por página (1–200). |
cursor | string | Não | Cursor opaco devolvido em next_cursor da página anterior. |
Exemplo
curl "https://sua-oficina.example/api/v1/invoices" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"data": [
{
"id": 412,
"number": 87,
"series": "F26",
"full_number": "F2687",
"kind": "invoice",
"rectifies_number": null,
"status": "issued",
"date": "2026-10-06",
"issued_at": "2026-10-06T09:30:00.000Z",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"budget_id": 1234,
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"plate": "1234 KLM",
"km": 84500,
"total": 78.65,
"currency": "EUR",
"payments": {
"paid": 78.65,
"pending": 0,
"settled": true
},
"payment_method": "Tarjeta",
"rebu": false,
"verifactu_hash": "3f9a…",
"registered_externally": false
}
],
"next_cursor": "aWQ6MTIzNA",
"has_more": true
}
GET /api/v1/invoices/{id} invoices:read
Detalhe de uma fatura
Permissão necessária: invoices:read.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id da fatura. |
Exemplo
curl "https://sua-oficina.example/api/v1/invoices/1234" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"id": 412,
"number": 87,
"series": "F26",
"full_number": "F2687",
"kind": "invoice",
"rectifies_number": null,
"status": "issued",
"date": "2026-10-06",
"issued_at": "2026-10-06T09:30:00.000Z",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"budget_id": 1234,
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"plate": "1234 KLM",
"km": 84500,
"total": 78.65,
"currency": "EUR",
"payments": {
"paid": 78.65,
"pending": 0,
"settled": true
},
"payment_method": "Tarjeta",
"rebu": false,
"verifactu_hash": "3f9a…",
"registered_externally": false,
"billing": {
"name": "Laura Gómez",
"tax_id": "12345678Z",
"address": "C/ Mayor 12",
"city": "Barcelona",
"zip": "08001",
"province": "Barcelona"
},
"date_in": null,
"date_out": null,
"public_notes": null,
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 9001,
"description": "Troca de óleo e filtro",
"reference": null,
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
],
"payment_list": [
{
"id": 77,
"date": "2026-10-06T09:30:00.000Z",
"amount": 78.65,
"currency": "EUR",
"method": "Tarjeta"
}
]
}
GET /api/v1/invoices/{id}/pdf invoices:read
PDF de uma fatura
O mesmo PDF que o programa gera (com QR Verifactu se a fatura estiver emitida). Resposta application/pdf.
Permissão necessária: invoices:read.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id da fatura. |
Exemplo
curl "https://sua-oficina.example/api/v1/invoices/1234/pdf" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
(application/pdf)
POST /api/v1/invoices/{id}/payments invoices:write
Registar um pagamento
Mesmo registro de recebimentos da ficha da fatura: a marca «paga» é recalculada com todos os recebimentos (nunca é forçada) e payment.received é emitido. Somente sobre faturas emitidas. Devolve a fatura com seu resumo de recebimentos.
Permissão necessária: invoices:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | integer | Sim | Id da fatura. |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"amount": 245.3,
"date": "2026-10-13",
"pay_method": "TARJETA",
"notes": "Recebido no balcão"
}
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/invoices/1234/payments" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"amount":245.3,"date":"2026-10-13","pay_method":"TARJETA","notes":"Recebido no balcão"}'
Resposta
{
"id": 412,
"number": 87,
"series": "F26",
"full_number": "F2687",
"kind": "invoice",
"rectifies_number": null,
"status": "issued",
"date": "2026-10-06",
"issued_at": "2026-10-06T09:30:00.000Z",
"client_id": 1204,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"budget_id": 1234,
"vehicle_id": 871,
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"plate": "1234 KLM",
"km": 84500,
"total": 78.65,
"currency": "EUR",
"payments": {
"paid": 78.65,
"pending": 0,
"settled": true
},
"payment_method": "Tarjeta",
"rebu": false,
"verifactu_hash": "3f9a…",
"registered_externally": false,
"billing": {
"name": "Laura Gómez",
"tax_id": "12345678Z",
"address": "C/ Mayor 12",
"city": "Barcelona",
"zip": "08001",
"province": "Barcelona"
},
"date_in": null,
"date_out": null,
"public_notes": null,
"totals": {
"base": 65,
"tax": 13.65,
"total": 78.65,
"currency": "EUR",
"tax_rates": [
{
"rate": 21,
"base": 65,
"quota": 13.65
}
]
},
"lines": [
{
"id": 9001,
"description": "Troca de óleo e filtro",
"reference": null,
"group_title": null,
"quantity": 1,
"unit_price": 65,
"discount_pct": 0,
"tax_rate": 21,
"tax_exempt_code": null,
"base": 65,
"currency": "EUR",
"sort_order": 0
}
],
"payment_list": [
{
"id": 77,
"date": "2026-10-06T09:30:00.000Z",
"amount": 78.65,
"currency": "EUR",
"method": "Tarjeta"
}
]
}
Agendamentos
GET /api/v1/appointments appointments:read
Agendamentos confirmados e propostas
Por padrão, os próximos 30 dias. status=confirmed são agendamentos fixados na agenda; status=proposed são propostas do cliente esperando a confirmação da oficina (bloqueiam o horário).
Permissão necessária: appointments:read.
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
from | string (date-time) | Não | Início do intervalo (padrão: agora). |
to | string (date-time) | Não | Fim do intervalo (padrão: +30 dias, máximo 1 ano). |
status | string [confirmed, proposed] | Não | Só um tipo. |
box_id | integer | Não | Filtrar por elevador/box. |
Exemplo
curl "https://sua-oficina.example/api/v1/appointments" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"data": [
{
"id": "b1234",
"budget_id": 1234,
"status": "confirmed",
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"estimated_duration_minutes": 60,
"client_confirmed_at": null,
"budget_status": "Aprobado",
"checked_in_at": null,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"box": {
"id": 2,
"name": "Elevador 2"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"channel": null,
"proposed_at": null
}
],
"from": "2026-10-06T00:00:00.000Z",
"to": "2026-11-05T00:00:00.000Z"
}
POST /api/v1/appointments appointments:write
Propor ou confirmar um agendamento
Segue o modo de agendamento da oficina (booking_mode em GET /workshop). Em «propose» é criada uma proposta (status=proposed) que bloqueia o horário até a oficina confirmar; pedir mode=book responde 403 booking_mode_propose_only. Em «book» o agendamento fica firme (status=confirmed), a menos que você peça mode=propose. O horário é validado com a mesma lógica de /appointments/availability; se não estiver livre, 409 slot_unavailable com até 3 alternativas em error.alternatives. O cliente não é avisado, exceto com notify_client=true e communications:send.
Permissão necessária: appointments:write.
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Sim | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"budget_id": 1234,
"start": "2026-10-14T09:00:00+02:00",
"box_id": 2,
"duration_minutes": 60,
"mode": "propose",
"notify_client": false
}
Exemplo
curl -X POST "https://sua-oficina.example/api/v1/appointments" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"budget_id":1234,"start":"2026-10-14T09:00:00+02:00","box_id":2,"duration_minutes":60,"mode":"propose","notify_client":false}'
Resposta
{
"id": "b1234",
"budget_id": 1234,
"status": "confirmed",
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"estimated_duration_minutes": 60,
"client_confirmed_at": null,
"budget_status": "Aprobado",
"checked_in_at": null,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"box": {
"id": 2,
"name": "Elevador 2"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"channel": null,
"proposed_at": null
}
GET /api/v1/appointments/availability appointments:read
Horários livres
Mesma lógica da agenda e do site de acompanhamento: horário da oficina e de cada box, almoço, feriados nacionais, regionais e locais, agendamentos abertos e propostas pendentes (que bloqueiam o horário). Inícios a cada 30 min e com pelo menos 1 h de antecedência. Padrão: os próximos 7 dias (máximo 31). Inclui o booking_mode da oficina.
Permissão necessária: appointments:read.
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
from | string (date-time) | Não | De (padrão: agora). |
to | string (date-time) | Não | Até (padrão: +7 dias; máximo 31 dias). |
duration_minutes | integer | Não | Duração do agendamento (15–720). Padrão: a mínima da agenda. |
box_id | integer | Não | Só esse box. |
limit | integer · default 100 | Não | Máximo de horários (1–500). |
Exemplo
curl "https://sua-oficina.example/api/v1/appointments/availability" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"data": [
{
"start": "2026-10-14T07:00:00.000Z",
"end": "2026-10-14T08:00:00.000Z",
"box": {
"id": 2,
"name": "Elevador 2"
}
}
],
"duration_minutes": 60,
"from": "2026-10-14T00:00:00.000Z",
"to": "2026-10-21T00:00:00.000Z",
"booking_mode": "propose"
}
DELETE /api/v1/appointments/{id} appointments:write
Cancelar um agendamento ou retirar uma proposta
b<orçamento>: cancela o agendamento confirmado (igual a «Cancelar agendamento» no cadastro). p<proposta>: retira a proposta pendente; com notify_client=true e communications:send o cliente é convidado a escolher outro horário. Emite appointment.cancelled.
Permissão necessária: appointments:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | string | Sim | Id do agendamento (b1234 ou p88). |
Consulta (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|
notify_client | boolean · default false | Não | Só propostas: avisar o cliente. |
Exemplo
curl -X DELETE "https://sua-oficina.example/api/v1/appointments/b1234" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"ok": true,
"id": "b1234",
"status": "cancelled"
}
GET /api/v1/appointments/{id} appointments:read
Detalhe de uma marcação
Permissão necessária: appointments:read.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | string | Sim | Id do agendamento (b1234 ou p88). |
Exemplo
curl "https://sua-oficina.example/api/v1/appointments/b1234" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Resposta
{
"id": "b1234",
"budget_id": 1234,
"status": "confirmed",
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"estimated_duration_minutes": 60,
"client_confirmed_at": null,
"budget_status": "Aprobado",
"checked_in_at": null,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"box": {
"id": 2,
"name": "Elevador 2"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"channel": null,
"proposed_at": null
}
PATCH /api/v1/appointments/{id} appointments:write
Mover uma marcação ou alterar uma proposta
b<orçamento>: move o agendamento confirmado para o novo horário (somente se a oficina trabalha no modo «reservar»; no modo «propor» responde 403 booking_mode_propose_only: crie uma proposta com POST /appointments). p<proposta>: retira a proposta e cria outra no novo horário (o id muda). O horário é validado como ao criar (409 slot_unavailable com alternativas). Emite appointment.updated.
Permissão necessária: appointments:write.
Parâmetros
| Nome | Tipo | Obrigatório | Descrição |
|---|
id | string | Sim | Id do agendamento (b1234 ou p88). |
Cabeçalhos
| Nome | Tipo | Obrigatório | Descrição |
|---|
Idempotency-Key | string | Não | Chave única por operação (UUID recomendado). Repeti-la com o mesmo corpo em 24 h devolve a resposta guardada com Idempotent-Replay: true; com outro corpo, 409 idempotency_conflict. |
Corpo
{
"start": "2026-10-15T10:00:00+02:00",
"box_id": 2,
"duration_minutes": 60,
"notify_client": false
}
Exemplo
curl -X PATCH "https://sua-oficina.example/api/v1/appointments/b1234" \
-H "Authorization: Bearer pt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"start":"2026-10-15T10:00:00+02:00","box_id":2,"duration_minutes":60,"notify_client":false}'
Resposta
{
"id": "b1234",
"budget_id": 1234,
"status": "confirmed",
"start": "2026-10-06T09:30:00.000Z",
"end": "2026-10-06T10:30:00.000Z",
"estimated_duration_minutes": 60,
"client_confirmed_at": null,
"budget_status": "Aprobado",
"checked_in_at": null,
"client": {
"id": 1204,
"name": "Laura Gómez"
},
"vehicle": {
"id": 871,
"plate": "1234 KLM",
"brand": "Seat",
"model": "León"
},
"mechanic": {
"id": 3,
"name": "Marta"
},
"box": {
"id": 2,
"name": "Elevador 2"
},
"category": {
"id": 5,
"name": "Mantenimiento"
},
"channel": null,
"proposed_at": null
}