Cancela o que ainda falta de um manifesto (cancelamento parcial)

POST/integracao/v1/manifestos/{numeroExterno}/cancelar

Cancela só os documentos que ainda não foram entregues ou coletados. O que já foi feito permanece, com o comprovante. Os documentos cancelados saem do app do motorista. 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.

Para que serve: cancela o que ainda falta de um manifesto (cancelamento parcial).

Quando chamar: quando a viagem foi desfeita (veículo quebrou, carga redistribuída). Os documentos cancelados saem do app do motorista.

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.
Content-Typetextoobrigatório
Sempre application/json.

Caminho (path)

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

Corpo (body) · application/json · opcional

motivotextoopcional
Motivo do cancelamento, registrado na linha do tempo de cada documento cancelado.
até 500 caracteres

Exemplos de corpo

JSON

{
  "motivo": "Veículo quebrado; carga redistribuída em outro manifesto"
}

Respostas

200application/json

Situação do manifesto depois do cancelamento

JSON

{
  "id": "0192f3a4-5b6c-7d8e-9f01-000000000001",
  "numeroExterno": "REL-2026-000123",
  "tipo": "ENTREGA",
  "ambiente": "PRODUCAO",
  "versaoAtual": 2,
  "quantidadeParadas": 1,
  "quantidadeDocumentos": 2,
  "documentos": [
    {
      "id": "0192f3a4-5b6c-7d8e-9f01-000000000010",
      "modelo": 57,
      "chave": "35260911222333000181570010000123451482135762",
      "numero": "12345",
      "serie": "1",
      "status": "CANCELADO"
    },
    {
      "id": "0192f3a4-5b6c-7d8e-9f01-000000000012",
      "modelo": 57,
      "chave": "35260911222333000181570010000123461918273641",
      "numero": "12346",
      "serie": "1",
      "status": "ENTREGUE"
    }
  ]
}

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
`400`	`motivo` com mais de 500 caracteres	Encurtar
`401`	Chave inválida	Conferir a chave
`403`	Chave sem permissão	Usar a chave de TMS
`404`	O manifesto não existe neste ambiente	Conferir o `numeroExterno` e o ambiente

Observações

Cancelar de novo é seguro: responde 200 com a mesma situação, sem mudar nada.
O cancelamento é por documento: só o que ainda não foi entregue nem coletado é cancelado.
Cancelar não gera webhook de manifesto.

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