Visão Geral

Gerenciamento completo de compradores no GoPag API.

Documentação

Operações CRUD

• Criar Comprador - Cadastrar novo comprador no sistema

• Buscar por CPF/CNPJ - Localizar comprador usando documento

• Detalhes do Comprador - Recuperar e atualizar informações

• Remover Comprador - Deletar comprador do sistema

---

Visão Geral

Os compradores (buyers) são os clientes finais que realizam compras através da plataforma. Cada comprador possui:

• Dados pessoais: Nome, email, telefone, CPF/CNPJ

• Endereço: Informações completas de localização

• Cartões tokenizados: Métodos de pagamento salvos

• Metadata: Campos customizados para sua aplicação

Fluxo Básico

1. Criar Comprador
   ↓
2. Tokenizar Cartão (opcional)
   ↓
3. Criar Transação
   ↓
4. Reutilizar em próximas compras

---

Início Rápido

Criar Primeiro Comprador

curl --location 'https://api.gopag.com.br/v1/marketplaces/YOUR_MARKETPLACE_ID/buyers' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "first_name": "Maria",
  "last_name": "Santos",
  "email": "[email protected]",
  "taxpayer_id": "12345678901"
}'

Buscar por CPF

curl --location 'https://api.gopag.com.br/v1/marketplaces/YOUR_MARKETPLACE_ID/buyers/search?taxpayer_id=12345678901' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Atualizar Email

curl --location --request PATCH 'https://api.gopag.com.br/v1/marketplaces/YOUR_MARKETPLACE_ID/buyers/BUYER_ID' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data '{"email": "[email protected]"}'

---

Casos de Uso Comuns

1. Checkout com Comprador Novo

// Verificar se comprador já existe
let buyer = await searchBuyerByCPF(cpf);

if (!buyer) {
  // Criar novo comprador
  buyer = await createBuyer({
    first_name: 'Maria',
    last_name: 'Santos',
    email: '[email protected]',
    taxpayer_id: cpf
  });
}

// Criar transação
const transaction = await createTransaction({
  customer: buyer.id,
  amount: 10000,
  payment_type: 'credit'
});

2. Compra Recorrente (Assinatura)

# Buscar comprador existente
buyer = search_buyer_by_cpf('12345678901')

# Criar cobrança mensal usando customer_id
transaction = create_transaction({
    'customer': buyer['id'],  # Usa cartão tokenizado
    'amount': 4990,
    'currency': 'BRL',
    'description': 'Assinatura Premium - Mensal',
    'capture': True
})

3. Atualização de Cadastro

<?php
// Cliente mudou de email
$buyer = updateBuyer($buyerId, [
    'email' => '[email protected]',
    'metadata' => [
        'email_updated_at' => date('c'),
        'email_updated_by' => 'customer_portal'
    ]
]);
?>

---

Estrutura de Dados

Objeto Buyer Completo

{
  "id": "e4e8c5b569da48b28d896385f5481bcf",
  "resource": "buyer",
  "first_name": "Maria",
  "last_name": "Santos",
  "email": "[email protected]",
  "phone_number": "11987654321",
  "taxpayer_id": "12345678901",
  "birthdate": "1990-07-15",
  "address": {
    "line1": "Rua das Palmeiras, 456",
    "line2": "Apto 789",
    "line3": "",
    "neighborhood": "Jardins",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01418000",
    "country_code": "BR"
  },
  "metadata": {
    "customer_level": "gold",
    "origin": "mobile_app"
  },
  "created_at": "2025-12-21T10:00:00Z",
  "updated_at": "2025-12-21T10:00:00Z"
}

---

Boas Práticas

✅ Recomendado

• Sempre busque antes de criar: Evite duplicatas verificando CPF primeiro

• Armazene o buyer_id: Guarde para reutilizar em transações futuras

• Use metadata: Adicione informações customizadas relevantes para seu negócio

• Valide dados: Verifique email e CPF antes de enviar

• Tokenize cartões: Use usage: 'reusable' para vendas recorrentes

❌ Evite

• Criar compradores duplicados sem verificar CPF

• Armazenar dados sensíveis em metadata

• Atualizar todos os campos quando precisa mudar apenas um

• Deletar compradores sem verificar transações pendentes

• Formatar CPF com pontos e traços (use apenas números)

---

Próximos Passos

Documentação Relacionada

• Criar Transação com Comprador

• Tokenização de Cartões

• Gestão de Vendedores

• API Reference

Tutoriais

• Implementar Checkout Completo

• Sistema de Assinaturas

• LGPD e Privacidade

---

Precisa de Ajuda?

• 📧 Email: [email protected]

• 📚 Documentação Completa

• 💬 Portal do Desenvolvedor