Emite uma nova API key para a transportadora autenticada

POST/v1/api-keys

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.

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

Para que serve: emite uma chave de API nova para a transportadora do administrador logado.

Quando chamar: ao começar a integração (uma chave de teste), ao ir para produção (uma chave de produção) e ao trocar uma chave que vazou.

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
Rótulo/descrição da chave (ex.; "TMS produção")
ambientetexto (lista fixa)obrigatório
Ambiente da credencial — sandbox e produção nunca se misturam
Valores: TESTE, PRODUCAO

Exemplos de corpo

JSON

{
  "nome": "texto",
  "ambiente": "TESTE"
}

Respostas

201application/json

API key emitida

JSON

{
  "id": "0192f3a4-5b6c-7d8e-9f01-23456789abcd",
  "nome": "texto",
  "ambiente": "TESTE",
  "apiKeyValorEmClaro": "texto",
  "apiKeyPrefixo": "texto",
  "criadaEm": "2026-11-06T09:15:00-03:00",
  "revogadaEm": "2026-11-06T09:15:00-03:00"
}

Campos da resposta (7)

Campos

idtexto (uuid)obrigatório
nometextoobrigatório
ambientetexto (lista fixa)obrigatório
Ambiente da credencial — sandbox e produção nunca se misturam
Valores: TESTE, PRODUCAO
apiKeyValorEmClarotextoopcional
Presente somente na resposta de criação (T-01-02-01).
apiKeyPrefixotextoobrigatório
criadaEmtexto (data e hora ISO 8601)obrigatório
revogadaEmtexto (data e hora ISO 8601) ou nuloopcional

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`	Falta `nome` ou `ambiente`, ou nome acima de 120 caracteres	Corrigir o corpo
`401`	Sessão do portal ausente ou vencida	Entrar de novo
`403`	O usuário não é administrador	Pedir a um administrador
`409`	Chave de `PRODUCAO` para transportadora que ainda não está ativa (em homologação ou inativa)	Pedir ao Veltra para concluir a homologação

Observações

emitir várias chaves é permitido. Revogue as que não usa mais.

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