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:

1. Infraestrutura de Rede (VPC, Firewall, etc)
2. Certificados mTLS (Mutual TLS)
3. Credenciais OAuth2 (Client ID e Client Secret)
4. Testes de Conectividade
5. 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

• Credenciais solicitadas
• CLIENT_ID recebido
• CLIENT_SECRET recebido
• Credenciais armazenadas de forma segura
• Token OAuth2 obtido com sucesso

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:

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

Erro: "Certificate verify failed"

Causa: Certificado inválido ou expirado

Solução:

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

Erro: "Invalid client credentials"

Causa: CLIENT_ID ou CLIENT_SECRET incorretos

Solução:

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

Erro: "mTLS handshake failed"

Causa: Certificado e chave privada não correspondem

Solução:

1. Verifique se está usando o certificado e chave corretos
2. 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:

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

---

displayed_sidebar: bankingApiSidebar

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