Getting Started

Este é o caminho mais rápido para começar a consumir a Banking API.

Se você está começando agora, use esta página como guia rápido para sair do zero até sua primeira chamada autenticada.

✨ O que você vai concluir ao final

Ao concluir este guia, você terá:

1. Um certificado de cliente pronto para uso
2. Uma credencial ativa com client_id e client_secret
3. Um token emitido com sucesso
4. Sua primeira chamada autenticada à API

✅ Pré-requisitos

Antes de começar, você precisa ter:

• acesso ao ambiente correto da Banking API
• acesso ao CORE para criar a credencial e o certificado
• uma ferramenta ou biblioteca que suporte mTLS

Exemplos:

• curl
• Bruno
• Postman
• seu backend próprio

🧭 Fluxo resumido

1. Criar certificado no CORE
2. Criar credencial e vincular o certificado
3. Obter token em /auth/token-v2 com mTLS
4. Usar o token nas chamadas protegidas

🔐 Passo 1: Criar o certificado

No CORE:

1. Acesse Painel Gerencial ONZ > API do Core
2. Escolha um destes caminhos:
   • criar uma nova credencial completa já com certificado
   • cadastrar um certificado existente
   • emitir um novo certificado pela CA do ambiente
3. Baixe o material gerado:
   • client.crt + client.key, ou
   • client.pfx
4. Armazene o material em local seguro

Dica

Se for sua primeira integração, o fluxo de nova credencial completa costuma ser o mais simples.

🪪 Passo 2: Criar a credencial

Ainda no CORE:

1. Defina o Client ID
2. Configure os IPs permitidos para a credencial
3. Vincule o certificado que será usado no mTLS
4. Salve a credencial
5. Copie o Client Secret

Ao final, você terá:

• client_id
• client_secret
• certificado de cliente
• chave privada ou PFX
• base URL do ambiente

🔑 Passo 3: Obter token

O endpoint atual de autenticação é:

POST /public/gw_banking/v1/auth/token-v2

A chamada deve ser feita com:

• mTLS usando o certificado vinculado à credencial
• corpo JSON
• grant_type: client_credentials

Exemplo com curl

curl -X POST https://api.bancodigital.com/public/gw_banking/v1/auth/token-v2 \
  --cert client.crt \
  --key client.key \
  --cacert ca.crt \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "seu-client-id",
    "client_secret": "seu-client-secret",
    "grant_type": "client_credentials"
  }'

Resposta de sucesso

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

🚀 Passo 4: Fazer sua primeira requisição

Use o mesmo certificado mTLS da etapa anterior e envie o token no header Authorization.

curl -X GET "https://api.bancodigital.com/public/gw_banking/v1/accounts/123/balance" \
  --cert client.crt \
  --key client.key \
  --cacert ca.crt \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Exemplo de resposta

{
  "accountId": "123",
  "balance": {
    "available": 1500.5,
    "current": 2000.0,
    "blocked": 500.5
  },
  "currency": "BRL",
  "lastUpdated": "2025-11-19T10:30:00Z"
}

💻 Exemplo em Node.js

import axios from 'axios';
import https from 'https';
import { readFileSync } from 'fs';

const API_BASE_URL = 'https://api.bancodigital.com';
const CLIENT_ID = process.env.CLIENT_ID!;
const CLIENT_SECRET = process.env.CLIENT_SECRET!;

const httpsAgent = new https.Agent({
  cert: readFileSync(process.env.CERT_PATH!),
  key: readFileSync(process.env.KEY_PATH!),
  ca: readFileSync(process.env.CA_PATH!),
});

async function getToken() {
  const response = await axios.post(
    `${API_BASE_URL}/public/gw_banking/v1/auth/token-v2`,
    {
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
      grant_type: 'client_credentials',
    },
    {
      headers: { 'Content-Type': 'application/json' },
      httpsAgent,
    },
  );

  return response.data.access_token;
}

async function getBalance(token: string, accountId: string) {
  const response = await axios.get(
    `${API_BASE_URL}/public/gw_banking/v1/accounts/${accountId}/balance`,
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
      httpsAgent,
    },
  );

  return response.data;
}

(async () => {
  const token = await getToken();
  const balance = await getBalance(token, '123');
  console.log(balance);
})();

🧯 Erros comuns

401 Invalid Credentials

O client_id ou client_secret está incorreto.

401 Invalid Client Certificate

O certificado enviado na conexão mTLS:

• não corresponde ao certificado vinculado à credencial
• está inválido ou expirado
• foi emitido por uma CA não aceita no ambiente

403 Forbidden

O IP de origem da requisição não está na allowlist configurada para a credencial.

📚 Próximos Passos

1. Authentication & mTLS
2. Partner Onboarding
3. Balance Flow