Pular para o conteúdo
Veltra Ajuda
Manual da APIPlaybookEntrar

Manual da API · Leitura e consulta

Lista as fotos avulsas de um CT-e (ou NF-e) para o TMS

GET/v1/saida/documentos/{id}/fotos

Devolve os metadados das fotos verificadas ligadas ao documento. Para um CT-e entram as fotos do próprio CT-e e as das NF-e vinculadas a ele, então um CT-e pode ter várias (por exemplo, o canhoto de cada nota). Cada item traz o caminho para baixar a imagem original e diz a que a foto se refere: numeroCte (o CT-e da foto; o próprio documento quando ele é um CT-e), numeroNf e serieNf (só no canhoto, a nota a que ele pertence) e rotulo (texto pronto, como "CT-e 322433" ou "Canhoto da NF 15876/2"). O TMS nunca recebe as fotos de outro CT-e, mesmo que a baixa tenha coberto vários: só as do documento consultado, as das NF dele e as compartilhadas (assinatura, local). Só a chave do TMS. Documento inexistente neste ambiente responde 404 (DOCUMENTO_NAO_ENCONTRADO). Lista vazia quando ainda não há foto.

Para que serve: lista as fotos avulsas de um documento, com os metadados de cada uma. Para um CT-e entram as fotos do próprio CT-e e as das NF-e ligadas a ele, então um CT-e pode ter várias (por exemplo, o canhoto de cada nota). Cada foto vem com o número do CT-e e, no canhoto, o número (e a série) da NF-e, para você casar a imagem com o documento sem adivinhar. Uma baixa pode cobrir vários CT-e de uma vez, mas o Veltra nunca devolve as fotos de outro CT-e: você recebe só as do CT-e consultado, as das NF-e dele e as compartilhadas (assinatura, local).

Quando chamar: quando o seu sistema quer guardar as imagens do CT-e (canhoto, mercadoria, avaria) sem abrir o pacote de evidências. Só a chave do TMS usa. Chave de consulta recebe 403.

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)

  • idtexto (uuid)obrigatório

Respostas

200application/json

Fotos do documento, da mais antiga para a mais nova

JSON
[
  {
    "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
    "tipo": "COMPROVANTE_CTE",
    "contentType": "image/jpeg",
    "tamanho": 1,
    "sha256": "texto",
    "capturadaEm": "2026-11-06T09:15:00-03:00",
    "documentoIds": [
      "0192f3a4-5b6c-7d8e-9f01-23456789abcd"
    ],
    "caminho": "texto",
    "rotulo": "texto",
    "numeroCte": "texto",
    "numeroNf": "texto",
    "serieNf": "texto"
  }
]

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.

404application/problem+json

Documento inexistente neste ambiente (DOCUMENTO_NAO_ENCONTRADO, no campo codigo).

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

401, 403 (chave que não é de TMS), 404 (DOCUMENTO_NAO_ENCONTRADO: o documento não existe neste ambiente), 429.

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