> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/ib/guias/comece-aqui/visao-geral/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# A API da sua conta

> **Beta**
>
> A API de Internet banking está em **beta**, disponível só para usuários
> convidados pelo banco. Contratos, escopos e comportamentos ainda podem mudar
> sem o ciclo de depreciação da API BaaS em produção. Em dúvida, fale com o
> banco ou com o suporte CorpX antes de ir a produção.

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](/ib/guias/comece-aqui/primeiros-passos): token, assinatura de teste e o
primeiro saldo. Se um agente ou LLM for integrar por você, peça que leia
[For agents](/ib/guias/referencia/para-agentes) e o [openapi.yaml](https://docs.api.corpx.com/openapi.yaml)
filtrado por `x-audience` contendo `ib`.