Emite uma chave de consulta e devolve o valor uma vez (só ADMIN)

POST/v1/integracoes/chaves

Perfil ADMIN. Finalidade CONSULTA_EMBARCADOR e CONSULTA_DESTINATARIO exigem escopoCnpjs não vazio (raízes de 8 caracteres), expiraEm e limitePorMinuto. A chave só consulta. CPF nunca é exibido. PDF e canhoto só saem para quem paga o frete.

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

Corpo (body) · application/json

nometextoobrigatório
de 1 a 120 caracteres
finalidadetexto (lista fixa)obrigatório
Valores: INTEGRACAO_TMS, CONSULTA_EMBARCADOR, CONSULTA_DESTINATARIO
escopoCnpjslista de textoopcional
Obrigatório e não vazio para CONSULTA_EMBARCADOR e CONSULTA_DESTINATARIO. Cada item é a raiz de 8 caracteres.
expiraEmtexto (data e hora ISO 8601)obrigatório
limitePorMinutointeiroobrigatório
de 1 a 600

Exemplos de corpo

JSON

{
  "nome": "texto",
  "finalidade": "INTEGRACAO_TMS",
  "escopoCnpjs": [
    "texto"
  ],
  "expiraEm": "2026-11-06T09:15:00-03:00",
  "limitePorMinuto": 1
}

Respostas

201application/json

Chave emitida; o valor aparece uma única vez

JSON

{
  "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
  "nome": "texto",
  "finalidade": "INTEGRACAO_TMS",
  "prefixo": "texto",
  "escopoCnpjs": [
    "texto"
  ],
  "situacao": "ATIVA",
  "expiraEm": "2026-11-06T09:15:00-03:00",
  "limitePorMinuto": 1,
  "ultimoUsoEm": "2026-11-06T09:15:00-03:00",
  "chave": "texto"
}

Campos da resposta (10)

Campos

idtexto (uuid)obrigatório
nometextoobrigatório
finalidadetexto (lista fixa)obrigatório
Valores: INTEGRACAO_TMS, CONSULTA_EMBARCADOR, CONSULTA_DESTINATARIO
prefixotextoobrigatório
escopoCnpjslista de textoopcional
situacaotexto (lista fixa)obrigatório
Valores: ATIVA, REVOGADA, EXPIRADA
expiraEmtexto (data e hora ISO 8601)obrigatório
limitePorMinutointeiroobrigatório
ultimoUsoEmtexto (data e hora ISO 8601) ou nuloopcional
chavetextoobrigatório
Valor completo, exibido uma única vez. Não registrar em log.

409application/problem+json

Módulo de chaves de consulta não habilitado para a conta (MODULO_NAO_HABILITADO, no campo codigo).

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.

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.