API de integração (ERP)
Guia para quem integra um ERP ou TMS ao Autorizee. A API deixa o sistema da empresa emitir e acompanhar autorizações de abastecimento, manter viagens, motoristas, veículos, postos e usuários e ler os catálogos, sem usar o portal. Ela substitui a API da versão anterior do Autorizee.
1. Visão geral
| Item | Valor |
|---|---|
| Host | Autorizee.Integracao.Api (host próprio, separado do portal) |
| URL base | https://<host-da-integracao>/api/v1 (em desenvolvimento, https://localhost:7268/api/v1 ou http://localhost:5187/api/v1) |
| Versão | v1 no caminho. Mudança que quebra o contrato vira v2; a v1 não muda de forma incompatível |
| Formato | JSON em UTF-8, nomes em camelCase |
| Autenticação | Token da empresa em Authorization: Bearer <token> |
| Documentação interativa | /swagger e /openapi/v1.json (liberados também em produção; no Swagger, informe o token em "Authorize" para testar as chamadas) |
A empresa é sempre a do token. Nenhuma ação recebe o identificador da empresa, e uma autorização, viagem ou cadastro de outra empresa responde como não localizado.
2. Autenticação
Cada empresa tem um token de integração. Quem gerencia é o administrador da empresa (ou o backoffice), na tela da empresa, com três ações:
| Ação | Efeito |
|---|---|
| Habilitar | Liga a integração e gera o token. Se já estava habilitada, mostra o token atual |
| Regenerar | Gera outro token; o anterior deixa de valer na hora |
| Desabilitar | Desliga a integração e apaga o token; toda chamada passa a responder 401 |
O token é o mesmo TokenApi que a empresa já tinha na versão anterior (a migração o preservou). Quem só vê o token é quem tem a permissão de consultá-lo.
Envie o token em todas as chamadas:
Authorization: Bearer 3f2b8c1e-9d4a-4a57-8f0e-5c6d7e8f9a0b
Não existe mais certificado de cliente, autenticação Basic nem o token temporário de api/Autenticacao com ?token=.
Responde 401 ({ "success": false, "message": "..." }) quando falta o cabeçalho, o esquema não é Bearer, o token é desconhecido, está desabilitado ou passa de 200 caracteres. A API não diz qual dos casos ocorreu.
Guarde o token como segredo (variável de ambiente ou cofre do ERP). Ele dá acesso a tudo que a empresa faz pela integração.
3. Formato das respostas e códigos HTTP
Toda resposta usa o mesmo envelope:
{ "success": true, "data": { "numero": 1201, "status": 1 } }
{ "success": false, "message": "Não foi possível localizar um motorista ativo na empresa com o CPF 12345678909." }
data e message saem do JSON quando vazios: uma consulta que não acha nada (viagem de uma autorização sem viagem) volta { "success": true }. Enums são números (tabela abaixo); datas são ISO 8601 (2026-11-05 na validade da autorização, 2026-11-05T08:00:00 nas viagens).
| HTTP | Quando |
|---|---|
| 200 | Sucesso |
| 400 | Corpo inválido ou regra de negócio recusou (a message explica) |
| 401 | Sem token, token inválido ou desabilitado |
| 404 | Autorização, viagem ou cadastro não existe ou é de outra empresa |
| 500 | Falha inesperada do servidor. A mensagem não traz detalhe interno |
Diferente da versão anterior, o erro não volta com HTTP 200. Confira o código HTTP, não só success.
Armadilha conhecida: em POST sem corpo (vincular posto), não envie Content-Type: application/json. Com esse cabeçalho e corpo vazio a API responde 400 "corpo não é JSON válido".
Enums
| Campo | Valores |
|---|---|
tipo (autorização) | 1 Abastecimento tração, 2 Abastecimento equipamento |
status (autorização) | 1 Pendente, 2 Validado, 3 Concluído, 4 Cancelado, 5 Bloqueado, 6 Com divergência de valor |
status (viagem) | 1 Ativa, 2 Cancelada, 3 Concluída |
tipoFrota | 1 Própria, 2 Agregado, 3 Terceiro |
grupo (produto) | 1 Combustível, 2 Aditivo |
tipo (usuário) | 3 Usuário Empresa, 4 Gestor Empresa |
4. Identificadores
| Coisa | Como identificar | Exemplo |
|---|---|---|
| Autorização | número (o Id da versão anterior, preservado) | /autorizacoes/1201 |
| Viagem | número | /viagens/87 |
| Produto, marca, modelo, categoria da CNH | id numérico dos catálogos | "produto": 3 |
| Veículo | placa (maiúsculas, sem espaço) | ABC1D23 |
| Motorista e usuário | CPF | 12345678909 |
| Posto | CNPJ | 12345678000190 |
CPF e CNPJ valem com ou sem máscara no corpo (123.456.789-09 ou 12345678909). No caminho da URL, só dígitos, porque a barra do CNPJ quebra a rota. As respostas devolvem CPF, CNPJ e placa só com dígitos e letras, como gravados.
Autorização e viagem também trazem um uuid (identificador interno estável). As ações usam o numero.
5. Autorizações
Rotas em /api/v1/autorizacoes.
| Rota | Verbo | Para que serve |
|---|---|---|
/ | POST | Registrar (emitir) autorização |
/{numero} | GET | Consultar com os produtos |
/{numero}/situacao | GET | Situação ({ numero, status }) |
/{numero}/permite-alteracao | GET | true se está Pendente |
/{numero}/validade | PUT | Trocar a validade (Pendente) |
/{numero}/cancelar | POST | Cancelar (Pendente) |
/{numero}/atender-solicitacao | POST | Aprovar ou negar a solicitação de alteração do posto |
/validacoes-pendentes | GET | Fila: validadas e não lidas (até 100) |
/estornos-validacao-pendentes | GET | Fila: validação estornada e não lida (até 100) |
/conclusoes-pendentes | GET | Fila: concluídas e não lidas (até 500) |
/solicitacoes-alteracao-pendentes | GET | Autorizações com solicitação de alteração pendente (sem limite) |
/validacoes-pendentes/confirmar | POST | Confirmar leitura da fila de validações |
/estornos-validacao-pendentes/confirmar | POST | Confirmar leitura da fila de estornos |
/conclusoes-pendentes/confirmar | POST | Confirmar leitura da fila de conclusões |
5.1 Registrar autorização
POST /api/v1/autorizacoes
| Campo | Tipo | Obrigatório | Observação |
|---|---|---|---|
tipo | número | sim | 1 ou 2 |
viagem | número | não | Número da viagem; com ele, sequenciaViagem é obrigatória |
sequenciaViagem | inteiro | com viagem | Posição da autorização na viagem |
dataValidade | data yyyy-MM-dd | sim | Só a data conta |
placa | texto (até 20) | sim | Veículo ativo na empresa |
cpfMotorista | texto (até 14) | sim | Motorista ativo na empresa |
cnpjPosto | texto (até 18) | sim | Posto com vínculo ativo com a empresa |
cpfUsuario | texto (até 14) | sim | Usuário ativo da empresa que emite |
numeroCliente | texto (até 20) | não | Seu número interno; volta na resposta |
produtos | lista | sim | Ver abaixo |
Cada item de produtos:
| Campo | Tipo | Observação |
|---|---|---|
produto | número | id do catálogo de produtos |
completar | booleano | true completa o tanque (limites ignorados) |
quantidade | decimal | Limite de quantidade |
valor | decimal | Limite de valor |
Regras e mensagens principais:
- Sem
completar, informequantidadee/ouvalor(ao menos um): "O produto {n} foi marcado para limitar a quantidade ou valores abastecidos, porém não foi especificado pelo menos um destes limites." - Produto inexistente: "Não foi possível localizar um produto {n} no autorizee."
- "Não foi informado a sequência da autorização dentro da viagem." (viagem sem sequência)
- "Não foi possível localizar um usuário ativo com o CPF {cpf}."
- "Não foi possível localizar um motorista ativo na empresa com o CPF {cpf}."
- "Não foi possível localizar um veículo ativo na empresa com a placa {placa}."
- "Não foi possível localizar um posto com CNPJ {cnpj}, vinculado a empresa."
- Viagem que não existe (ou é de outra empresa): 404 "Viagem não foi localizado(a)."
- Com viagem, o veículo precisa ser a tração ou o reboque dela: "O veículo informado na autorização é diferente do veículo registrado na viagem informada, seja ele tração ou reboque."
- As demais validações são as do portal: validade não pode ser anterior à data atual, produto repetido, capacidade do veículo, celular do motorista quando o grupo exige token.
A autorização nasce Pendente, com origem integração (origemPortal: false). A resposta é a autorização completa (seção 5.2) com status, usuarioEmissaoNome e produtos.
5.2 Resposta de autorização
numero, uuid, status, tipo, tipoFrota, dataEmissao, dataValidade, dataValidacao, dataBaixa, placa, cpfMotorista, nomeMotorista, cnpjPosto, nomePosto, numeroCliente, numeroProtocolo, numeroComprovanteBaixa, valorMarcador, usuarioEmissaoNome, usuarioValidacaoNome, usuarioBaixaNome, origemPortal, automatica, utilizaToken, divergenciaValor, motivoDivergencia, dataAprovacaoDivergencia, observacaoAprovacaoDivergencia, quantidadeArquivos, justificativaSolicitacaoAlteracao (só com solicitação pendente) e produtos.
Cada produto: produto, nome, unidadeMedida, completar, quantidade, valor, quantidadeAbastecida, valorAbastecido, naoUtilizado, divergenciaValor, motivoDivergencia.
5.3 Consultas, validade, cancelamento e solicitação
- Consultar (
GET /{numero}): a autorização com os produtos. Não tem efeito colateral. - Situação (
GET /{numero}/situacao):{ "numero": 1201, "status": 3 }. Atenção: consultar a situação de uma autorização Concluída ainda não lida a marca como lida na fila de conclusões (igual aa versão anterior). Para só olhar, useGET /{numero}. - Permite alteração:
dataétruese a autorização está Pendente. - Validade (
PUT /{numero}/validade, corpo{ "dataValidade": "2026-11-20" }): só Pendente; senão "Não é possível alterar a autorização {n}." Não há outra validação da data nem histórico. - Cancelar (
POST /{numero}/cancelar, corpo{ "cpfUsuario": "...", "motivo": "..." }): só Pendente; motivo obrigatório (até 500). A autorização nunca é excluída, só cancelada. A integração cancela também a autorização criada no portal e a que está em viagem. - Atender solicitação (
POST /{numero}/atender-solicitacao, corpo{ "cpfUsuario": "...", "permitir": true }): o posto pede a alteração de uma autorização Concluída;permitir: trueestorna a conclusão (a autorização volta a Validada) efalsesó encerra a solicitação. Lista das pendentes:GET /solicitacoes-alteracao-pendentes.
Cancelar e atender aceitam usuário da empresa em qualquer situação (ativo ou não); só a emissão exige usuário ativo.
5.4 Filas e confirmação de leitura
As filas dizem ao ERP o que mudou no posto. O ciclo é sempre o mesmo:
- Ler a fila (
GET). A leitura é repetível: sem confirmar, a mesma lista volta. - Processar cada autorização no ERP (baixar a conclusão, registrar a validação...).
- Confirmar com os números processados (
POST .../confirmar, corpo{ "numeros": [1201, 1202] }). A resposta é{ "quantidade": 2 }: quantas foram marcadas. Números de outra empresa ou que não estão na fila são ignorados e não contam. - Na próxima leitura, só vêm as ainda não confirmadas. Fila maior que o limite: confirme o lote e leia de novo.
| Fila | Entra quando | Limite |
|---|---|---|
validacoes-pendentes | Validada e ainda não lida | 100 |
estornos-validacao-pendentes | Voltou a Pendente por estorno da validação e o estorno não foi lido | 100 |
conclusoes-pendentes | Concluída e ainda não lida | 500 |
As filas saem ordenadas pelo número. Confirmar lista vazia responde { "quantidade": 0 }.
Limitações que valem saber:
- Autorização em Divergência de valor não entra em nenhuma fila até a aprovação (vira Concluída). Antes disso, acompanhe por
GET /{numero}ou/situacao. - Autorização que volta a Validada pelo estorno da conclusão (solicitação aprovada) não reaparece na fila de validações se a validação anterior já foi lida.
solicitacoes-alteracao-pendentesnão tem confirmação: sai da lista quando você atende a solicitação.
5.5 Exemplos
Registrar uma autorização:
curl -s -X POST "$BASE/api/v1/autorizacoes" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"tipo": 1,
"dataValidade": "2026-11-05",
"placa": "ABC1D23",
"cpfMotorista": "123.456.789-09",
"cnpjPosto": "12.345.678/0001-90",
"cpfUsuario": "98765432100",
"numeroCliente": "PED-4471",
"produtos": [
{ "produto": 3, "completar": false, "quantidade": 300 },
{ "produto": 7, "completar": true }
]
}'
{ "success": true, "data": { "numero": 1201, "status": 1, "numeroCliente": "PED-4471", "produtos": [ ... ] } }
Ler e confirmar a fila de conclusões:
curl -s "$BASE/api/v1/autorizacoes/conclusoes-pendentes" \
-H "Authorization: Bearer $TOKEN"
curl -s -X POST "$BASE/api/v1/autorizacoes/conclusoes-pendentes/confirmar" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "numeros": [1201, 1202] }'
{ "success": true, "data": { "quantidade": 2 } }
6. Viagens
Rotas em /api/v1/viagens.
| Rota | Verbo | Para que serve |
|---|---|---|
/ | POST | Registrar viagem (nasce Ativa) |
/{numero} | PUT | Alterar viagem Ativa |
/{numero} | GET | Consultar com as autorizações |
/{numero}/cancelar | POST | Cancelar viagem Ativa e suas autorizações |
/autorizacao/{autorizacao} | GET | Viagem de uma autorização (pelo número) |
Corpo de registrar e de alterar (o mesmo):
| Campo | Tipo | Obrigatório |
|---|---|---|
descricao | texto (até 200) | sim |
numeroInternoCliente | texto (até 20) | não |
cpfMotorista | texto | sim (motorista ativo) |
placaVeiculoTracao | texto | sim (veículo ativo) |
placaVeiculoReboque | texto | não (veículo ativo) |
dataInicioViagem | data e hora | sim |
dataFimViagem | data e hora | não |
origem, destino | texto (até 500) | sim |
latitudeOrigem, longitudeOrigem | decimal | não; só valem juntas |
latitudeDestino, longitudeDestino | decimal | não; só valem juntas |
pesoTotalCarga | decimal | não |
Regras principais:
- Não há rota do Google: origem e destino são texto, e as coordenadas são só as que você enviar (latitude de -90 a 90, longitude de -180 a 180; fora disso, "Não foi possível converter em coordenadas geográficas os valores de latitude e longitude de origem informados.").
- Alterar regrava todos os campos: o que você omitir fica vazio, inclusive as coordenadas. Envie sempre a viagem inteira. As autorizações já vinculadas não mudam.
- Só a viagem Ativa se altera: "O status atual da viagem é Cancelada, e não permite a alteração."
- As autorizações entram na viagem pela emissão com
viagemesequenciaViagem(seção 5.1). - Cancelar (
{ "cpfUsuario": "...", "motivo": "..." }): cancela a viagem e todas as suas autorizações, que precisam estar Pendentes ou Canceladas (de qualquer origem). Com autorização já validada ou concluída, a viagem não cancela. GET /autorizacao/{autorizacao}: a viagem com todas as autorizações dela; sem viagem,{ "success": true }semdata.
Resposta: numero, uuid, status, descricao, numeroInternoCliente, dataInicioViagem, dataFimViagem, origem, destino, latitudeOrigem, longitudeOrigem, latitudeDestino, longitudeDestino, pesoTotalCarga, nomeMotorista, placaTracao, placaReboque e autorizacoes (cada uma com sequencia, numero, status, tipo, dataValidade, numeroCliente, placa, nomePosto, origemPortal).
7. Motoristas
Rotas em /api/v1/motoristas.
| Rota | Verbo | Para que serve |
|---|---|---|
/cpf/{cpf}/existe | GET | true se a empresa tem o motorista ativo |
/ | POST | Incluir (vincular) o motorista à empresa |
Corpo de incluir: nome (obrigatório), cpf (obrigatório, válido), rg, siglaEstadoRg (UF do RG), cnh, categoriaCnh (id da categoria), ddiCelular, dddCelular, numeroCelular.
Regras principais:
- CPF inválido é recusado; o CPF é gravado só com dígitos.
- Se o CPF já existe no Autorizee (cadastrado por outra empresa), o cadastro é reaproveitado e os dados pessoais são sobrescritos pelos que você enviou (comportamento da versão anterior e do portal). Cria ou reativa o vínculo com a empresa.
- Vínculo ativo da própria empresa: 400 "Motorista '{cpf}' já está cadastrado(a)."
siglaEstadoRgouddiCelulardesconhecidos ficam vazios, sem erro. Categoria da CNH inexistente: 404.- Resposta:
{ cpf, nome, ativo }.
8. Veículos
Rotas em /api/v1/veiculos.
| Rota | Verbo | Para que serve |
|---|---|---|
/placa/{placa}/existe | GET | true se a empresa tem o veículo ativo |
/ | POST | Incluir (vincular) o veículo à empresa |
Corpo de incluir: placa (obrigatória), tipoFrota (obrigatório, 1 a 3), marca e modelo (id dos catálogos), anoFabricacao.
Regras principais:
- A placa é única no Autorizee: se outra empresa já cadastrou o veículo, ele é reaproveitado e só o vínculo com a sua empresa é criado.
- Vínculo inativo da sua empresa é reativado com os dados novos; vínculo ativo: 400 "Veículo '{placa}' já está cadastrado(a)."
- Marca ou modelo inexistente: 404. Modelo de outra marca: 400 "O modelo informado não pertence à marca informada."
- Resposta:
{ placa, tipoFrota, marca, modelo, anoFabricacao, ativo }. Capacidades e marcadores ficam no portal.
9. Postos
Rotas em /api/v1/postos, sempre pelo CNPJ (só dígitos no caminho).
| Rota | Verbo | Para que serve |
|---|---|---|
/cnpj/{cnpj}/credenciado | GET | true se o posto existe no Autorizee (de qualquer empresa) |
/cnpj/{cnpj}/vinculado | GET | true se o posto tem vínculo ativo com a empresa |
/cnpj/{cnpj}/vincular | POST | Vincula o posto à empresa (sem corpo) |
Regras principais:
- Posto inexistente: 400 "Não foi possível localizar um posto com o cnpj {cnpj}."; vínculo ativo já existente: 400.
- Vínculo inativo é reativado em vez de criar outro.
- Não há aceite do posto: a empresa vincula qualquer posto credenciado só pelo CNPJ.
dataétruequando vincula.
curl -s -X POST "$BASE/api/v1/postos/cnpj/12345678000190/vincular" \
-H "Authorization: Bearer $TOKEN"
10. Usuários
Rotas em /api/v1/usuarios.
| Rota | Verbo | Para que serve |
|---|---|---|
/ | GET | Usuários com acesso à empresa, por nome |
/cpf/{cpf}/existe | GET | true se há usuário da empresa com o CPF (qualquer situação) |
/ | POST | Convidar usuário para a empresa |
Corpo de convidar: nome, cpf, email (obrigatórios), dddCelular, numeroCelular e tipo (obrigatório: 3 Usuário Empresa ou 4 Gestor Empresa; outro valor: "Não é permitido criar um usuário para a empresa com o tipo informado.").
Regras principais:
- É um convite do Sistema: o usuário recebe um e-mail para definir a senha e fica
ativo: falseaté confirmar. Só usuário ativo emite autorização. - O tipo vira o nível padrão correspondente (Usuário Empresa ou Gestor Empresa).
- E-mail já cadastrado no Sistema só ganha o acesso à sua empresa.
- Resposta:
{ nome, email, cpf, celular, ativo, niveis }. Nunca traz senha, hash ou token.
11. Catálogos
Rotas em /api/v1/catalogos, só leitura, globais (iguais para todas as empresas), por nome.
| Rota | Retorno |
|---|---|
GET /marcas | [{ id, nome }] |
GET /modelos?marca={id} | [{ id, nome, marca, capacidadeMaximaTracao }] (marca opcional: sem ela, todos) |
GET /produtos | [{ id, nome, grupo, unidadeMedida }] |
Use os id nas ações que pedem produto, marca, modelo. Não há rota de categorias da CNH: categoriaCnh recebe o id numérico da categoria que a versão anterior já usava.
12. Log das requisições
Cada requisição é gravada na tabela IntegracaoRequisicao do banco do Cliente, para suporte e auditoria:
| Coluna | Conteúdo |
|---|---|
Locatario | Empresa do token (vazio se não autenticou: as 401 também ficam no log) |
DataRegistro, DuracaoMs | Hora do servidor e duração |
Metodo, Caminho | Verbo e caminho com a query string |
StatusCode, IpCliente | Código HTTP e IP |
CorpoRequisicao, CorpoResposta | Corpo em texto (JSON, XML, texto, formulário) |
O log nunca grava cabeçalhos (nem o token). Corpo acima de 1.000.000 de caracteres é truncado com …[truncado]. Não são gravados /health, /openapi*, /swagger* e OPTIONS. Falha ao gravar o log não afeta a resposta. Como o corpo vai inteiro, não mande no JSON dado que não pode ser guardado.
13. Limites
| Limite | Valor |
|---|---|
| Fila de validações | 100 por leitura |
| Fila de estornos da validação | 100 por leitura |
| Fila de conclusões | 500 por leitura |
| Solicitações de alteração pendentes | sem limite |
| Tamanho do token | 200 caracteres |
| Corpo guardado no log | 1.000.000 de caracteres |
Não há limite de requisições por empresa (nem por tempo): evite consultar as filas em laço apertado; um intervalo de alguns segundos a minutos basta.