Manual da API · Leitura e consulta

Lista eventos de saída alterados desde o cursor

GET/v1/saida/eventos

Chave X-Veltra-Api-Key. O cursor alteradoDesde é opaco. A resposta só inclui linhas com alteração até 5 segundos atrás (janela de segurança); o mesmo cursor pode repetir a borda e o consumidor deduplica pelo id. CONSULTA_EMBARCADOR e CONSULTA_DESTINATARIO não recebem o tipo posicao.lote. PDF e canhoto no payload só quando EscopoDeTerceiro autorizar.

Para que serve: lista os eventos que mudaram desde a última leitura: baixa, ocorrência, comprovante, chegada e saída de parada, posição do veículo, estado do evento do CT-e, e as mudanças de manifesto.

Quando chamar: em repetição, de tempos em tempos, para manter o TMS em dia. É o jeito de "puxar" as novidades. Se preferir ser avisado, use os webhooks (os eventos têm o mesmo formato).

Parâmetros

Cabeçalhos (header)

X-Veltra-Api-Keytextoobrigatório
Chave de API do TMS. Emitida na tela Chaves de API do portal; o valor completo aparece uma única vez.

Consulta (query)

alteradoDesdetextoopcional
Cursor opaco devolvido em proximoCursor. Omitido, começa do início.
limiteinteiroopcional
de 1 a 200; padrão: 50

Respostas

200application/json

Página incremental de eventos

JSON

{
  "itens": [
    {}
  ],
  "proximoCursor": "texto"
}

Campos da resposta (2)

Campos

itenslista de objetosobrigatório
Envelopes do catálogo contracts/webhooks. Sem tenantId.
proximoCursortexto ou nuloobrigatório
Cursor opaco. Nulo quando não há página seguinte.

403application/problem+json

CHAVE_SUSPENSA (no campo codigo): a chave de consulta está suspensa porque o add-on foi desligado. A chave não foi revogada e volta a funcionar quando o add-on for contratado de novo.

JSON

{
  "type": "https://exemplo.com.br/webhook-veltra",
  "title": "texto",
  "status": 1,
  "detail": "texto",
  "instance": "https://exemplo.com.br/webhook-veltra",
  "codigo": "ASAAS_RECUSOU"
}

Campos da resposta (6)

Campos

typetextoobrigatório
titletextoobrigatório
statusinteiroobrigatório
detailtextoopcional
instancetextoopcional
codigotextoopcional
Código estável do problema para o cliente decidir o tratamento (ex.: ASAAS_RECUSOU, FATURA_NAO_ENCONTRADA, PAGINACAO_INVALIDA). Ausente quando o erro não tem código próprio.

Erroapplication/problem+json

Erro no formato RFC 9457 (application/problem+json)

JSON

{
  "type": "https://exemplo.com.br/webhook-veltra",
  "title": "texto",
  "status": 1,
  "detail": "texto",
  "instance": "https://exemplo.com.br/webhook-veltra",
  "codigo": "ASAAS_RECUSOU"
}

Campos da resposta (6)

Campos

typetextoobrigatório
titletextoobrigatório
statusinteiroobrigatório
detailtextoopcional
instancetextoopcional
codigotextoopcional
Código estável do problema para o cliente decidir o tratamento (ex.: ASAAS_RECUSOU, FATURA_NAO_ENCONTRADA, PAGINACAO_INVALIDA). Ausente quando o erro não tem código próprio.

Guia explicado

O que fazer: erros

Status	Quando	O que fazer
`400`	`limite` fora de 1 a 200 (`detail`: "limite deve estar entre 1 e 200")	Corrigir
`400`	Cursor inventado ou alterado (`detail`: "cursor alteradoDesde inválido")	Use só o valor devolvido em `proximoCursor`
`401`	Chave inválida	Conferir a chave
`403`	Chave sem permissão, ou `CHAVE_SUSPENSA` (chave de consulta sem o módulo)	Usar a chave certa
`429`	Limite de chamadas	Esperar o `Retry-After`

Observações

Janela de 5 segundos. Um evento recém-criado pode demorar alguns segundos para aparecer. Não é falha; consulte de novo.
Repetição é normal. O mesmo evento pode vir em duas respostas seguidas (por exemplo, se o seu processo caiu antes de guardar o cursor). Processar duas vezes tem de dar o mesmo resultado: trate pelo id.
Fluxo recomendado: leia, processe os itens, só depois grave o proximoCursor.
Posição do veículo (posicao.lote) vai só para a chave do TMS. Chaves de embarcador e destinatário não recebem esse tipo.
Chaves de consulta só veem eventos de documentos das raízes de CNPJ cadastradas nelas.
Leitura pura: pode ser repetida sem efeito colateral.

Texto completo, com mais exemplos, em API por rota.