displayed_sidebar: bankingApiSidebar

Onboarding do Parceiro

Este guia apresenta o passo a passo completo para que sua instituição parceira se conecte à Banking API, desde a configuração da infraestrutura até a primeira requisição bem-sucedida.

📋 Visão Geral

O processo de onboarding envolve múltiplas camadas de segurança que devem ser configuradas em ordem:

Infraestrutura de Rede (VPC, Firewall, etc)
Certificados mTLS (Mutual TLS)
Credenciais OAuth2 (Client ID e Client Secret)
Testes de Conectividade
Primeira Requisição

🎯 Pré-requisitos

Antes de começar, certifique-se de que:

✅ Você já implementou os Requisitos de Segurança
✅ Você tem um BFF (Backend for Frontend) pronto
✅ Você tem um sistema de autenticação funcionando
✅ Você tem controle de usuários implementado

📞 Iniciando o Processo

Para iniciar o processo de onboarding, entre em contato com nossa equipe:

Email: [email protected]
Assunto: "Solicitação de Onboarding - Banking API"
Informações necessárias:
- Nome da instituição
- CNPJ
- Ambiente desejado (Development, Staging, Production)
- IPs públicos que farão requisições (para whitelist)

🔐 Fase 1: Configuração de Infraestrutura

1.1 Configuração de Rede (VPC)

Nossa API está protegida por uma VPC (Virtual Private Cloud). Você precisará configurar sua infraestrutura para se conectar.

O que você precisa fornecer:

IPs públicos dos servidores que farão requisições
CIDR blocks (se aplicável) da sua infraestrutura
Ambiente (Development, Staging, Production)

O que nós fazemos:

Adicionamos seus IPs à whitelist da VPC
Configuramos rotas de rede
Fornecemos informações de conectividade

Tempo estimado: 2-3 dias úteis

1.2 Configuração de Firewall

Certifique-se de que seu firewall permite conexões HTTPS (porta 443) para:

Development: api-dev.bancodigital.com
Staging: api-staging.bancodigital.com
Production: api.bancodigital.com

Exemplo de regra de firewall:

# Permitir saída HTTPS para Banking API
iptables -A OUTPUT -p tcp --dport 443 -d api.bancodigital.com -j ALLOW

1.3 Teste de Conectividade

Após a configuração da VPC, teste a conectividade:

# Teste básico de conectividade
curl -v https://api.bancodigital.com/gw_banking/healthcheck

# Deve retornar:
# {"status":"ok","timestamp":"2024-11-24T10:00:00Z"}

Nota: Se você receber erro de timeout ou conexão recusada, verifique com nossa equipe se seus IPs foram adicionados corretamente à whitelist.

🔒 Fase 2: Certificados mTLS

2.1 O que é mTLS?

mTLS (Mutual TLS) é uma camada adicional de segurança onde ambas as partes (você e nós) se autenticam usando certificados. Isso garante que apenas parceiros autorizados possam se conectar.

2.2 Solicitação de Certificados

Após a configuração da rede, solicite os certificados mTLS:

Email: [email protected]
Assunto: "Solicitação de Certificados mTLS - Banking API"
Informações:
- Nome da instituição
- CNPJ
- Ambiente (Development, Staging, Production)

2.3 Recebimento dos Certificados

Você receberá os seguintes arquivos:

client.crt - Certificado do cliente
client.key - Chave privada do cliente
ca.crt - Certificado da autoridade certificadora (CA)

⚠️ IMPORTANTE: Mantenha esses arquivos em local seguro. Nunca os commite em repositórios ou os exponha publicamente.

2.4 Armazenamento Seguro

Opção 1: Secret Manager (Recomendado)

// Exemplo: AWS Secrets Manager
import { SecretsManager } from '@aws-sdk/client-secrets-manager';

const secretsManager = new SecretsManager();

async function getCertificate() {
  const secret = await secretsManager.getSecretValue({
    SecretId: 'banking-api/mtls-cert',
  });
  return JSON.parse(secret.SecretString);
}

Opção 2: Variáveis de Ambiente (Desenvolvimento)

