Início rápido
A API de Internet banking está em beta — só para usuários convidados pelo banco. Veja o aviso em A API da sua conta.
Do internet banking até o primeiro saldo. Reserve uns minutos e um servidor com relógio sincronizado (NTP): a assinatura recusa um desvio maior que 5 minutos.
Antes de começar
- Guarde
clientId,clientSecret,X-Tenant-IdeaccountIdem variáveis de ambiente — não em repositório. - A chave privada fica só no servidor que vai assinar. A pública foi
cadastrada na emissão da credencial; anote o
kid. Ainda não gerou o par? Veja Gerar o par de chaves. - O IP de saída desse servidor precisa estar na allowlist da credencial.
- Espere o
activeFrom(18 horas após a emissão). Antes disso, qualquer chamada responde403 credential_not_yet_active. Isso é proteção, não um defeito.
Se a credencial ainda não existe, peça ao titular para emiti-la no internet banking do banco, colando a chave pública que você gerou — o passo a passo mostra o que preencher.
Código completo, do token ao primeiro PIX, em Exemplos de código.
1. Pedir o token
O token vale 5 minutos. Guarde-o e reutilize até perto de expirar — um token por request esgota o emissor e pode ser recusado.
2. Conferir a assinatura sem mover dinheiro
Toda chamada a https://client.api.corpx.com/v1/** leva, além do token e do
X-Tenant-Id:
Antes do primeiro saldo, use POST /v1/security/signature/verify. Ele devolve
a string canônica que nós montamos e valid: true|false, sem criar nada.
Quando valid é false, compare canonicalString caractere a caractere com
a sua: o problema quase sempre é CRLF, path sem query ou timestamp em
milissegundos.
Há um vetor de teste com chave pública, string canônica e JWS prontos para validar a implementação offline.
3. Primeiro saldo
Com a assinatura conferida:
GET não tem corpo: o hash é sempre o do vazio, acima.
Valores monetários são BRL com no máximo 2 casas decimais.
Se você apontar esta credencial para https://tenant.api.corpx.com, a
resposta é 403 signed_host_required. O host antigo não verifica assinatura
por request.
4. Confirmar quem você é
GET /v1/me (também no host assinado) devolve clientId, scopes e os
contextos em que o token vale. Use para conferir que o X-Tenant-Id que você
vai enviar está na lista.
Checklist do primeiro dia
- Token reutilizado até
expires_in -
POST /v1/security/signature/verifycomvalid: true -
GET /v1/accounts/{accountId}/balanceno hostclient.api.corpx.com - Relógio do servidor com NTP
- Chave privada fora do repositório e de logs
Depois
- Autenticação — headers e o que a credencial alcança
- Gerar o par de chaves —
openssl, impressão digital, cadastro e rotação - Assinatura — string canônica, Node, vetor de teste
- Exemplos de código — bash, Node.js, Python e Go completos
- Sua conta — extrato, dados bancários, exportações
- Receber e Pagar
- Webhooks —
accountIdé obrigatório - Ir para produção
Contrato: Referência da API. Filtre operações com
x-audience contendo ib.