Pular para o conteúdo
Veltra Ajuda
Manual da APIPlaybookEntrar

Documentação da API

Resume como autenticar, o que cada finalidade enxerga e como consultar eventos, e baixa o contrato OpenAPI filtrado da finalidade da chave.

Documentação da API

A tela Integrações > Documentação reúne, dentro do portal, o que você entrega a quem vai integrar com o Veltra: como autenticar, o que cada chave enxerga, como consultar eventos, os códigos de erro e o botão para baixar o contrato OpenAPI (YAML) da finalidade da chave. Ela é um resumo de bolso; o manual completo de todas as rotas, com exemplos por linguagem, fica na central de ajuda, em Manual da API.

Para que serve#

  • Passar ao desenvolvedor do embarcador ou do TMS o essencial, sem abrir o código.
  • Baixar o contrato OpenAPI que mostra só as rotas que a finalidade pode chamar, para gerar um cliente.
  • Ter à mão exemplos copiáveis de chamada.

Quem vê#

Só o Administrador. Os demais perfis veem o aviso de acesso restrito. Para criar a chave que a documentação cita, veja Chaves de consulta.

O que a página traz#

Na lateral, em telas grandes, há um sumário Nesta página. As seções são:

SeçãoO que explica
Como autenticarToda consulta leva a chave no cabeçalho X-Veltra-Api-Key. A chave é criada em Integrações > Chaves de consulta e aparece completa uma única vez. Cada chave pertence a um ambiente (teste ou produção) e só enxerga os dados dele; chave revogada ou vencida perde o acesso na hora
O que cada finalidade enxergaTabela com o alcance de TMS, Consulta do embarcador e Consulta de terceiro. A raiz é o início de 8 caracteres do CNPJ; CPF nunca aparece; documento fora das raízes responde 404; PDF e canhoto só saem para quem paga o frete
Consultar entregas (alteradoDesde)Leia GET /v1/saida/eventos sem alteradoDesde, guarde o proximoCursor e use-o na próxima rodada. O cursor é opaco; eventos com menos de 5 segundos entram na rodada seguinte; o mesmo evento pode vir duas vezes (trate pelo id); o limite vai de 1 a 200 (padrão 50)
Como o prazo é contadoAs mesmas regras de Prazos de entrega. O prazo efetivo de cada entrega já vem calculado: não refaça a conta
Receber webhooks e validar a assinaturaResumo da verificação no padrão Standard Webhooks (cabeçalhos webhook-id, webhook-timestamp e webhook-signature). Veja Webhooks
Limites e códigos de erroLimite de 1 a 600 consultas por minuto, definido na criação da chave. Códigos: 400 (cursor ou limite inválido), 401 (chave ausente, inválida, revogada ou vencida), 403 (a finalidade não permite a consulta), 404 (não encontrado ou fora dos CNPJs liberados), 429 (limite atingido; respeite o Retry-After). Os erros seguem application/problem+json
ExemplosPrimeira leitura de eventos, leitura seguinte com o cursor, resposta de exemplo, situação de um documento e validação de assinatura de webhook em Node. Cada bloco tem o botão Copiar
Baixar OpenAPI (YAML)Veja abaixo

Nos exemplos, a chave é um texto de mentira (SUA_CHAVE): troque pela chave real e $VELTRA_API pelo endereço da API que vem no OpenAPI baixado.

Como baixar o OpenAPI#

  1. Na seção Baixar OpenAPI (YAML), escolha a Finalidade: Consulta do embarcador, Consulta de terceiro ou TMS.
  2. Cole a Chave da mesma finalidade. Use o ícone de olho para mostrar ou esconder o que digitou. O contrato filtrado só sai com uma chave da mesma finalidade; a chave não fica guardada no portal e é limpa depois do download.
  3. Clique em Baixar OpenAPI (YAML). O arquivo é salvo com o nome veltra- seguido da finalidade, por exemplo veltra-consulta-embarcador.yaml, e a tela confirma "Arquivo baixado."
  4. Entregue o arquivo, junto com a chave, a quem vai integrar.

Mensagens que você pode ver#

MensagemO que fazer
Cole a chave da finalidade escolhida.Preencher o campo da chave
Chave recusada. Confira se ela está ativa e se é da finalidade escolhida.Usar uma chave ativa e da mesma finalidade que você escolheu
Não foi possível baixar o arquivo. Tente de novo em instantes.Tentar novamente

Boas práticas#

  • Entregue o OpenAPI filtrado, não o da transportadora inteira: o integrador vê só as rotas que pode usar.
  • Combine webhook para velocidade com a leitura incremental para conferir se nada se perdeu.
  • Nunca cole a chave em e-mail ou chat; combine um meio seguro com o integrador.

Perguntas frequentes#

Onde está a lista completa de rotas? No Manual da API e na referência de leitura.

Posso baixar o contrato da finalidade TMS? Sim, com uma chave do TMS.

Veja também#