# .env (nunca commitar)
CERT_PATH=/secure/path/to/client.crt
KEY_PATH=/secure/path/to/client.key
CA_PATH=/secure/path/to/ca.crt

Opção 3: Vault (HashiCorp Vault)

# Armazenar no Vault
vault kv put secret/banking-api/mtls \
  [email protected] \
  [email protected] \
  [email protected]

2.5 Configuração no BFF

Node.js (axios)

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

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

const bankingApiClient = axios.create({
  baseURL: 'https://api.bancodigital.com',
  httpsAgent,
});

Python (requests)

import requests

cert = ('/path/to/client.crt', '/path/to/client.key')
ca_cert = '/path/to/ca.crt'

response = requests.get(
    'https://api.bancodigital.com/public/gw_banking/v1/accounts/123',
    cert=cert,
    verify=ca_cert,
)

cURL (teste)

curl -X GET https://api.bancodigital.com/public/gw_banking/v1/accounts/123 \
  --cert client.crt \
  --key client.key \
  --cacert ca.crt

2.6 Validação do Certificado

Teste se o certificado está funcionando:

# Teste de handshake mTLS
openssl s_client \
  -connect api.bancodigital.com:443 \
  -cert client.crt \
  -key client.key \
  -CAfile ca.crt

# Deve mostrar:
# Verify return code: 0 (ok)

Nota: Se você receber erro de "certificate verify failed", verifique se está usando os certificados corretos e se eles não expiraram.

🔑 Fase 3: Credenciais OAuth2

3.1 Solicitação de Credenciais

Após configurar mTLS, solicite as credenciais OAuth2:

Email: [email protected]
Assunto: "Solicitação de Credenciais OAuth2 - Banking API"
Informações:
- Nome da instituição
- CNPJ
- Ambiente (Development, Staging, Production)
- Confirmação de que mTLS está configurado

3.2 Recebimento das Credenciais

Você receberá:

CLIENT_ID - Identificador único do seu cliente
CLIENT_SECRET - Chave secreta para autenticação

⚠️ IMPORTANTE: Mantenha o CLIENT_SECRET em local seguro. Nunca o exponha no frontend ou em logs.

3.3 Armazenamento Seguro

# .env (nunca commitar)
CLIENT_ID=seu-client-id-aqui
CLIENT_SECRET=seu-client-secret-aqui

3.4 Configuração no BFF

// token-manager.ts
class TokenManager {
  private token: string | null = null;
  private expiresAt: number = 0;

  async getToken(): Promise<string> {
    // Se o token ainda é válido, retornar
    if (this.token && Date.now() < this.expiresAt - 5 * 60 * 1000) {
      return this.token;
    }

    // Obter novo token
    const response = await fetch(
      'https://api.bancodigital.com/public/gw_banking/v1/auth/token',
      {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: new URLSearchParams({
          grant_type: 'client_credentials',
          client_id: process.env.CLIENT_ID!,
          client_secret: process.env.CLIENT_SECRET!,
        }),
        // Incluir certificados mTLS se configurado
        agent: httpsAgent, // Node.js
      },
    );

    if (!response.ok) {
      throw new Error(`Falha ao obter token: ${response.statusText}`);
    }

    const data = await response.json();
    this.token = data.access_token;
    this.expiresAt = Date.now() + data.expires_in * 1000;

    return this.token;
  }
}

✅ Fase 4: Testes de Conectividade

4.1 Teste de Health Check

curl -X GET https://api.bancodigital.com/gw_banking/healthcheck \
  --cert client.crt \
  --key client.key \
  --cacert ca.crt

# Resposta esperada:
# {"status":"ok","timestamp":"2024-11-24T10:00:00Z"}

4.2 Teste de Autenticação

curl -X POST https://api.bancodigital.com/public/gw_banking/v1/auth/token \
  --cert client.crt \
  --key client.key \
  --cacert ca.crt \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=SEU_CLIENT_ID" \
  -d "client_secret=SEU_CLIENT_SECRET"

# Resposta esperada:
# {
#   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "token_type": "Bearer",
#   "expires_in": 3600
# }

4.3 Teste de Requisição com Token

TOKEN="seu-access-token-aqui"

