Skip to main content
Rascunho: especificação em definição. Endpoints e campos podem mudar.

​
Chaves de API

Cada chave pertence a uma organização e é criada no painel por um usuário administrador. A chave completa aparece uma única vez, no momento da criação. A chave vai no cabeçalho Authorization de toda requisição:
A chave de API autentica a integração com a TESA. Ela não assina transações e não dá acesso às chaves da carteira, que continuam com a empresa ou o seu custodiante.

​
Escopos

Cada chave recebe um ou mais escopos. Uma chamada fora do escopo retorna 403. A recomendação é separar funções: a integração do ERP usa read e propose, e a aprovação fica com uma chave admin guardada em ambiente restrito, ou apenas no painel.

​
Rotação

  • Uma organização pode ter mais de uma chave ativa ao mesmo tempo, o que permite rotação sem janela de indisponibilidade.
  • O fluxo sugerido é criar a nova chave, atualizar a integração e revogar a antiga.
  • Chaves revogadas deixam de funcionar na hora. Cada chave registra data de criação, último uso e autor.

​
Allowlist de IP

Chaves de produção podem ser restritas a uma lista de IPs ou blocos CIDR. Requisições de fora da lista retornam 403 com o código ip_nao_autorizado. A proposta é tornar a allowlist obrigatória para chaves com escopo admin.

​
Assinatura de requisição (HMAC)

Além da chave, requisições que alteram estado (POST, PUT) podem ser assinadas com um segredo HMAC da organização, distinto da chave de API. A proposta é que a assinatura seja obrigatória para chaves com escopo admin. A mensagem canônica junta, separados por quebra de linha: o timestamp, o método, o caminho com query string e o corpo bruto da requisição.
Requisições com timestamp fora de uma janela de 5 minutos são recusadas com 401, o que impede reenvio de uma requisição capturada.

​
Idempotência

Toda requisição POST aceita o cabeçalho Idempotency-Key, com um valor único gerado pela integração (um UUID, por exemplo).
  • Repetir a mesma chave com o mesmo corpo devolve a resposta original, sem criar uma segunda operação.
  • Repetir a mesma chave com corpo diferente retorna 409 com o código conflito_idempotencia.
  • As chaves ficam guardadas por 24 horas.
Em resgates e aprovações, o uso de Idempotency-Key é obrigatório. Uma falha de rede não deve gerar duas solicitações de resgate.

​
Limites de taxa

Os limites valem por chave e são detalhados em Erros e limites. Toda resposta traz os cabeçalhos RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset.