Consulta um manifesto enviado pelo próprio TMS (versão atual e status por documento)

GET/integracao/v1/manifestos/{numeroExterno}

Busca o manifesto pela chave natural, no ambiente da API key (chave de TESTE só enxerga manifestos de TESTE e vice-versa). Manifesto inexistente, de outro ambiente ou de outra transportadora = 404 (nunca revela que existe). A resposta traz o status de cada documento, que é controlado por documento e não pelo manifesto.

Para que serve: consulta a situação atual de um manifesto que o seu TMS enviou, com o status de cada documento e de cada NF.

Quando chamar: para conferir o que o Veltra tem depois de um envio ou de uma alteração, e para ver o andamento (PENDENTE, EM_TRANSPORTE, ENTREGUE e assim por diante).

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.

Caminho (path)

numeroExternotextoobrigatório
Número do manifesto no TMS (chave natural, única por transportadora e ambiente).
de 1 a 60 caracteres

Respostas

200application/json

Manifesto na versão atual

JSON

{
  "id": "0192f3a4-5b6c-7d8e-9f01-000000000001",
  "numeroExterno": "REL-2026-000123",
  "tipo": "ENTREGA",
  "ambiente": "PRODUCAO",
  "versaoAtual": 2,
  "quantidadeParadas": 1,
  "quantidadeDocumentos": 1,
  "documentos": [
    {
      "id": "0192f3a4-5b6c-7d8e-9f01-000000000010",
      "modelo": 57,
      "chave": "35260911222333000181570010000123451482135762",
      "numero": "12345",
      "serie": "1",
      "status": "EM_TRANSPORTE",
      "nfVinculadas": [
        {
          "id": "0192f3a4-5b6c-7d8e-9f01-000000000011",
          "chave": "35260912ABC34501DE35550010000456781555123454",
          "numero": "45678",
          "serie": "1",
          "status": "EM_TRANSPORTE"
        }
      ]
    }
  ]
}

Campos da resposta (26)

Campos

idtexto (uuid)obrigatório
numeroExternotextoobrigatório
tipotexto (lista fixa)obrigatório
Tipo do manifesto enviado pelo TMS. Use ROTA para o caminhão que sai com entregas e coletas juntas e TRANSFERENCIA para transferência entre filiais (sempre só transferência). ENTREGA e COLETA seguem aceitos por compatibilidade e são tratados como ROTA.
Valores: ROTA, TRANSFERENCIA, ENTREGA, COLETA
ambientetexto (lista fixa)obrigatório
Ambiente da credencial — sandbox e produção nunca se misturam
Valores: TESTE, PRODUCAO
versaoAtualinteiroobrigatório
Versão atual do manifesto (1 na criação; +1 a cada alteração).
mínimo 1
quantidadeParadasinteiroopcional
quantidadeDocumentosinteiroopcional
documentoslista de objetosopcional
Documentos ativos na versão atual, com o status de cada um.
documentos[].idtexto (uuid)obrigatório
documentos[].modelotexto (lista fixa)obrigatório
Modelo do documento fiscal: 55 = NF-e, 57 = CT-e, 58 = MDF-e. Nos documentos do manifesto o normal é 57 (CT-e) ou 55 (NF-e, ex.: coleta sem CT-e); a chave do MDF-e do próprio manifesto vai em chaveMdfe.
Valores: 55, 57, 58
documentos[].chavetexto ou nuloopcional
documentos[].numerotextoobrigatório
documentos[].serietexto ou nuloopcional
documentos[].statustexto (lista fixa)obrigatório
Status controlado por documento, não por manifesto.
Valores: PENDENTE, EM_TRANSPORTE, ENTREGUE, ENTREGUE_PARCIAL, DEVOLVIDO, CANCELADO
documentos[].nfVinculadaslista de objetosopcional
Situação de cada NF do CT-e (o status é por NF).
documentos[].nfVinculadas[].idtexto (uuid)obrigatório
documentos[].nfVinculadas[].chavetexto ou nuloopcional
documentos[].nfVinculadas[].numerotextoobrigatório
documentos[].nfVinculadas[].serietexto ou nuloopcional
documentos[].nfVinculadas[].statustexto (lista fixa)obrigatório
Status controlado por documento, não por manifesto.
Valores: PENDENTE, EM_TRANSPORTE, ENTREGUE, ENTREGUE_PARCIAL, DEVOLVIDO, CANCELADO
erroslista de objetosopcional
Documentos recusados nesta chamada. Ausente ou vazio quando tudo foi aceito.
erros[].documentoIndexinteiro ou nuloopcional
Índice (a partir de 0) do documento no array documentos da requisição. Nulo quando o documento recusado não está na requisição (ex.; remoção recusada de documento já baixado).
mínimo 0
erros[].codigotexto (lista fixa)obrigatório
Motivo da recusa de um documento específico.
Valores: CHAVE_INVALIDA, CHAVE_CTE_OBRIGATORIA, MODELO_INCOMPATIVEL, CNPJ_INVALIDO, DESTINATARIO_INVALIDO, DOCUMENTO_JA_BAIXADO, OUTRO
erros[].motivotextoobrigatório
Explicação em pt-BR.
erros[].chavetexto ou nuloopcional
Chave do documento, quando houver.
erros[].numerotexto ou nuloopcional
Número do documento, quando houver.

401application/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.

404application/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.

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
`401`	Chave inválida	Conferir a chave
`403`	Chave sem permissão	Usar a chave de TMS
`404`	Não existe neste ambiente da chave (ou é de outra transportadora). O Veltra nunca revela se existe em outro ambiente	Conferir o `numeroExterno` e se a chave é a de teste ou a de produção

Observações

a consulta é somente leitura e pode ser repetida à vontade. Uma chave de teste só enxerga manifestos de teste, e a de produção, só os de produção. Documentos removidos numa alteração não aparecem aqui. Para ser avisado da mudança de status sem consultar, use os webhooks.

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