displayed_sidebar: bankingApiSidebar

👥 Jornada: Gerenciar Pessoas

Este guia apresenta o fluxo completo para gerenciar pessoas (físicas e jurídicas) através da API.

📋 Visão Geral

Nesta jornada, você aprenderá a:

1. ✅ Consultar informações de pessoas
2. ✅ Buscar pessoas por CPF/CNPJ
3. ✅ Entender os diferentes tipos de pessoa
4. ✅ Trabalhar com dados de pessoas físicas e jurídicas

🎯 Cenário de Uso

Imagine que você precisa:

• Consultar dados de uma pessoa antes de criar uma conta
• Validar CPF/CNPJ antes de processar transações
• Buscar informações de titulares de contas

📝 Passo 1: Consultar Pessoa por ID

Requisição

curl -X GET "https://api.bancodigital.com/public/gw_banking/v1/people/123" \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta

{
  "id": "123",
  "document": "12345678900",
  "name": "João Silva",
  "type": "PF",
  "email": "[email protected]",
  "phone": "+5511999999999",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

📝 Passo 2: Buscar Pessoa por Documento

Requisição

curl -X GET "https://api.bancodigital.com/public/gw_banking/v1/people?document=12345678900" \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta

{
  "id": "123",
  "document": "12345678900",
  "name": "João Silva",
  "type": "PF",
  "email": "[email protected]",
  "phone": "+5511999999999",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

📊 Tipos de Pessoa

Código	Tipo	Descrição
PF	Pessoa Física	Pessoa física (CPF)
PJ	Pessoa Jurídica	Pessoa jurídica (CNPJ)

💻 Exemplo Completo em Node.js

import axios from 'axios';

const API_BASE_URL = 'https://api.bancodigital.com';
const CLIENT_ID = 'seu-client-id';
const CLIENT_SECRET = 'seu-client-secret';

// 1. Obter token
async function getToken() {
  const response = await axios.post(
    `${API_BASE_URL}/public/gw_banking/v1/auth/token`,
    new URLSearchParams({
      grant_type: 'client_credentials',
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
    }),
    {
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    },
  );
  return response.data.access_token;
}

// 2. Consultar pessoa por ID
async function getPerson(token: string, personId: string) {
  const response = await axios.get(
    `${API_BASE_URL}/public/gw_banking/v1/people/${personId}`,
    {
      headers: { Authorization: `Bearer ${token}` },
    },
  );
  return response.data;
}

// 3. Buscar pessoa por documento
async function findPersonByDocument(token: string, document: string) {
  const response = await axios.get(
    `${API_BASE_URL}/public/gw_banking/v1/people?document=${document}`,
    {
      headers: { Authorization: `Bearer ${token}` },
    },
  );
  return response.data;
}

// 4. Validar documento
function validateDocument(document: string, type: 'PF' | 'PJ'): boolean {
  if (type === 'PF') {
    // CPF: 11 dígitos
    return /^\d{11}$/.test(document);
  } else {
    // CNPJ: 14 dígitos
    return /^\d{14}$/.test(document);
  }
}

// Uso
(async () => {
  try {
    const token = await getToken();

    // Consultar pessoa por ID
    const person = await getPerson(token, '123');
    console.log('Pessoa:', person);

    // Buscar por documento
    const personByDoc = await findPersonByDocument(token, '12345678900');
    console.log('Pessoa encontrada:', personByDoc);

    // Validar documento
    if (validateDocument(person.document, person.type as 'PF' | 'PJ')) {
      console.log('✅ Documento válido');
    } else {
      console.log('❌ Documento inválido');
    }
  } catch (error) {
    console.error('Erro:', error.response?.data || error.message);
  }
})();

⚠️ Tratamento de Erros

Pessoa Não Encontrada (404)

{
  "type": "https://api.bancodigital.com/errors/person-not-found",
  "title": "Person Not Found",
  "status": 404,
  "detail": "Person with ID 123 not found",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}

Documento Inválido (400)

{
  "type": "https://api.bancodigital.com/errors/invalid-document",
  "title": "Invalid Document",
  "status": 400,
  "detail": "Document must be a valid CPF (11 digits) or CNPJ (14 digits)",
  "correlationId": "550e8400-e29b-41d4-a716-446655440000"
}

✅ Checklist de Implementação

• Implementar consulta de pessoa por ID
• Implementar busca por documento
• Adicionar validação de documento
• Implementar tratamento de erros
• Adicionar logs com correlation ID
• Testar cenários de pessoa não encontrada

🔄 Próximos Passos

Agora que você sabe gerenciar pessoas, explore:

1. Gerenciar Contas - Fluxo completo de gestão de contas
2. Balance Flow - Como consultar saldos
3. Errors & Retries - Tratamento de erros e boas práticas