Download OpenAPI specification:
API para sistemas de gestão de oficina enviarem ordens de serviço (O.S.) para a Rota.
Cada envio cria ou atualiza a O.S. identificada por externalOrderId (upsert).
A Rota gera um token para a integração e o entrega ao parceiro. Para pedir um token ou tirar dúvidas: geral@rotaautotech.com.br. O token vale para as oficinas liberadas nele. Envie-o em um dos cabeçalhos:
X-Partner-Token: {token}Authorization: Bearer {token}Token na URL (query ou path) não é aceito. Guarde o token como segredo: quem tem o token envia O.S. em nome das oficinas liberadas.
Limite: 120 requisições por minuto por token. Acima disso a resposta é 429.
externalOrderId: identificador estável da O.S. no seu sistema (até 80 caracteres).status: open (aberta) ou closed (fechada).customer.name: nome do cliente.closedOn: quando a O.S. é fechada neste envio (criada já fechada, ou aberta → fechada).Os demais campos são opcionais. Campo sem valor pode vir ausente, vazio ("") ou 0.
status: open. A resposta é 201 com o serviceOrderId e o number
I-{externalOrderId}.externalOrderId com status: closed e closedOn.
A resposta é 200, com o mesmo serviceOrderId e o mesmo number.status: open e sem closedOn.O último status enviado vale. Só a O.S. fechada inicia o pós-venda (pesquisa por WhatsApp) e a agenda de revisão. Reenviar uma O.S. já fechada atualiza os dados e não repete a pesquisa.
Datas em ISO 8601 com fuso (2026-09-15T13:00:00Z ou 2026-09-15T10:00:00-03:00).
openedOn: vale a data de fechamento (O.S. fechada) ou o momento do recebimento (O.S. aberta).closedOn anterior a openedOn é rejeitado (400). Datas a mais de 12 horas no futuro também.customer.whatsApp não há pesquisa de pós-venda.vehicle.licensePlate a O.S. fica sem veículo e sem revisão. A placa, se enviada, tem 7 caracteres.A O.S. fica ligada ao token que a criou. Outro token que envia o mesmo externalOrderId
para a mesma oficina recebe 409.
Todo erro tem o corpo { "code", "message", "fieldErrors" }.
| HTTP | code | Quando |
|---|---|---|
| 400 | VALIDATION_ERROR |
Campo obrigatório ausente ou valor inválido. fieldErrors lista o campo e o motivo. |
| 400 | INVALID_PAYLOAD |
Corpo que não é JSON válido ou com tipo errado (ex.: data inválida). |
| 401 | UNAUTHORIZED |
Token ausente, inválido ou expirado. |
| 403 | FORBIDDEN |
Token sem permissão para a oficina (shopId). |
| 409 | CONFLICT |
O número I-{externalOrderId} já existe na oficina e não pertence a este token. |
| 429 | RATE_LIMITED |
Mais de 120 requisições por minuto no token. Aguarde e reenvie. |
Em 400, 401, 403 e 409 não reenvie sem corrigir. Em 429 e 5xx, reenvie com espera
crescente: o upsert torna o reenvio seguro.
Upsert pela chave externalOrderId dentro da oficina e do token. Primeiro envio cria (201); os seguintes atualizam (200).
| shopId required | integer <int32> Id da oficina na Rota, informado junto com o token. |
| externalOrderId required | string <= 80 characters Identificador estável da O.S. no seu sistema. Chave do upsert. |
| status required | string Enum: "open" "closed"
|
| openedOn | string or null <date-time> Abertura da O.S. Ausente na criação: data de fechamento (O.S. fechada) ou momento do recebimento (O.S. aberta). Ausente no reenvio: mantém a gravada. |
| closedOn | string or null <date-time> Obrigatório ao fechar (criação fechada ou aberta → fechada). Ausente no reenvio de O.S. já fechada: mantém a gravada. Não pode ser anterior a |
| observation | string |
| commercialNumber | string <= 80 characters Número da O.S. exibido no seu sistema. Informativo; a chave continua |
| total | number <double> Valor total da O.S. |
| km | integer Quilometragem na O.S. |
required | object (PublicCustomer) |
object (PublicVehicle) | |
object (PublicStaff) | |
object (PublicStaff) | |
Array of objects (PublicServiceOrderItem) |
{- "externalOrderId": "OS-1001",
- "status": "open",
- "customer": {
- "name": "Cliente Exemplo"
}
}{- "serviceOrderId": 123456,
- "externalOrderId": "OS-1001",
- "number": "I-OS-1001",
- "status": "closed",
- "created": false
}