Integração com o TMS

Como o sistema da transportadora envia manifestos e recebe de volta entregas, baixas e comprovantes.

O Veltra conversa com o TMS da transportadora por API e por webhooks. O TMS envia o manifesto, o Veltra distribui a carga ao motorista e devolve ao TMS o que acontece em campo. Esta página é o mapa; o detalhe técnico está na documentação da API.

Para que serve#

Evitar digitar o manifesto duas vezes.
Devolver ao TMS as baixas, ocorrências e comprovantes assim que acontecem.
Permitir que embarcadores e destinatários consultem apenas o que é deles, por chaves de consulta.

Como funciona#

Enviar. O TMS envia o manifesto inteiro, em JSON, numa única chamada. O Veltra monta as paradas sozinho, agrupando os documentos pelo destinatário e pelo endereço. O envio é idempotente: repetir a chamada não duplica. Para alterar, o manifesto é reenviado inteiro; para cancelar, existe uma chamada própria.
Executar. O motorista recebe a carga no app e executa a rota (Fluxo do dia a dia).
Receber. O Veltra avisa o TMS por webhook (baixa, ocorrência, comprovante e outros eventos) e também permite a leitura por API, inclusive de forma incremental para conferir que nada ficou para trás.

Como começar#

Gere uma chave de entrada

O administrador abre Integrações > Chaves de consulta, usa Criar chave, escolhe o nome e o ambiente (Teste ou Produção) e copia a chave na hora: o valor completo aparece uma única vez. Guarde-a em um cofre de segredos e nunca a coloque em código versionado ou em e-mail.

Comece pelo ambiente de Teste

Manifestos enviados com a chave de Teste ficam separados dos reais: não chegam ao app de motoristas reais, não disparam webhook de produção e são apagados depois de cerca de 30 dias. Use-o para desenvolver e homologar.

Cadastre as filiais e envie o primeiro manifesto

As filiais precisam existir antes do envio. Siga o roteiro de homologação do módulo 4 da trilha.

Receba os avisos

Cadastre o endereço do webhook em Integrações > Webhooks (tela do administrador), guarde o segredo de assinatura e confira a assinatura de cada aviso. O passo a passo está no manual de webhooks.

Onde está a documentação técnica#

Preciso de	Onde
Visão geral e rotas da API, com exemplos	Central de ajuda: API
Cada rota explicada	API por rota
Webhooks: eventos, assinatura e tentativas	Webhooks e eventos e manual de webhooks
Testar chamadas no navegador	Swagger, pelo botão na página inicial da central de ajuda
Passo a passo na tela	Módulo 4 e módulo 5 da trilha

Boas práticas#

Use sempre Idempotency-Key no envio e trate a resposta de repetição como sucesso.
Combine webhook (rapidez) com leitura incremental (conferência).
Revogue imediatamente uma chave que vazou e gere outra.
Se o teste grátis tiver acabado, a chave de Produção não grava manifestos novos; contrate o plano para voltar (veja Plano, teste e cobrança).