Referência da API de leitura e chaves

Gerado de contracts/ — não editar à mão. Versão do contrato: 0.7.0. Para atualizar, rode python docs/ajuda/ferramentas/gerar-referencia.py.

Rotas /v1/saida para ler eventos, manifestos, documentos, comprovantes e prazos, e rotas /v1/api-keys para emitir e revogar chaves.

Esta é uma referência estática: lê o contrato e descreve cada rota. Não há botão para executar chamadas. Nos exemplos do guia use sempre SUA_CHAVE_AQUI no lugar da chave real.

Rotas#

• GET /v1/api-keys — Lista as API keys da transportadora autenticada (só prefixo, nunca o valor)
• POST /v1/api-keys — Emite uma nova API key para a transportadora autenticada (D-02)
• GET /v1/api-keys/atual — Dados da API key que autenticou a chamada (tenant e ambiente, D-03)
• DELETE /v1/api-keys/{id} — Revoga uma API key (D-02)
• GET /v1/saida/comprovantes/{id}/pacote — Baixa o pacote de evidências quando o escopo autorizar
• GET /v1/saida/comprovantes/{id}/pdf — Baixa o PDF do comprovante quando o escopo autorizar
• GET /v1/saida/configuracao-prazo — Lê a configuração de prazo pela chave do TMS
• PUT /v1/saida/configuracao-prazo — Grava cidades e prazos pela chave do TMS
• GET /v1/saida/documentos/{id} — Obtém um documento fiscal da leitura de saída
• GET /v1/saida/eventos — Lista eventos de saída alterados desde o cursor
• GET /v1/saida/eventos-cte/{id}/xml — Baixa o XML assinado do evento 110180 com o protocolo
• GET /v1/saida/manifestos — Lista manifestos visíveis para a chave
• GET /v1/saida/manifestos/{id} — Obtém um manifesto da leitura de saída
• GET /v1/saida/openapi/{finalidade} — Devolve o OpenAPI filtrado da finalidade

Detalhe por rota#

GET /v1/api-keys#

Lista as API keys da transportadora autenticada (só prefixo, nunca o valor)

Identificador da operação: listarApiKeys

Autenticação: sessão do portal (Bearer)

Respostas

Corpo da resposta 200 (application/json)

POST /v1/api-keys#

Emite uma nova API key para a transportadora autenticada (D-02)

Identificador da operação: emitirApiKey

O valor em claro da chave é retornado apenas nesta resposta; a partir daí só o hash é armazenado e só o prefixo (apiKeyPrefixo) é exibido em listagens (mitigação T-01-02-01). Chave de PRODUCAO só para transportadora ATIVA; em homologação (ou inativa) responde 409.

Autenticação: sessão do portal (Bearer)

Corpo (application/json, obrigatório)

Respostas

Corpo da resposta 201 (application/json)

GET /v1/api-keys/atual#

Dados da API key que autenticou a chamada (tenant e ambiente, D-03)

Identificador da operação: credencialAtual

Endpoint "quem sou eu" do TMS. Autenticado SÓ por API key (cabeçalho X-Veltra-Api-Key). Chave revogada ou desconhecida = 401.

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Respostas

Corpo da resposta 200 (application/json)

DELETE /v1/api-keys/{id}#

Revoga uma API key (D-02)

Identificador da operação: revogarApiKey

Autenticação: sessão do portal (Bearer)

Parâmetros

Respostas

GET /v1/saida/comprovantes/{id}/pacote#

Baixa o pacote de evidências quando o escopo autorizar

Identificador da operação: baixarPacoteDeSaida

Pacote ZIP só quando EscopoDeTerceiro autorizar (D-11).

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Parâmetros

Respostas

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

Baixa o PDF do comprovante quando o escopo autorizar

Identificador da operação: baixarPdfDeSaida

PDF só quando EscopoDeTerceiro autorizar (D-11). Chave de terceiro que não é o tomador recebe 404, a mesma resposta de comprovante inexistente.

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Parâmetros

Respostas

GET /v1/saida/configuracao-prazo#

Lê a configuração de prazo pela chave do TMS

Identificador da operação: obterConfiguracaoPrazoIntegracao

Mesmo conteúdo de GET /v1/configuracao-prazo do portal (D-14).

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Respostas

Corpo da resposta 200 (application/json)

PUT /v1/saida/configuracao-prazo#

Grava cidades e prazos pela chave do TMS

Identificador da operação: salvarConfiguracaoPrazoIntegracao

O TMS envia a relação de cidades e prazos (D-14). Mesmo schema do portal. A mudança vale para as cargas que chegarem depois.

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Corpo (application/json, obrigatório)

Respostas

Corpo da resposta 200 (application/json)

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

Obtém um documento fiscal da leitura de saída

Identificador da operação: obterDocumentoDeSaida

Grupos integracao-tms, consulta-embarcador e consulta-destinatario. Sem posição do veículo. PDF indicado só se D-11 autorizar.

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Parâmetros

Respostas

Corpo da resposta 200 (application/json)

GET /v1/saida/eventos#

Lista eventos de saída alterados desde o cursor

Identificador da operação: listarEventosDeSaida

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 (D-11).

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Parâmetros

Respostas

Corpo da resposta 200 (application/json)

GET /v1/saida/eventos-cte/{id}/xml#

Baixa o XML assinado do evento 110180 com o protocolo

Identificador da operação: baixarXmlEventoCteDeSaida

Grupo integracao-tms. Evento 110180 assinado, com o protocolo da SEFAZ. O Veltra não transmite o 110190.

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Parâmetros

Respostas

GET /v1/saida/manifestos#

Lista manifestos visíveis para a chave

Identificador da operação: listarManifestosDeSaida

Grupo integracao-tms. Chaves de consulta não usam esta listagem ampla; leem o documento. Sem posição de veículo.

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Parâmetros

Respostas

Corpo da resposta 200 (application/json)

GET /v1/saida/manifestos/{id}#

Obtém um manifesto da leitura de saída

Identificador da operação: obterManifestoDeSaida

Grupo integracao-tms. Sem trilha nem posição do veículo para terceiros.

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Parâmetros

Respostas

Corpo da resposta 200 (application/json)

GET /v1/saida/openapi/{finalidade}#

Devolve o OpenAPI filtrado da finalidade

Identificador da operação: obterOpenApiFiltrado

Grupos (CHAVE-04): integracao-tms (todas as rotas /v1/saida); consulta-embarcador e consulta-destinatario (somente leitura de documento, evento que não seja posicao.lote, e PDF só sob D-11).

Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)

Parâmetros

Respostas