curl -X GET https://api.bancodigital.com/public/gw_banking/v1/accounts/123 \
  --cert client.crt \
  --key client.key \
  --cacert ca.crt \
  -H "Authorization: Bearer $TOKEN"

# Deve retornar dados da conta ou erro de autorização se a conta não existir

🚀 Fase 5: Primeira Requisição Completa

5.1 Exemplo Completo em Node.js

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

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

// Cliente HTTP com mTLS
const client = axios.create({
  baseURL: 'https://api.bancodigital.com',
  httpsAgent,
});

// Obter token
async function getToken() {
  const response = await client.post(
    '/public/gw_banking/v1/auth/token',
    new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: process.env.CLIENT_ID!,
      client_secret: process.env.CLIENT_SECRET!,
    }),
    {
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    },
  );

  return response.data.access_token;
}

// Fazer requisição
async function getBalance(accountId: string) {
  const token = await getToken();

  const response = await client.get(
    `/public/gw_banking/v1/accounts/${accountId}/balance`,
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
    },
  );

  return response.data;
}

// Uso
(async () => {
  try {
    const balance = await getBalance('123');
    console.log('Saldo:', balance);
  } catch (error) {
    console.error('Erro:', error.response?.data || error.message);
  }
})();

5.2 Exemplo Completo em Python

import requests
import os

# Configuração
BASE_URL = 'https://api.bancodigital.com'
CLIENT_ID = os.getenv('CLIENT_ID')
CLIENT_SECRET = os.getenv('CLIENT_SECRET')
CERT = ('/path/to/client.crt', '/path/to/client.key')
CA_CERT = '/path/to/ca.crt'

# Obter token
def get_token():
    response = requests.post(
        f'{BASE_URL}/public/gw_banking/v1/auth/token',
        data={
            'grant_type': 'client_credentials',
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
        },
        cert=CERT,
        verify=CA_CERT,
    )
    response.raise_for_status()
    return response.json()['access_token']

# Fazer requisição
def get_balance(account_id):
    token = get_token()

    response = requests.get(
        f'{BASE_URL}/public/gw_banking/v1/accounts/{account_id}/balance',
        headers={'Authorization': f'Bearer {token}'},
        cert=CERT,
        verify=CA_CERT,
    )
    response.raise_for_status()
    return response.json()

# Uso
if __name__ == '__main__':
    try:
        balance = get_balance('123')
        print('Saldo:', balance)
    except Exception as e:
        print('Erro:', e)

📋 Checklist de Onboarding

Use este checklist para acompanhar seu progresso:

Infraestrutura

IPs públicos fornecidos à equipe ONZ
IPs adicionados à whitelist da VPC
Conectividade testada (health check)
Firewall configurado (porta 443)

Certificados mTLS

Certificados solicitados
Certificados recebidos (client.crt, client.key, ca.crt)
Certificados armazenados de forma segura
Certificados configurados no BFF
Handshake mTLS testado e funcionando

Credenciais OAuth2

Testes

Health check funcionando
Autenticação OAuth2 funcionando
Primeira requisição bem-sucedida
BFF integrado e funcionando

🐛 Troubleshooting

Erro: "Connection timeout"

Causa: IPs não foram adicionados à whitelist da VPC

Solução:

Verifique se forneceu os IPs corretos
Entre em contato com [email protected] para verificar whitelist

Erro: "Certificate verify failed"

Causa: Certificado inválido ou expirado

Solução:

Verifique se está usando os certificados corretos
Verifique se os certificados não expiraram
Solicite novos certificados se necessário

Erro: "Invalid client credentials"

Causa: CLIENT_ID ou CLIENT_SECRET incorretos

Solução:

Verifique se as credenciais estão corretas
Verifique se não há espaços extras
Solicite novas credenciais se necessário

Erro: "mTLS handshake failed"

Causa: Certificado e chave privada não correspondem

Solução:

Verifique se está usando o certificado e chave corretos
Teste com openssl: openssl x509 -noout -modulus -in client.crt | openssl md5 e openssl rsa -noout -modulus -in client.key | openssl md5 (devem ser iguais)

📞 Suporte

Durante o processo de onboarding, nossa equipe está disponível para ajudar:

