Manual da API · Leitura e consulta

Baixa o PDF do comprovante quando o escopo autorizar

GET/v1/saida/comprovantes/{id}/pdf

Só a chave do TMS baixa o PDF; chave de consulta recebe 403. Comprovante inexistente responde 404 e comprovante ainda não publicado responde 409, ambos em application/problem+json.

Para que serve: baixa o PDF do comprovante de um documento. É o mesmo arquivo que o portal mostra.

Quando chamar: depois de receber o evento comprovante.emitido; o comprovanteId está em dados. 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/pdf

PDF do comprovante

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

Comprovante inexistente neste ambiente (COMPROVANTE_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.

409application/problem+json

Comprovante ainda não publicado (COMPROVANTE_AINDA_NAO_PUBLICADO, 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

Status	Quando	O que fazer
`401`	Chave inválida	Conferir a chave
`403`	Chave que não é de TMS	Usar a chave de TMS
`404`	`COMPROVANTE_NAO_ENCONTRADO`: o comprovante não existe neste ambiente (ou é de outra transportadora). Vem em `application/problem+json`, com o código no campo `codigo`	Conferir o id (é o `comprovanteId` do evento `comprovante.emitido`) e o ambiente da chave
`409`	`COMPROVANTE_AINDA_NAO_PUBLICADO`: o comprovante existe, mas o PDF ainda não foi publicado. Vem em `application/problem+json`, com o código no campo `codigo`	Esperar um pouco e tentar de novo; o certo é baixar depois do evento `comprovante.emitido`
`429`	Limite de chamadas	Esperar o `Retry-After`

Observações

o arquivo é entregue como está guardado; baixe e confira o SHA-256 se quiser provar que não mudou. O PDF só vem assinado quando a transportadora ligou a validação opcional (veja o módulo 6 da trilha). Cada download é registrado para fins de medição, e o download pode ser repetido.

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