Autenticação
Duas camadas, sempre juntas: o token prova que a credencial é sua; a assinatura prova que o request saiu do servidor que tem a chave privada. Uma sem a outra não move dinheiro.
O par de chaves é gerado por você antes da emissão da credencial: a pública vai para a tela do internet banking, a privada fica no seu servidor. Passo a passo em Gerar o par de chaves; código completo (token + assinatura + chamadas) em Exemplos de código.
Token
O endereço é o token_url que a tela mostrou na emissão, junto com
client_id e client_secret.
O mesmo access_token vale em todas as chamadas até expirar. Guarde-o e
só peça outro quando faltar cerca de 60 segundos, ou quando a API recusar o
token. Leia o expires_in da resposta — não fixe 300 no cliente.
scope é opcional. Omitir devolve um token com todos os escopos da
credencial. Enviar um subconjunto (separado por espaço) restringe aquele
token.
Headers em toda chamada à API
Host: https://client.api.corpx.com.
Como montar os três headers de assinatura está no guia de assinatura.
GET /v1/me também exige esses headers (é /v1/** no host assinado), mas
não exige X-Tenant-Id.
Conferir o token: GET /v1/me
A resposta traz clientId, scopes e tenantRoles[] com os contextos em
que o token vale. Para uma credencial de internet banking, sub e clientId
são o mesmo valor.
O que esta credencial alcança
Ela foi emitida para uma conta. Chamadas a outra conta respondem 403 forbidden.
PIN e travas de horário / IP de origem são da tela do internet banking.
Nas rotas de pagamento você não envia X-Transaction-Pin nem
X-Acting-Document: a posse já está na chave privada e no IP da credencial.
Carência de 18 horas
A emissão devolve activeFrom 18h à frente. Até lá: 403 credential_not_yet_active. Incluir uma chave pública ou um IP novos na
credencial usa a mesma carência; remover chave ou IP vale na hora. Detalhe
em Chaves e IPs.
Para encerrar antes das 18h a carência da credencial ou de um IP novo na allowlist dela, abra um ticket com o internet banking. Quem antecipa é a CorpX, com o ticket e a aprovação de um administrador diferente de quem pediu. Nem a credencial nem o master que a emitiu conseguem antecipá-la pela API.