Pular para o conteúdo principal

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​

ItemValor
HostAutorizee.Integracao.Api (host próprio, separado do portal)
URL basehttps://<host-da-integracao>/api/v1 (em desenvolvimento, https://localhost:7268/api/v1 ou http://localhost:5187/api/v1)
Versãov1 no caminho. Mudança que quebra o contrato vira v2; a v1 não muda de forma incompatível
FormatoJSON em UTF-8, nomes em camelCase
AutenticaçãoToken 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çãoEfeito
HabilitarLiga a integração e gera o token. Se já estava habilitada, mostra o token atual
RegenerarGera outro token; o anterior deixa de valer na hora
DesabilitarDesliga 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).

HTTPQuando
200Sucesso
400Corpo inválido ou regra de negócio recusou (a message explica)
401Sem token, token inválido ou desabilitado
404Autorização, viagem ou cadastro não existe ou é de outra empresa
500Falha 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​

CampoValores
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
tipoFrota1 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​

CoisaComo identificarExemplo
Autorizaçãonúmero (o Id da versão anterior, preservado)/autorizacoes/1201
Viagemnúmero/viagens/87
Produto, marca, modelo, categoria da CNHid numérico dos catálogos"produto": 3
Veículoplaca (maiúsculas, sem espaço)ABC1D23
Motorista e usuárioCPF12345678909
PostoCNPJ12345678000190

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.

RotaVerboPara que serve
/POSTRegistrar (emitir) autorização
/{numero}GETConsultar com os produtos
/{numero}/situacaoGETSituação ({ numero, status })
/{numero}/permite-alteracaoGETtrue se está Pendente
/{numero}/validadePUTTrocar a validade (Pendente)
/{numero}/cancelarPOSTCancelar (Pendente)
/{numero}/atender-solicitacaoPOSTAprovar ou negar a solicitação de alteração do posto
/validacoes-pendentesGETFila: validadas e não lidas (até 100)
/estornos-validacao-pendentesGETFila: validação estornada e não lida (até 100)
/conclusoes-pendentesGETFila: concluídas e não lidas (até 500)
/solicitacoes-alteracao-pendentesGETAutorizações com solicitação de alteração pendente (sem limite)
/validacoes-pendentes/confirmarPOSTConfirmar leitura da fila de validações
/estornos-validacao-pendentes/confirmarPOSTConfirmar leitura da fila de estornos
/conclusoes-pendentes/confirmarPOSTConfirmar leitura da fila de conclusões

5.1 Registrar autorização​

POST /api/v1/autorizacoes

CampoTipoObrigatórioObservação
tiponúmerosim1 ou 2
viagemnúmeronãoNúmero da viagem; com ele, sequenciaViagem é obrigatória
sequenciaViageminteirocom viagemPosição da autorização na viagem
dataValidadedata yyyy-MM-ddsimSó a data conta
placatexto (até 20)simVeículo ativo na empresa
cpfMotoristatexto (até 14)simMotorista ativo na empresa
cnpjPostotexto (até 18)simPosto com vínculo ativo com a empresa
cpfUsuariotexto (até 14)simUsuário ativo da empresa que emite
numeroClientetexto (até 20)nãoSeu número interno; volta na resposta
produtoslistasimVer abaixo

Cada item de produtos:

CampoTipoObservação
produtonúmeroid do catálogo de produtos
completarbooleanotrue completa o tanque (limites ignorados)
quantidadedecimalLimite de quantidade
valordecimalLimite de valor

Regras e mensagens principais:

  • Sem completar, informe quantidade e/ou valor (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, use GET /{numero}.
  • Permite alteração: data é true se 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: true estorna a conclusão (a autorização volta a Validada) e false só 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:

  1. Ler a fila (GET). A leitura é repetível: sem confirmar, a mesma lista volta.
  2. Processar cada autorização no ERP (baixar a conclusão, registrar a validação...).
  3. 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.
  4. Na próxima leitura, só vêm as ainda não confirmadas. Fila maior que o limite: confirme o lote e leia de novo.
FilaEntra quandoLimite
validacoes-pendentesValidada e ainda não lida100
estornos-validacao-pendentesVoltou a Pendente por estorno da validação e o estorno não foi lido100
conclusoes-pendentesConcluída e ainda não lida500

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-pendentes nã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.

RotaVerboPara que serve
/POSTRegistrar viagem (nasce Ativa)
/{numero}PUTAlterar viagem Ativa
/{numero}GETConsultar com as autorizações
/{numero}/cancelarPOSTCancelar viagem Ativa e suas autorizações
/autorizacao/{autorizacao}GETViagem de uma autorização (pelo número)

Corpo de registrar e de alterar (o mesmo):

CampoTipoObrigatório
descricaotexto (até 200)sim
numeroInternoClientetexto (até 20)não
cpfMotoristatextosim (motorista ativo)
placaVeiculoTracaotextosim (veículo ativo)
placaVeiculoReboquetextonão (veículo ativo)
dataInicioViagemdata e horasim
dataFimViagemdata e horanão
origem, destinotexto (até 500)sim
latitudeOrigem, longitudeOrigemdecimalnão; só valem juntas
latitudeDestino, longitudeDestinodecimalnão; só valem juntas
pesoTotalCargadecimalnã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 viagem e sequenciaViagem (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 } sem data.

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.

RotaVerboPara que serve
/cpf/{cpf}/existeGETtrue se a empresa tem o motorista ativo
/POSTIncluir (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)."
  • siglaEstadoRg ou ddiCelular desconhecidos ficam vazios, sem erro. Categoria da CNH inexistente: 404.
  • Resposta: { cpf, nome, ativo }.

8. Veículos​

Rotas em /api/v1/veiculos.

RotaVerboPara que serve
/placa/{placa}/existeGETtrue se a empresa tem o veículo ativo
/POSTIncluir (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).

RotaVerboPara que serve
/cnpj/{cnpj}/credenciadoGETtrue se o posto existe no Autorizee (de qualquer empresa)
/cnpj/{cnpj}/vinculadoGETtrue se o posto tem vínculo ativo com a empresa
/cnpj/{cnpj}/vincularPOSTVincula 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 é true quando vincula.
curl -s -X POST "$BASE/api/v1/postos/cnpj/12345678000190/vincular" \
-H "Authorization: Bearer $TOKEN"

10. Usuários​

Rotas em /api/v1/usuarios.

RotaVerboPara que serve
/GETUsuários com acesso à empresa, por nome
/cpf/{cpf}/existeGETtrue se há usuário da empresa com o CPF (qualquer situação)
/POSTConvidar 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: false até 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.

RotaRetorno
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:

ColunaConteúdo
LocatarioEmpresa do token (vazio se não autenticou: as 401 também ficam no log)
DataRegistro, DuracaoMsHora do servidor e duração
Metodo, CaminhoVerbo e caminho com a query string
StatusCode, IpClienteCódigo HTTP e IP
CorpoRequisicao, CorpoRespostaCorpo 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​

LimiteValor
Fila de validações100 por leitura
Fila de estornos da validação100 por leitura
Fila de conclusões500 por leitura
Solicitações de alteração pendentessem limite
Tamanho do token200 caracteres
Corpo guardado no log1.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.