Email: [email protected]
Assunto: "Onboarding - [Nome da Instituição]"
Tempo de resposta: 24-48 horas úteis

🎉 Próximos Passos

Após concluir o onboarding:

Getting Started - Explore a API
Balance Flow - Entenda o fluxo de saldo
Account Management - Gerencie contas
Errors & Retries - Trate erros adequadamente

displayed_sidebar: bankingApiSidebar

Última Atualização: 2024-11-24
Versão: 1.0.0

Onboarding do Parceiro

📋 Visão Geral​

🎯 Pré-requisitos​

📞 Iniciando o Processo​

🔐 Fase 1: Configuração de Infraestrutura​

1.1 Configuração de Rede (VPC)​

O que você precisa fornecer:​

O que nós fazemos:​

Tempo estimado: 2-3 dias úteis​

1.2 Configuração de Firewall​

Exemplo de regra de firewall:​

1.3 Teste de Conectividade​

🔒 Fase 2: Certificados mTLS​

2.1 O que é mTLS?​

2.2 Solicitação de Certificados​

2.3 Recebimento dos Certificados​

2.4 Armazenamento Seguro​

Opção 1: Secret Manager (Recomendado)​

Opção 2: Variáveis de Ambiente (Desenvolvimento)​

Opção 3: Vault (HashiCorp Vault)​

2.5 Configuração no BFF​

Node.js (axios)​

Python (requests)​

cURL (teste)​

2.6 Validação do Certificado​

🔑 Fase 3: Credenciais OAuth2​

3.1 Solicitação de Credenciais​

3.2 Recebimento das Credenciais​

3.3 Armazenamento Seguro​

3.4 Configuração no BFF​

✅ Fase 4: Testes de Conectividade​

4.1 Teste de Health Check​

4.2 Teste de Autenticação​

4.3 Teste de Requisição com Token​

🚀 Fase 5: Primeira Requisição Completa​

5.1 Exemplo Completo em Node.js​

5.2 Exemplo Completo em Python​

📋 Checklist de Onboarding​

Infraestrutura​

Certificados mTLS​

Credenciais OAuth2​

Testes​

🐛 Troubleshooting​

Erro: "Connection timeout"​

Erro: "Certificate verify failed"​

Erro: "Invalid client credentials"​

Erro: "mTLS handshake failed"​

📞 Suporte​

🎉 Próximos Passos​

📋 Visão Geral

🎯 Pré-requisitos

📞 Iniciando o Processo

🔐 Fase 1: Configuração de Infraestrutura

1.1 Configuração de Rede (VPC)

O que você precisa fornecer:

O que nós fazemos:

Tempo estimado: 2-3 dias úteis

1.2 Configuração de Firewall

Exemplo de regra de firewall:

1.3 Teste de Conectividade

🔒 Fase 2: Certificados mTLS

2.1 O que é mTLS?

2.2 Solicitação de Certificados

2.3 Recebimento dos Certificados

2.4 Armazenamento Seguro

Opção 1: Secret Manager (Recomendado)

Opção 2: Variáveis de Ambiente (Desenvolvimento)

Opção 3: Vault (HashiCorp Vault)

2.5 Configuração no BFF

Node.js (axios)

Python (requests)

cURL (teste)

2.6 Validação do Certificado

🔑 Fase 3: Credenciais OAuth2

3.1 Solicitação de Credenciais

3.2 Recebimento das Credenciais

3.3 Armazenamento Seguro

3.4 Configuração no BFF

✅ Fase 4: Testes de Conectividade

4.1 Teste de Health Check

4.2 Teste de Autenticação

4.3 Teste de Requisição com Token

🚀 Fase 5: Primeira Requisição Completa

5.1 Exemplo Completo em Node.js

5.2 Exemplo Completo em Python

📋 Checklist de Onboarding

Infraestrutura

Certificados mTLS

Credenciais OAuth2

Testes

🐛 Troubleshooting

Erro: "Connection timeout"

Erro: "Certificate verify failed"

Erro: "Invalid client credentials"

Erro: "mTLS handshake failed"

📞 Suporte

🎉 Próximos Passos