Pular para o conteúdo
Veltra Ajuda
Manual da APIPlaybookEntrar

Manual da API · contrato 0.15.0

Manual da API

A API do Veltra fala JSON. O sistema da transportadora (o TMS) envia filiais e manifestos e lê o que aconteceu: baixas, ocorrências e comprovantes. Este manual é gerado direto do contrato OpenAPI, então sempre mostra as rotas e os campos como o contrato os define. Para o texto explicado de cada rota, veja também API por rota e o Guia do TMS.

Endereços base

AmbienteEndereço basePara que serve
Produçãohttps://api.veltrasolution.comUso real, com clientes de verdade.
Testehttps://api-teste.veltrasolution.comHomologar a integração. Tem o mesmo comportamento da produção e roda sempre no ambiente PRODUCAO.

A versão da API está no caminho (/integracao/v1/... e /v1/...). Mudanças dentro de uma versão são só aditivas: seu código deve ignorar campos que não conhece.

Autenticação

O TMS se autentica com uma chave de API no cabeçalho X-Veltra-Api-Key. A chave é emitida pelo administrador na tela Chaves de API do portal e o valor completo aparece uma única vez. Guarde em um cofre de segredos, nunca em código, log ou e-mail.

  • Não envie Authorization junto com a chave: o Veltra recusa com 401 (uma credencial por chamada).
  • Chave ausente, desconhecida, revogada ou expirada devolve 401.
  • As rotas marcadas como rota de administrador (webhooks e emissão de chaves) usam a sessão do portal em Authorization: Bearer.
curl -X GET 'https://api.veltrasolution.com/v1/api-keys/atual' \
  -H 'X-Veltra-Api-Key: SUA_CHAVE_AQUI'

Idempotency-Key

Nas rotas que gravam manifesto (POST e PUT), envie o cabeçalho Idempotency-Key (recomendado: um UUID por tentativa lógica de envio). Repetir a mesma chave com o mesmo corpo devolve a resposta original, sem duplicar nada; a mesma chave com corpo diferente devolve 409. A chave é guardada por pelo menos 72 horas.

Erros (RFC 9457)

Os erros vêm em application/problem+json, no padrão RFC 9457. Use status para decidir o que fazer e detail para mostrar a causa. Alguns erros trazem também codigo (por exemplo CHAVE_SUSPENSA) e uma lista erros com o motivo de cada documento recusado.

409
{
  "type": "https://veltra.com.br/problemas/idempotencia",
  "title": "Idempotency-Key já usada com outro corpo",
  "status": 409,
  "detail": "A Idempotency-Key informada já foi usada numa requisição com conteúdo diferente."
}

Rotas por grupo

Entrada do TMS

Enviar, consultar, alterar e cancelar manifestos (entrega, coleta e transferência).

Leitura e consulta

Ler eventos, manifestos, documentos e comprovantes; baixar PDF, pacote e XML; configurar o prazo.

Webhooks

Cadastrar os endereços que recebem os eventos, girar o segredo e reenviar entregas.

Filiais

Cadastrar e manter as filiais do TMS no Veltra.

Chaves

Verificar a chave em uso e administrar chaves de API e de consulta.

Prefere testar no navegador? Use o Swagger.