Guia do Usuário

O que você vai aprender

Ao final deste guia, você será capaz de:

• Configurar a autenticação da API
• Criar uma validação de conta bancária
• Confirmar a validação com o código recebido
• Tratar os possíveis erros de resposta

Pré-requisitos

Antes de começar, você precisa:

• Ter um workspace_id válido
• Conhecer os dados bancários que deseja validar
• Ter acesso ao ambiente de produção da API

Passo 1: Configurar a autenticação

Todas as requisições precisam incluir o header workspace_id:

-H "workspace_id: SEU_WORKSPACE_ID"
-H "Content-Type: application/json"

Passo 2: Criar uma validação

Endpoint

POST /api/v1/validate

Parâmetros

Exemplo de requisição

curl -X POST https://api.exemplo.com.br/api/v1/validate \
  -H "workspace_id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "bank": "00000000",
    "branch": "0001",
    "account": "123456",
    "account_digit": "7",
    "account_type": "0",
    "fiscal_code": "12345678900"
  }'

Resposta de sucesso

{
  "id": 123,
  "bank": "00000000",
  "branch": "0001",
  "account": "123456",
  "account_digit": "7",
  "account_type": "0",
  "fiscal_code": "12345678900",
  "status": "validated",
  "error_code": "",
  "error_message": ""
}

Checkpoint: Neste momento, o titular da conta receberá um código de 6 caracteres via PIX.

Passo 3: Confirmar o código

Endpoint

POST /api/v1/match_code/{id}

Parâmetros

Exemplo de requisição

curl -X POST https://api.exemplo.com.br/api/v1/match_code/123 \
  -H "workspace_id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "short_code": "ABCDEF"
  }'

Resposta de sucesso

{
  "match_result": true
}

Resposta de código incorreto

{
  "match_result": false
}

Passo 4: Tratar erros

Erros de validação

Quando a validação falha, o campo status será invalidated e os campos error_code e error_message conterão detalhes:

{
  "id": 124,
  "status": "invalidated",
  "error_code": "IG01",
  "error_message": "CPF/CNPJ inválido"
}

Erros de limite

Ao atingir o limite de uso:

{
  "error": "Limit reached"
}

Status HTTP: 400 Bad Request

Erros de autenticação

Workspace inválido ou ausente:

{
  "error": "Invalid workspace"
}

Status HTTP: 400 Bad Request

Exemplo completo

// 1. Criar validação
const validation = await fetch('https://api.exemplo.com.br/api/v1/validate', {
  method: 'POST',
  headers: {
    'workspace_id': 'SEU_WORKSPACE_ID',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    bank: '00000000',
    branch: '0001',
    account: '123456',
    account_digit: '7',
    account_type: '0', // Conta Corrente
    fiscal_code: '12345678900'
  })
});

const result = await validation.json();

if (result.status === 'validated') {
  // 2. Aguardar código do usuário
  const userCode = prompt('Digite o código recebido:');
  
  // 3. Confirmar código
  const confirmation = await fetch(`https://api.exemplo.com.br/api/v1/match_code/${result.id}`, {
    method: 'POST',
    headers: {
      'workspace_id': 'SEU_WORKSPACE_ID',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      short_code: userCode
    })
  });
  
  const match = await confirmation.json();
  
  if (match.match_result) {
    console.log('Conta validada com sucesso!');
  } else {
    console.log('Código incorreto');
  }
} else {
  console.error('Erro na validação:', result.error_message);
}

Próximos passos

• Endpoints da API - Documentação detalhada dos endpoints
• Referência de Erros - Lista completa de códigos de erro
• Conceitos - Revisar conceitos técnicos