Pular para o conteúdo principal
POST
/
credit-card
/
v1
/
buyer
Criar Comprador
curl --request POST \
  --url https://api-gateway.firebanking.dev/credit-card/v1/buyer \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "document": {
    "documentNumber": "36880261019",
    "documentType": "cpf",
    "documentNation": "BR"
  },
  "name": "João Silva",
  "email": "[email protected]",
  "phone": "11999999999",
  "countryCode": "+55",
  "alternativeEmail": "[email protected]",
  "address": {
    "country": "BR",
    "state": "SP",
    "city": "São Paulo",
    "district": "Centro",
    "street": "Rua das Flores",
    "zipCode": "01000000",
    "number": "220",
    "complement": "Apto 45"
  }
}
'
{
  "uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "email": "<string>",
  "document": {
    "documentNumber": "36880261019",
    "documentType": "cpf",
    "documentNation": "BR"
  },
  "phone": "<string>",
  "createdAt": "2023-11-07T05:31:56Z"
}
Criar um novo registro de comprador no sistema. Compradores são essenciais para processamento de pagamentos e podem ser reutilizados em múltiplas transações e assinaturas.

​
Dados Obrigatórios vs Opcionais

Campos Obrigatórios

Documento, nome, email, telefone - mínimo para criação do comprador

Campos Opcionais

Endereço, email alternativo - aprimoram perfis de comprador

​
Tipos de Documento

​
document.documentType
string
required
Tipo de documento: cpf para pessoas físicas, cnpj para pessoas jurídicas
  • CPF: Para clientes pessoa física (11 dígitos)
  • CNPJ: Para clientes pessoa jurídica (14 dígitos)

​
Exemplo de Requisição (Completa)

Exemplo de Requisição
{
  "document": {
    "documentNumber": "36880261019",
    "documentType": "cpf",
    "documentNation": "BR"
  },
  "name": "João Silva",
  "email": "[email protected]",
  "countryCode": "+55",
  "phone": "11999999999",
  "alternativeEmail": "[email protected]",
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "district": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "zipCode": "01000000"
  }
}

​
Exemplo de Requisição (Mínima)

Requisição Mínima
{
  "document": {
    "documentNumber": "98765432100",
    "documentType": "cpf",
    "documentNation": "BR"
  },
  "name": "Maria Santos",
  "email": "[email protected]",
  "phone": "11888888888"
}

​
Exemplo de Resposta

Resposta
{
  "uuid": "buyer-uuid-12345",
  "document": {
    "documentNumber": "36880261019",
    "documentType": "cpf",
    "documentNation": "BR"
  },
  "name": "João Silva",
  "email": "[email protected]",
  "phone": "11999999999",
  "countryCode": "+55",
  "alternativeEmail": "[email protected]",
  "address": {
    "street": "Rua das Flores",
    "number": "123",
    "complement": "Apto 45",
    "district": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR",
    "zipCode": "01000000"
  },
  "createdAt": "2024-01-15T14:30:00Z",
  "updatedAt": "2024-01-15T14:30:00Z"
}

​
Validações de Campo

Validação de Documento: Números de CPF e CNPJ são validados para formato correto e dígitos verificadores.

​
Formato do Número de Telefone

  • Inclua código de área (DDD) para números brasileiros
  • Exemplo: 11999999999 (11 é o código de área de São Paulo)

​
Formato do CEP

  • CEP brasileiro: 8 dígitos sem hífen
  • Exemplo: 01000000 para Centro, São Paulo

​
Reutilização do Comprador

Uma vez criados, compradores podem ser usados para:
  • Múltiplos pagamentos usando buyerUuid
  • Tokenização de cartão para armazenamento seguro
  • Gerenciamento de assinatura para cobrança recorrente
  • Histórico de pedidos rastreamento através de transações
Armazene o uuid retornado - você precisará dele para pagamentos futuros e operações com este comprador.

​
Detecção de Duplicatas

O sistema previne compradores duplicados baseado em:
  1. Número de documento - Mesmo CPF/CNPJ não pode ser registrado duas vezes
  2. Endereço de email - Mesmo email não pode ser usado para documentos diferentes

​
Melhores Práticas

  1. Validar entrada - Verificar formato de CPF/CNPJ antes de enviar
  2. Armazenar UUID - Salvar o UUID do comprador para transações futuras
  3. Atualizar perfis - Manter informações do comprador atuais
  4. Lidar com duplicatas - Lidar graciosamente com erros de detecção de duplicatas
  5. Privacidade de dados - Seguir requisitos da LGPD/GDPR para manuseio de dados

​
Cenários de Erro

  • Documento inválido: Formato de CPF/CNPJ ou validação de dígito verificador falha
  • Documento duplicado: Número de documento já existe
  • Email duplicado: Email já associado com outro comprador
  • Telefone inválido: Formato do número de telefone está incorreto
  • Campos obrigatórios ausentes: Campos obrigatórios não foram fornecidos

Authorizations

​
x-api-key
string
header
required

Chave de API para autenticação

Body

application/json
​
document
object
required
​
name
string
required

Nome completo do comprador

Example:

"João Silva"

​
email
string<email>
required

Endereço de email principal

Example:

"[email protected]"

​
phone
string
required

Número de telefone

Example:

"11999999999"

​
countryCode
string

Código do país com prefixo +

Example:

"+55"

​
alternativeEmail
string<email>

Endereço de email alternativo

Example:

"[email protected]"

​
address
object

Response

200 - application/json

Comprador criado com sucesso

​
uuid
string<uuid>

UUID do comprador

​
name
string

Nome do comprador

​
email
string

Endereço de email

​
document
object
​
phone
string

Número de telefone

​
createdAt
string<date-time>

Timestamp de criação