Manual da API · Webhooks

Retoma um assinante de webhook (só ADMIN)

POST/v1/integracoes/webhooks/{id}/retomada

Perfil ADMIN.

Rota de administrador. Usa a sessão do portal em Authorization: Bearer; o TMS não a chama com a chave de API.

Parâmetros

Cabeçalhos (header)

Authorizationtextoobrigatório
Sessão do administrador no portal: Bearer seguido do token. Rota de administrador; o TMS não a chama com a chave de API.

Caminho (path)

idtexto (uuid)obrigatório

Respostas

200application/json

Assinante retomado

JSON

{
  "nome": "texto",
  "ambiente": "PRODUCAO",
  "url": "https://exemplo.com.br/webhook-veltra",
  "tipos": [
    "parada.chegada"
  ],
  "papel": "TMS",
  "escopoCnpjs": [
    "texto"
  ],
  "cadenciaPosicaoMin": 5,
  "contatoEmail": "texto",
  "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
  "situacao": "ATIVO",
  "criadoEm": "2026-11-06T09:15:00-03:00",
  "segredoAlteradoEm": "2026-11-06T09:15:00-03:00"
}

Campos da resposta (12)

Campos

nometextoobrigatório
de 1 a 120 caracteres
ambientetexto (lista fixa)opcional
Desde a 0.21.0. Ambiente do assinante; não muda depois de criado. Em PRODUCAO a url precisa ser https. http e endereço local só valem em TESTE. Na atualização, omitido mantém o atual.
Valores: TESTE, PRODUCAO; padrão: "PRODUCAO"
urltextoobrigatório
Endereço público HTTPS. Endereço interno é recusado.
tiposlista de texto (lista fixa)obrigatório
Valores: parada.chegada, parada.saida, baixa.registrada, ocorrencia.registrada, comprovante.emitido, evento_cte.estado_alterado, posicao.lote, veiculo.km_registrado; ao menos 1 item(ns)
papeltexto (lista fixa)obrigatório
Valores: TMS, TERCEIRO
escopoCnpjslista de textoopcional
Raízes de 8 caracteres. Obrigatório quando papel é TERCEIRO. PDF e canhoto só saem se o terceiro for o tomador.
cadenciaPosicaoMintexto (lista fixa)opcional
Só para papel TMS e tipo posicao.lote. Embarcador e destinatário não recebem posição.
Valores: 5, 10, 15
contatoEmailtextoobrigatório
Dado pessoal. Não registrar em log.
até 320 caracteres
idtexto (uuid)obrigatório
situacaotexto (lista fixa)obrigatório
Valores: ATIVO, PAUSADO, COM_FALHAS, DESATIVADO
criadoEmtexto (data e hora ISO 8601)opcional
segredoAlteradoEmtexto (data e hora ISO 8601)opcional

Erroapplication/problem+json

Erro no formato RFC 9457 (application/problem+json)

JSON

{
  "type": "https://veltra.com.br/problemas/validacao",
  "title": "Requisição inválida",
  "status": 400,
  "detail": "O campo cpf é obrigatório",
  "instance": "https://exemplo.com.br/webhook-veltra",
  "codigo": "TERMO_NAO_ACEITO"
}

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.: TERMO_NAO_ACEITO, RETENCAO_MENOR_QUE_MINIMA, REAUTENTICACAO_NECESSARIA). Ausente quando o erro não tem código próprio.