A API da sua conta

O banco em que você tem conta oferece um internet banking. De lá, o titular pode emitir uma credencial para o seu sistema — o ERP, o site, o app de cobrança — falar com a conta sem passar pela tela.

Esta documentação é para quem recebeu essa credencial. Você não está virando banco e não opera as contas de outras pessoas: a credencial alcança uma conta, a do titular que autorizou.

Quem é quem

Papel	O que faz
Você	Guarda a chave privada, chama a API, recebe webhooks da conta
O banco	Emite e revoga a credencial no internet banking; o titular configura travas e PIN na tela
A CorpX	Opera o host `https://client.api.corpx.com` e o contrato desta API

Problemas de credencial, IP, chave pública ou trava de saída se resolvem no internet banking do banco. A API só recusa ou aceita o que já está configurado.

O que muda em relação a um integrador BaaS

Integradores da CorpX usam https://tenant.api.corpx.com e um token. A sua credencial é outra: o token sozinho não basta. Toda chamada a /v1/** vai para https://client.api.corpx.com e leva uma assinatura (JWS) feita com a chave privada que ficou no seu servidor.

O motivo é direto. O token OAuth é um portador — quem o copia do log ou do proxy pode usá-lo até expirar. A chave privada nunca sai do seu servidor, então um token vazado sem ela não move dinheiro.

O que você recebeu

Na emissão, o internet banking mostra (uma vez) e você guarda:

Item	Para que serve
`clientId` e `clientSecret`	Pedir o token em `https://auth.api.corpx.com/oauth2/token`
`X-Tenant-Id`	O identificador que o banco mostrou. Entra em toda chamada — é o contexto da conta, não um valor que você inventa
`accountId`	A conta que a credencial alcança. Entra no path (`/v1/accounts/{accountId}/…`) e no webhook
Par de chaves	A privada fica no seu servidor. A pública já foi cadastrada; o `kid` identifica qual chave assinou
Allowlist de IPs	De quais endereços a API aceita a sua chamada. Pedido de outro IP é recusado na borda

A credencial só passa a aceitar chamadas depois de 18 horas (activeFrom). Até lá a resposta é 403 credential_not_yet_active. Revogar no painel do banco vale na hora. A carência existe para um alerta chegar a um humano se alguém emitiu a credencial sem o titular querer.

Glossário curto

Termo	Significado
`accountId`	Identificador da conta na API (UUID). Uma credencial, uma conta
`X-Tenant-Id`	Slug que o banco mostrou. Sem ele a API não sabe de qual contexto você fala
`kid`	Identificador da chave pública, derivado do SHA-256 dela. Confira offline que cadastrou a chave certa
`activeFrom`	Instantâneo a partir do qual a credencial (ou uma chave / IP novos) passa a valer
`Idempotency-Key`	Identidade da tentativa HTTP em POST/PUT/PATCH que movem dinheiro. Repetir a mesma chave devolve o resultado da original, sem um segundo pagamento
`identifier`	Sua chave de conciliação no corpo. Aparece no extrato e no webhook. É outra coisa que a `Idempotency-Key`

Próximo passo

Siga o Início rápido: token, assinatura de teste e o primeiro saldo. Se um agente ou LLM for integrar por você, peça que leia For agents e o openapi.yaml filtrado por x-audience contendo ib.