Referência da API
Referência da API de entrada (manifestos e filiais)
Referência da API de entrada (manifestos e filiais)
Gerado de
contracts/— não editar à mão. Versão do contrato: 0.7.0. Para atualizar, rodepython docs/ajuda/ferramentas/gerar-referencia.py.
Rotas /integracao/v1 que o sistema da transportadora (TMS) usa para cadastrar filiais e enviar, alterar, consultar e cancelar manifestos.
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
/integracao/v1/filiais— Lista as filiais da transportadora da API key (D-10) - POST
/integracao/v1/filiais— Cadastra uma filial pela API do TMS (D-10) - GET
/integracao/v1/filiais/{id}— Detalha uma filial (D-10) - PUT
/integracao/v1/filiais/{id}— Atualiza uma filial pela API do TMS (D-10) - POST
/integracao/v1/manifestos— Envia um manifesto novo (entrega, coleta ou transferência) - GET
/integracao/v1/manifestos/{numeroExterno}— Consulta um manifesto enviado pelo próprio TMS (versão atual e status por documento) - PUT
/integracao/v1/manifestos/{numeroExterno}— Altera um manifesto reenviando-o inteiro (nova versão) - POST
/integracao/v1/manifestos/{numeroExterno}/cancelar— Cancela o que ainda falta de um manifesto (cancelamento parcial)
Detalhe por rota#
GET /integracao/v1/filiais#
Lista as filiais da transportadora da API key (D-10)
Identificador da operação: listarFiliaisTms
Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)
Respostas
| Código | Descrição |
|---|---|
| 200 | Filiais da transportadora |
| demais erros | Erro no formato RFC 9457 (application/problem+json) |
Corpo da resposta 200 (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
[] | objeto | não | |
[].ativa | booleano | não | |
[].endereco | texto | não | |
[].id | texto (uuid) | sim | |
[].latitude | número (double) | não | |
[].longitude | número (double) | não | |
[].nome | texto | sim | |
[].raioGeofenceM | inteiro | não | Raio da geofence em metros, ajustado no mapa pelo usuário (D-11) |
[].siglaExterna | texto | sim | Identificador externo único por tenant, referenciado pelo manifesto do TMS (D-10) |
POST /integracao/v1/filiais#
Cadastra uma filial pela API do TMS (D-10)
Identificador da operação: criarFilialTms
Mesma implementação do cadastro pelo portal. A siglaExterna é o identificador que o manifesto usa para referenciar a filial; é única por transportadora (repetida = 409). Pela API do TMS o endereço NÃO é geocodificado (limite de taxa do serviço externo): sem latitude/longitude, a filial fica sem pino até o ajuste no portal (D-11). Exige API key de PRODUCAO: enquanto os cadastros não separam dados por ambiente, a chave de TESTE só lê (gravar = 403, D-03).
Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)
Corpo (application/json, obrigatório)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ativa | booleano | não | Omitido = mantém o valor atual (nova filial nasce ativa) |
endereco | texto | não | |
latitude | número (double) | não | |
longitude | número (double) | não | |
nome | texto | sim | |
raioGeofenceM | inteiro | não | Padrão 200 m quando omitido na criação; mínimo: 10; máximo: 50000 |
siglaExterna | texto | sim |
Respostas
| Código | Descrição |
|---|---|
| 201 | Filial criada |
| demais erros | Erro no formato RFC 9457 (application/problem+json) |
Corpo da resposta 201 (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ativa | booleano | não | |
endereco | texto | não | |
id | texto (uuid) | sim | |
latitude | número (double) | não | |
longitude | número (double) | não | |
nome | texto | sim | |
raioGeofenceM | inteiro | não | Raio da geofence em metros, ajustado no mapa pelo usuário (D-11) |
siglaExterna | texto | sim | Identificador externo único por tenant, referenciado pelo manifesto do TMS (D-10) |
GET /integracao/v1/filiais/{id}#
Detalha uma filial (D-10)
Identificador da operação: buscarFilialTms
Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | texto (uuid) | sim |
Respostas
| Código | Descrição |
|---|---|
| 200 | Filial |
| demais erros | Erro no formato RFC 9457 (application/problem+json) |
Corpo da resposta 200 (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ativa | booleano | não | |
endereco | texto | não | |
id | texto (uuid) | sim | |
latitude | número (double) | não | |
longitude | número (double) | não | |
nome | texto | sim | |
raioGeofenceM | inteiro | não | Raio da geofence em metros, ajustado no mapa pelo usuário (D-11) |
siglaExterna | texto | sim | Identificador externo único por tenant, referenciado pelo manifesto do TMS (D-10) |
PUT /integracao/v1/filiais/{id}#
Atualiza uma filial pela API do TMS (D-10)
Identificador da operação: atualizarFilialTms
Exige API key de PRODUCAO; com a chave de TESTE = 403 (D-03).
Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
id | path | texto (uuid) | sim |
Corpo (application/json, obrigatório)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ativa | booleano | não | Omitido = mantém o valor atual (nova filial nasce ativa) |
endereco | texto | não | |
latitude | número (double) | não | |
longitude | número (double) | não | |
nome | texto | sim | |
raioGeofenceM | inteiro | não | Padrão 200 m quando omitido na criação; mínimo: 10; máximo: 50000 |
siglaExterna | texto | sim |
Respostas
| Código | Descrição |
|---|---|
| 200 | Filial atualizada |
| demais erros | Erro no formato RFC 9457 (application/problem+json) |
Corpo da resposta 200 (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ativa | booleano | não | |
endereco | texto | não | |
id | texto (uuid) | sim | |
latitude | número (double) | não | |
longitude | número (double) | não | |
nome | texto | sim | |
raioGeofenceM | inteiro | não | Raio da geofence em metros, ajustado no mapa pelo usuário (D-11) |
siglaExterna | texto | sim | Identificador externo único por tenant, referenciado pelo manifesto do TMS (D-10) |
POST /integracao/v1/manifestos#
Envia um manifesto novo (entrega, coleta ou transferência)
Identificador da operação: criarManifestoTms
Um manifesto por chamada (D-04). A idempotência usa o cabeçalho Idempotency-Key (obrigatório) mais a chave natural numeroExterno (número do manifesto no TMS): - mesma Idempotency-Key e mesmo corpo = devolve a mesma resposta da primeira chamada, sem duplicar nada (INT-01); - mesma Idempotency-Key com corpo diferente = 409; - numeroExterno que já existe (com outra Idempotency-Key) = 409; para alterar um manifesto já enviado use o PUT (reenvio completo).
O manifesto é gravado no ambiente da API key: chave de TESTE grava manifesto de sandbox (ambiente=TESTE), que nunca vai para o app de motoristas reais, nunca dispara webhook de produção, não faz upsert de motorista/veículo no cadastro real e é expurgado depois de ~30 dias (D-25). Idempotência, chave natural e vínculo de documentos são isolados por ambiente. Erros de cabeçalho do manifesto (tipo ausente, CPF do motorista inválido, filial de transferência inexistente etc.) recusam a chamada inteira com 400. Erros de um documento específico (chave com dígito verificador errado, CT-e sem chave) recusam só aquele documento: o restante é gravado e a resposta traz o motivo em erros[], apontando o índice do documento no array documentos (D-07). As paradas são montadas agrupando os documentos por destinatário (CNPJ/CPF) + endereço, na ordem em que aparecem no manifesto (D-10, D-11). Sem latitude/longitude, o endereço é geocodificado em segundo plano (D-13, D-26); a resposta não espera a geocodificação.
Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
Idempotency-Key | header | texto | sim | Chave de idempotência gerada pelo TMS (recomendado: UUID) por tentativa lógica de envio. Guardada por pelo menos 72 h, isolada por transportadora e ambiente (D-04, D-25). Repetir a mesma chave com o mesmo corpo devolve a resposta original; com corpo diferente = 409.; mín. tamanho: 1; máx. tamanho: 255 |
Corpo (application/json, obrigatório)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ajudantes | lista | não | Até 2 ajudantes (nome + CPF). Não são usuários do app, só dados do manifesto (D-23).; máx. itens: 2 |
ajudantes[] | objeto | não | Motorista ou ajudante citado no manifesto. |
ajudantes[].cpf | texto | sim | CPF com ou sem máscara (11 dígitos), validado pelos dígitos verificadores. |
ajudantes[].nome | texto | sim | máx. tamanho: 200 |
chaveMdfe | texto | não | Chave de acesso de 44 posições (NF-e, CT-e ou MDF-e). As 12 primeiras posições do CNPJ de quem emitiu o documento fiscal podem ser letras maiúsculas (CNPJ alfanumérico, em vigor desde 01/07/2026); o resto é numérico. O dígito verificador e o modelo são conferidos (INT-05).; mín. tamanho: 44; máx. tamanho: 44; padrão de formato: ^[0-9]{6}[0-9A-Z]{12}[0-9]{26}$ |
documentos | lista | sim | mín. itens: 1 |
documentos[] | objeto | não | Documento fiscal do manifesto (normalmente um CT-e com as NF que ele transporta). Chave do CT-e (modelo=57) é obrigatória; nos demais modelos é opcional, e sem ela o documento é identificado por numero + serie + cnpjEmbarcador (D-03, D-05). |
documentos[].chave | texto | não | Chave de acesso de 44 posições (NF-e, CT-e ou MDF-e). As 12 primeiras posições do CNPJ de quem emitiu o documento fiscal podem ser letras maiúsculas (CNPJ alfanumérico, em vigor desde 01/07/2026); o resto é numérico. O dígito verificador e o modelo são conferidos (INT-05).; mín. tamanho: 44; máx. tamanho: 44; padrão de formato: ^[0-9]{6}[0-9A-Z]{12}[0-9]{26}$ |
documentos[].cnpjEmbarcador | texto | não | CNPJ do embarcador, dono/emitente da NF (para modelo diferente de 57; obrigatório nesses casos). No CT-e não é usado: a chave já identifica o documento. Com ou sem máscara. |
documentos[].cnpjTransportadora | texto | não | CNPJ da transportadora que emitiu o CT-e (só faz sentido em modelo=57). Opcional: ausente, o Veltra usa o CNPJ da chave (posições 7 a 20). Se vier, é usado como enviado, sem checar contra a chave. Com ou sem máscara. |
documentos[].cteEmitidoEm | texto (date-time) | não | Opcional. Data e hora de emissão do CT-e. Sem a data base escolhida pela transportadora, o prazo conta da chegada do manifesto ao Veltra (D-14). prazoEntrega continua aceito. |
documentos[].destinatario | objeto | sim | |
documentos[].destinatario.cnpjCpf | texto | sim | CNPJ (numérico ou alfanumérico) ou CPF do destinatário/recebedor, com ou sem máscara. Obrigatório (D-24): agrupa as paradas (D-10) e identifica o link do destinatário (fase 7). |
documentos[].destinatario.email | texto (email) | não | Opcional. E-mail do destinatário para o aviso da entrega. Dado pessoal: não registrar em log. Ausente, o destinatário acompanha pelo link copiado no portal ou pela chave da NF.; máx. tamanho: 320 |
documentos[].destinatario.endereco | objeto | sim | Endereço de entrega/coleta do destinatário. Junto com o CNPJ/CPF, define a parada (D-10). |
documentos[].destinatario.nome | texto | sim | máx. tamanho: 200 |
documentos[].embarcador | objeto | não | Embarcador da mercadoria (opcional, D-02); quem embarca a mercadoria (cliente da transportadora). |
documentos[].embarcador.cnpjCpf | texto | sim | |
documentos[].embarcador.nome | texto | não | |
documentos[].globalizado | booleano | não | Opcional e aditivo (só modelo=57). CT-e globalizado (a SEFAZ admite mais de um comprovante para ele). Omitido = não globalizado.; padrão: False |
documentos[].latitude | número (double) | não | Opcional (INT-06). Se vier junto com longitude, é usada direto na parada; senão o endereço é geocodificado em segundo plano (D-13, D-26).; mínimo: -90; máximo: 90 |
documentos[].longitude | número (double) | não | mínimo: -180; máximo: 180 |
documentos[].modelo | enum | sim | 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[].nfVinculadas | lista | não | NF transportadas quando o documento é um CT-e (1 ou mais). Vazio/omitido nos demais modelos. |
documentos[].nfVinculadas[] | objeto | não | NF transportada pelo CT-e. A chave da NF-e (modelo 55) normalmente vem, mas é opcional (D-03); o perfil Comprovante Digital Homologado usa essas chaves como lista de NF-e do CT-e (sem chave, o evento fica PENDENTE_DE_DADOS); sem ela, a NF é identificada por número + série + CNPJ de quem emitiu o documento fiscal e a chave é vinculada quando chegar depois (INT-02). A mesma NF pode estar em vários CT-e (CARGA-01). |
documentos[].numero | texto | sim | máx. tamanho: 20 |
documentos[].peso | número (double) | não | Peso em kg.; mínimo: 0 |
documentos[].prazoEntrega | texto (date) | não | Prazo de entrega, quando houver (INT-06). Continua aceito. Sem a data base escolhida pela transportadora (cteEmitidoEm, nfeEmitidoEm ou este campo), o prazo conta da chegada do manifesto ao Veltra (D-14). |
documentos[].protocoloAutorizacao | texto | não | Opcional e aditivo (só modelo=57). Protocolo de autorização do CT-e (nProt, 15 dígitos, do protCTe). Necessário ao perfil Comprovante Digital Homologado (evento 110180). Sem ele, o evento do CT-e fica PENDENTE_DE_DADOS no portal; a entrega continua sendo comprovada pelo comprovante interno do Veltra. Clientes que não enviam o campo seguem funcionando como antes.; padrão de formato: ^[0-9]{15}$ |
documentos[].serie | texto | não | máx. tamanho: 10 |
documentos[].tarefa | enum | não | O que o motorista faz com o documento na parada. Coleta e entrega no mesmo cliente e no mesmo manifesto ficam na mesma parada, com as duas tarefas (D-12).; valores: ENTREGA, COLETA |
documentos[].tipoServico | enum | não | Opcional e aditivo (só modelo=57). Tipo de serviço do CT-e (tpServ): NORMAL (0), SUBCONTRATACAO (1), REDESPACHO (2), REDESPACHO_INTERMEDIARIO (3), SERVICO_VINCULADO_MULTIMODAL (4). O evento 110180 só lista as NF-e entregues em CT-e NORMAL.; valores: NORMAL, SUBCONTRATACAO, REDESPACHO, REDESPACHO_INTERMEDIARIO, SERVICO_VINCULADO_MULTIMODAL |
documentos[].tomadorCnpj | texto | não | Opcional e aditivo (só modelo=57). CNPJ de quem paga o frete (tomador do CT-e), numérico ou alfanumérico, com ou sem máscara. Ausente, nenhum terceiro recebe PDF nem canhoto (D-12). |
documentos[].valor | número (double) | não | Valor do documento em reais, para exibição na torre; não é usado em cálculo (desde a 0.4.0).; mínimo: 0 |
documentos[].volumes | inteiro | não | mínimo: 0 |
filialDestinoSigla | texto | não | siglaExterna da filial de destino. Obrigatória quando tipo=TRANSFERENCIA. |
filialOrigemSigla | texto | não | siglaExterna da filial de origem. Obrigatória quando tipo=TRANSFERENCIA (D-10 da fase 1, INT-03); sigla desconhecida = 400. |
motorista | objeto | sim | Motorista ou ajudante citado no manifesto. |
motorista.cpf | texto | sim | CPF com ou sem máscara (11 dígitos), validado pelos dígitos verificadores. |
motorista.nome | texto | sim | máx. tamanho: 200 |
numeroExterno | texto | sim | Número do manifesto/relatório no TMS. Chave natural, única por transportadora e ambiente (D-04).; mín. tamanho: 1; máx. tamanho: 60 |
quantidadePaletes | inteiro | não | Quantidade de paletes informada no manifesto (D-23).; mínimo: 0 |
tipo | enum | sim | 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 |
veiculo | objeto | sim | |
veiculo.placa | texto | sim | Placa de tração (padrão antigo ou Mercosul), com ou sem hífen. Chave de upsert do veículo (D-09 da fase 1). |
Respostas
| Código | Descrição |
|---|---|
| 200 | Reenvio idempotente (mesma Idempotency-Key e mesmo corpo): a mesma resposta da primeira chamada, sem gravar nada de novo. |
| 201 | Manifesto criado (versão 1). Se algum documento foi recusado, ele aparece em erros[] e o restante foi gravado normalmente. |
| 400 | Manifesto recusado por inteiro (RFC 9457). Quando o problema está em documentos específicos e nenhum documento pôde ser aceito, o membro de extensão erros lista o motivo de cada um. |
| 401 | Erro no formato RFC 9457 (application/problem+json) |
| 409 | Conflito (RFC 9457): Idempotency-Key repetida com corpo diferente, numeroExterno que já existe no ambiente, ou TESTE_ENCERRADO (no campo codigo): o teste grátis da transportadora acabou e a chave de PRODUCAO não grava manifesto novo. TESTE_ENCERRADO vale só para PRODUCAO; o reenvio idempotente de um manifesto já gravado devolve o 201 gravado, sem erro. Chave de TESTE não é afetada. |
| demais erros | Erro no formato RFC 9457 (application/problem+json) |
Corpo da resposta 200 (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ambiente | enum | sim | Ambiente da credencial — sandbox e produção nunca se misturam (D-03); valores: TESTE, PRODUCAO |
documentos | lista | não | Documentos ativos na versão atual, com o status de cada um. |
documentos[] | objeto | não | Situação atual de um documento no manifesto. |
documentos[].chave | string/null | não | |
documentos[].id | texto (uuid) | sim | |
documentos[].modelo | enum | sim | 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[].nfVinculadas | lista | não | Situação de cada NF do CT-e (o status é por NF). |
documentos[].nfVinculadas[] | objeto | não | |
documentos[].numero | texto | sim | |
documentos[].serie | string/null | não | |
documentos[].status | enum | sim | Status controlado por documento, não por manifesto (CARGA-01). Na fase 2 só aparecem PENDENTE, EM_TRANSPORTE e CANCELADO; ENTREGUE, ENTREGUE_PARCIAL e DEVOLVIDO chegam com as baixas (fase 4, D-14).; valores: PENDENTE, EM_TRANSPORTE, ENTREGUE, ENTREGUE_PARCIAL, DEVOLVIDO, CANCELADO |
erros | lista | não | Documentos recusados nesta chamada (D-07). Ausente ou vazio quando tudo foi aceito. |
erros[] | objeto | não | Recusa de um documento específico (D-07). O resto do manifesto é aplicado normalmente. |
erros[].chave | string/null | não | Chave do documento, quando houver. |
erros[].codigo | enum | sim | 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[].documentoIndex | integer/null | não | Í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[].motivo | texto | sim | Explicação em pt-BR. |
erros[].numero | string/null | não | Número do documento, quando houver. |
id | texto (uuid) | sim | |
numeroExterno | texto | sim | |
quantidadeDocumentos | inteiro | não | |
quantidadeParadas | inteiro | não | |
tipo | enum | sim | 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 |
versaoAtual | inteiro | sim | Versão atual do manifesto (1 na criação; +1 a cada alteração, D-06).; mínimo: 1 |
Corpo da resposta 201 (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ambiente | enum | sim | Ambiente da credencial — sandbox e produção nunca se misturam (D-03); valores: TESTE, PRODUCAO |
documentos | lista | não | Documentos ativos na versão atual, com o status de cada um. |
documentos[] | objeto | não | Situação atual de um documento no manifesto. |
documentos[].chave | string/null | não | |
documentos[].id | texto (uuid) | sim | |
documentos[].modelo | enum | sim | 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[].nfVinculadas | lista | não | Situação de cada NF do CT-e (o status é por NF). |
documentos[].nfVinculadas[] | objeto | não | |
documentos[].numero | texto | sim | |
documentos[].serie | string/null | não | |
documentos[].status | enum | sim | Status controlado por documento, não por manifesto (CARGA-01). Na fase 2 só aparecem PENDENTE, EM_TRANSPORTE e CANCELADO; ENTREGUE, ENTREGUE_PARCIAL e DEVOLVIDO chegam com as baixas (fase 4, D-14).; valores: PENDENTE, EM_TRANSPORTE, ENTREGUE, ENTREGUE_PARCIAL, DEVOLVIDO, CANCELADO |
erros | lista | não | Documentos recusados nesta chamada (D-07). Ausente ou vazio quando tudo foi aceito. |
erros[] | objeto | não | Recusa de um documento específico (D-07). O resto do manifesto é aplicado normalmente. |
erros[].chave | string/null | não | Chave do documento, quando houver. |
erros[].codigo | enum | sim | 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[].documentoIndex | integer/null | não | Í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[].motivo | texto | sim | Explicação em pt-BR. |
erros[].numero | string/null | não | Número do documento, quando houver. |
id | texto (uuid) | sim | |
numeroExterno | texto | sim | |
quantidadeDocumentos | inteiro | não | |
quantidadeParadas | inteiro | não | |
tipo | enum | sim | 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 |
versaoAtual | inteiro | sim | Versão atual do manifesto (1 na criação; +1 a cada alteração, D-06).; mínimo: 1 |
GET /integracao/v1/manifestos/{numeroExterno}#
Consulta um manifesto enviado pelo próprio TMS (versão atual e status por documento)
Identificador da operação: buscarManifestoTms
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 (CARGA-01).
Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
numeroExterno | path | texto | sim | Número do manifesto no TMS (chave natural, única por transportadora e ambiente).; mín. tamanho: 1; máx. tamanho: 60 |
Respostas
| Código | Descrição |
|---|---|
| 200 | Manifesto na versão atual |
| 401 | Erro no formato RFC 9457 (application/problem+json) |
| 404 | Erro no formato RFC 9457 (application/problem+json) |
| demais erros | Erro no formato RFC 9457 (application/problem+json) |
Corpo da resposta 200 (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ambiente | enum | sim | Ambiente da credencial — sandbox e produção nunca se misturam (D-03); valores: TESTE, PRODUCAO |
documentos | lista | não | Documentos ativos na versão atual, com o status de cada um. |
documentos[] | objeto | não | Situação atual de um documento no manifesto. |
documentos[].chave | string/null | não | |
documentos[].id | texto (uuid) | sim | |
documentos[].modelo | enum | sim | 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[].nfVinculadas | lista | não | Situação de cada NF do CT-e (o status é por NF). |
documentos[].nfVinculadas[] | objeto | não | |
documentos[].numero | texto | sim | |
documentos[].serie | string/null | não | |
documentos[].status | enum | sim | Status controlado por documento, não por manifesto (CARGA-01). Na fase 2 só aparecem PENDENTE, EM_TRANSPORTE e CANCELADO; ENTREGUE, ENTREGUE_PARCIAL e DEVOLVIDO chegam com as baixas (fase 4, D-14).; valores: PENDENTE, EM_TRANSPORTE, ENTREGUE, ENTREGUE_PARCIAL, DEVOLVIDO, CANCELADO |
erros | lista | não | Documentos recusados nesta chamada (D-07). Ausente ou vazio quando tudo foi aceito. |
erros[] | objeto | não | Recusa de um documento específico (D-07). O resto do manifesto é aplicado normalmente. |
erros[].chave | string/null | não | Chave do documento, quando houver. |
erros[].codigo | enum | sim | 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[].documentoIndex | integer/null | não | Í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[].motivo | texto | sim | Explicação em pt-BR. |
erros[].numero | string/null | não | Número do documento, quando houver. |
id | texto (uuid) | sim | |
numeroExterno | texto | sim | |
quantidadeDocumentos | inteiro | não | |
quantidadeParadas | inteiro | não | |
tipo | enum | sim | 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 |
versaoAtual | inteiro | sim | Versão atual do manifesto (1 na criação; +1 a cada alteração, D-06).; mínimo: 1 |
PUT /integracao/v1/manifestos/{numeroExterno}#
Altera um manifesto reenviando-o inteiro (nova versão)
Identificador da operação: alterarManifestoTms
Alterar = reenviar o manifesto completo (D-06). O Veltra calcula o que entrou, saiu ou mudou, grava uma nova versão (versaoAtual + 1) e guarda o histórico. Trocar motorista, veículo ou ajudantes no meio da rota é permitido; o que já foi feito continua em nome de quem fez (D-09). - numeroExterno do corpo diferente do caminho = 400; mudar o tipo do manifesto = 400. - Um documento que sumiu da versão nova mas já tem baixa ou ocorrência NÃO é removido: o restante da alteração é aplicado e a resposta traz o motivo em erros[] (D-07). Um comprovante nunca some. - O manifesto é localizado no ambiente da API key e a alteração nunca muda o ambiente dele (D-25). Inexistente = 404. - Idempotência igual à do POST: mesma Idempotency-Key e mesmo corpo = mesma resposta; mesma chave com corpo diferente = 409. - Reenviar exatamente o conteúdo da versão atual (com outra Idempotency-Key) não cria versão nova.
Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
numeroExterno | path | texto | sim | Número do manifesto no TMS (chave natural, única por transportadora e ambiente).; mín. tamanho: 1; máx. tamanho: 60 |
Idempotency-Key | header | texto | sim | Chave de idempotência gerada pelo TMS (recomendado: UUID) por tentativa lógica de envio. Guardada por pelo menos 72 h, isolada por transportadora e ambiente (D-04, D-25). Repetir a mesma chave com o mesmo corpo devolve a resposta original; com corpo diferente = 409.; mín. tamanho: 1; máx. tamanho: 255 |
Corpo (application/json, obrigatório)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ajudantes | lista | não | Até 2 ajudantes (nome + CPF). Não são usuários do app, só dados do manifesto (D-23).; máx. itens: 2 |
ajudantes[] | objeto | não | Motorista ou ajudante citado no manifesto. |
ajudantes[].cpf | texto | sim | CPF com ou sem máscara (11 dígitos), validado pelos dígitos verificadores. |
ajudantes[].nome | texto | sim | máx. tamanho: 200 |
chaveMdfe | texto | não | Chave de acesso de 44 posições (NF-e, CT-e ou MDF-e). As 12 primeiras posições do CNPJ de quem emitiu o documento fiscal podem ser letras maiúsculas (CNPJ alfanumérico, em vigor desde 01/07/2026); o resto é numérico. O dígito verificador e o modelo são conferidos (INT-05).; mín. tamanho: 44; máx. tamanho: 44; padrão de formato: ^[0-9]{6}[0-9A-Z]{12}[0-9]{26}$ |
documentos | lista | sim | mín. itens: 1 |
documentos[] | objeto | não | Documento fiscal do manifesto (normalmente um CT-e com as NF que ele transporta). Chave do CT-e (modelo=57) é obrigatória; nos demais modelos é opcional, e sem ela o documento é identificado por numero + serie + cnpjEmbarcador (D-03, D-05). |
documentos[].chave | texto | não | Chave de acesso de 44 posições (NF-e, CT-e ou MDF-e). As 12 primeiras posições do CNPJ de quem emitiu o documento fiscal podem ser letras maiúsculas (CNPJ alfanumérico, em vigor desde 01/07/2026); o resto é numérico. O dígito verificador e o modelo são conferidos (INT-05).; mín. tamanho: 44; máx. tamanho: 44; padrão de formato: ^[0-9]{6}[0-9A-Z]{12}[0-9]{26}$ |
documentos[].cnpjEmbarcador | texto | não | CNPJ do embarcador, dono/emitente da NF (para modelo diferente de 57; obrigatório nesses casos). No CT-e não é usado: a chave já identifica o documento. Com ou sem máscara. |
documentos[].cnpjTransportadora | texto | não | CNPJ da transportadora que emitiu o CT-e (só faz sentido em modelo=57). Opcional: ausente, o Veltra usa o CNPJ da chave (posições 7 a 20). Se vier, é usado como enviado, sem checar contra a chave. Com ou sem máscara. |
documentos[].cteEmitidoEm | texto (date-time) | não | Opcional. Data e hora de emissão do CT-e. Sem a data base escolhida pela transportadora, o prazo conta da chegada do manifesto ao Veltra (D-14). prazoEntrega continua aceito. |
documentos[].destinatario | objeto | sim | |
documentos[].destinatario.cnpjCpf | texto | sim | CNPJ (numérico ou alfanumérico) ou CPF do destinatário/recebedor, com ou sem máscara. Obrigatório (D-24): agrupa as paradas (D-10) e identifica o link do destinatário (fase 7). |
documentos[].destinatario.email | texto (email) | não | Opcional. E-mail do destinatário para o aviso da entrega. Dado pessoal: não registrar em log. Ausente, o destinatário acompanha pelo link copiado no portal ou pela chave da NF.; máx. tamanho: 320 |
documentos[].destinatario.endereco | objeto | sim | Endereço de entrega/coleta do destinatário. Junto com o CNPJ/CPF, define a parada (D-10). |
documentos[].destinatario.nome | texto | sim | máx. tamanho: 200 |
documentos[].embarcador | objeto | não | Embarcador da mercadoria (opcional, D-02); quem embarca a mercadoria (cliente da transportadora). |
documentos[].embarcador.cnpjCpf | texto | sim | |
documentos[].embarcador.nome | texto | não | |
documentos[].globalizado | booleano | não | Opcional e aditivo (só modelo=57). CT-e globalizado (a SEFAZ admite mais de um comprovante para ele). Omitido = não globalizado.; padrão: False |
documentos[].latitude | número (double) | não | Opcional (INT-06). Se vier junto com longitude, é usada direto na parada; senão o endereço é geocodificado em segundo plano (D-13, D-26).; mínimo: -90; máximo: 90 |
documentos[].longitude | número (double) | não | mínimo: -180; máximo: 180 |
documentos[].modelo | enum | sim | 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[].nfVinculadas | lista | não | NF transportadas quando o documento é um CT-e (1 ou mais). Vazio/omitido nos demais modelos. |
documentos[].nfVinculadas[] | objeto | não | NF transportada pelo CT-e. A chave da NF-e (modelo 55) normalmente vem, mas é opcional (D-03); o perfil Comprovante Digital Homologado usa essas chaves como lista de NF-e do CT-e (sem chave, o evento fica PENDENTE_DE_DADOS); sem ela, a NF é identificada por número + série + CNPJ de quem emitiu o documento fiscal e a chave é vinculada quando chegar depois (INT-02). A mesma NF pode estar em vários CT-e (CARGA-01). |
documentos[].numero | texto | sim | máx. tamanho: 20 |
documentos[].peso | número (double) | não | Peso em kg.; mínimo: 0 |
documentos[].prazoEntrega | texto (date) | não | Prazo de entrega, quando houver (INT-06). Continua aceito. Sem a data base escolhida pela transportadora (cteEmitidoEm, nfeEmitidoEm ou este campo), o prazo conta da chegada do manifesto ao Veltra (D-14). |
documentos[].protocoloAutorizacao | texto | não | Opcional e aditivo (só modelo=57). Protocolo de autorização do CT-e (nProt, 15 dígitos, do protCTe). Necessário ao perfil Comprovante Digital Homologado (evento 110180). Sem ele, o evento do CT-e fica PENDENTE_DE_DADOS no portal; a entrega continua sendo comprovada pelo comprovante interno do Veltra. Clientes que não enviam o campo seguem funcionando como antes.; padrão de formato: ^[0-9]{15}$ |
documentos[].serie | texto | não | máx. tamanho: 10 |
documentos[].tarefa | enum | não | O que o motorista faz com o documento na parada. Coleta e entrega no mesmo cliente e no mesmo manifesto ficam na mesma parada, com as duas tarefas (D-12).; valores: ENTREGA, COLETA |
documentos[].tipoServico | enum | não | Opcional e aditivo (só modelo=57). Tipo de serviço do CT-e (tpServ): NORMAL (0), SUBCONTRATACAO (1), REDESPACHO (2), REDESPACHO_INTERMEDIARIO (3), SERVICO_VINCULADO_MULTIMODAL (4). O evento 110180 só lista as NF-e entregues em CT-e NORMAL.; valores: NORMAL, SUBCONTRATACAO, REDESPACHO, REDESPACHO_INTERMEDIARIO, SERVICO_VINCULADO_MULTIMODAL |
documentos[].tomadorCnpj | texto | não | Opcional e aditivo (só modelo=57). CNPJ de quem paga o frete (tomador do CT-e), numérico ou alfanumérico, com ou sem máscara. Ausente, nenhum terceiro recebe PDF nem canhoto (D-12). |
documentos[].valor | número (double) | não | Valor do documento em reais, para exibição na torre; não é usado em cálculo (desde a 0.4.0).; mínimo: 0 |
documentos[].volumes | inteiro | não | mínimo: 0 |
filialDestinoSigla | texto | não | siglaExterna da filial de destino. Obrigatória quando tipo=TRANSFERENCIA. |
filialOrigemSigla | texto | não | siglaExterna da filial de origem. Obrigatória quando tipo=TRANSFERENCIA (D-10 da fase 1, INT-03); sigla desconhecida = 400. |
motorista | objeto | sim | Motorista ou ajudante citado no manifesto. |
motorista.cpf | texto | sim | CPF com ou sem máscara (11 dígitos), validado pelos dígitos verificadores. |
motorista.nome | texto | sim | máx. tamanho: 200 |
numeroExterno | texto | sim | Número do manifesto/relatório no TMS. Chave natural, única por transportadora e ambiente (D-04).; mín. tamanho: 1; máx. tamanho: 60 |
quantidadePaletes | inteiro | não | Quantidade de paletes informada no manifesto (D-23).; mínimo: 0 |
tipo | enum | sim | 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 |
veiculo | objeto | sim | |
veiculo.placa | texto | sim | Placa de tração (padrão antigo ou Mercosul), com ou sem hífen. Chave de upsert do veículo (D-09 da fase 1). |
Respostas
| Código | Descrição |
|---|---|
| 200 | Manifesto alterado (ou reenvio idempotente) |
| 400 | Manifesto recusado por inteiro (RFC 9457). Quando o problema está em documentos específicos e nenhum documento pôde ser aceito, o membro de extensão erros lista o motivo de cada um. |
| 401 | Erro no formato RFC 9457 (application/problem+json) |
| 404 | Erro no formato RFC 9457 (application/problem+json) |
| 409 | Conflito (RFC 9457): Idempotency-Key repetida com corpo diferente, ou POST de um numeroExterno que já existe no ambiente. |
| demais erros | Erro no formato RFC 9457 (application/problem+json) |
Corpo da resposta 200 (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ambiente | enum | sim | Ambiente da credencial — sandbox e produção nunca se misturam (D-03); valores: TESTE, PRODUCAO |
documentos | lista | não | Documentos ativos na versão atual, com o status de cada um. |
documentos[] | objeto | não | Situação atual de um documento no manifesto. |
documentos[].chave | string/null | não | |
documentos[].id | texto (uuid) | sim | |
documentos[].modelo | enum | sim | 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[].nfVinculadas | lista | não | Situação de cada NF do CT-e (o status é por NF). |
documentos[].nfVinculadas[] | objeto | não | |
documentos[].numero | texto | sim | |
documentos[].serie | string/null | não | |
documentos[].status | enum | sim | Status controlado por documento, não por manifesto (CARGA-01). Na fase 2 só aparecem PENDENTE, EM_TRANSPORTE e CANCELADO; ENTREGUE, ENTREGUE_PARCIAL e DEVOLVIDO chegam com as baixas (fase 4, D-14).; valores: PENDENTE, EM_TRANSPORTE, ENTREGUE, ENTREGUE_PARCIAL, DEVOLVIDO, CANCELADO |
erros | lista | não | Documentos recusados nesta chamada (D-07). Ausente ou vazio quando tudo foi aceito. |
erros[] | objeto | não | Recusa de um documento específico (D-07). O resto do manifesto é aplicado normalmente. |
erros[].chave | string/null | não | Chave do documento, quando houver. |
erros[].codigo | enum | sim | 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[].documentoIndex | integer/null | não | Í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[].motivo | texto | sim | Explicação em pt-BR. |
erros[].numero | string/null | não | Número do documento, quando houver. |
id | texto (uuid) | sim | |
numeroExterno | texto | sim | |
quantidadeDocumentos | inteiro | não | |
quantidadeParadas | inteiro | não | |
tipo | enum | sim | 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 |
versaoAtual | inteiro | sim | Versão atual do manifesto (1 na criação; +1 a cada alteração, D-06).; mínimo: 1 |
POST /integracao/v1/manifestos/{numeroExterno}/cancelar#
Cancela o que ainda falta de um manifesto (cancelamento parcial)
Identificador da operação: cancelarManifestoTms
Cancela só os documentos que ainda não foram entregues ou coletados (D-08). O que já foi feito permanece, com o comprovante. Os documentos cancelados saem do app do motorista (fase 3). Cancelar de novo um manifesto já cancelado responde 200 com a mesma situação (idempotente por natureza). O manifesto é localizado no ambiente da API key; inexistente = 404.
Autenticação: cabeçalho X-Veltra-Api-Key (chave de API)
Parâmetros
| Nome | Onde | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
numeroExterno | path | texto | sim | Número do manifesto no TMS (chave natural, única por transportadora e ambiente).; mín. tamanho: 1; máx. tamanho: 60 |
Corpo (application/json, opcional)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
motivo | texto | não | Motivo do cancelamento, registrado na linha do tempo de cada documento cancelado.; máx. tamanho: 500 |
Respostas
| Código | Descrição |
|---|---|
| 200 | Situação do manifesto depois do cancelamento |
| 401 | Erro no formato RFC 9457 (application/problem+json) |
| 404 | Erro no formato RFC 9457 (application/problem+json) |
| demais erros | Erro no formato RFC 9457 (application/problem+json) |
Corpo da resposta 200 (application/json)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
ambiente | enum | sim | Ambiente da credencial — sandbox e produção nunca se misturam (D-03); valores: TESTE, PRODUCAO |
documentos | lista | não | Documentos ativos na versão atual, com o status de cada um. |
documentos[] | objeto | não | Situação atual de um documento no manifesto. |
documentos[].chave | string/null | não | |
documentos[].id | texto (uuid) | sim | |
documentos[].modelo | enum | sim | 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[].nfVinculadas | lista | não | Situação de cada NF do CT-e (o status é por NF). |
documentos[].nfVinculadas[] | objeto | não | |
documentos[].numero | texto | sim | |
documentos[].serie | string/null | não | |
documentos[].status | enum | sim | Status controlado por documento, não por manifesto (CARGA-01). Na fase 2 só aparecem PENDENTE, EM_TRANSPORTE e CANCELADO; ENTREGUE, ENTREGUE_PARCIAL e DEVOLVIDO chegam com as baixas (fase 4, D-14).; valores: PENDENTE, EM_TRANSPORTE, ENTREGUE, ENTREGUE_PARCIAL, DEVOLVIDO, CANCELADO |
erros | lista | não | Documentos recusados nesta chamada (D-07). Ausente ou vazio quando tudo foi aceito. |
erros[] | objeto | não | Recusa de um documento específico (D-07). O resto do manifesto é aplicado normalmente. |
erros[].chave | string/null | não | Chave do documento, quando houver. |
erros[].codigo | enum | sim | 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[].documentoIndex | integer/null | não | Í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[].motivo | texto | sim | Explicação em pt-BR. |
erros[].numero | string/null | não | Número do documento, quando houver. |
id | texto (uuid) | sim | |
numeroExterno | texto | sim | |
quantidadeDocumentos | inteiro | não | |
quantidadeParadas | inteiro | não | |
tipo | enum | sim | 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 |
versaoAtual | inteiro | sim | Versão atual do manifesto (1 na criação; +1 a cada alteração, D-06).; mínimo: 1 |