> ## Documentation Index
> Fetch the complete documentation index at: https://scaleup-c34c4386.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/v1/buyers/

> Cria um novo comprador no gateway de pagamentos e salva no banco de dados local

Cria um comprador no gateway de pagamentos e sincroniza os dados localmente. Se um comprador com o mesmo `taxpayer_id` já existir no gateway, os dados locais são atualizados em vez de criar um novo registro.

## Autenticação

Não requer autenticação.

## Corpo da Requisição

**first\_name** `string` *required*

Nome do comprador

**last\_name** `string` *required*

Sobrenome do comprador

**email** `string` *required*

E-mail do comprador

**taxpayer\_id** `string`

CPF do comprador (somente dígitos, 11 caracteres). Se não informado, o comprador é criado sem CPF

**phone\_number** `string`

Telefone do comprador

**birthdate** `string`

Data de nascimento no formato `DD-MM-YYYY`

## Resposta

**success** `boolean`

Indica se a criação foi bem-sucedida

**buyer** `object`

Dados do comprador criado

**Propriedades**

**id** `string`

ID do comprador no gateway

**taxpayer\_id** `string`

CPF (se fornecido)

**first\_name** `string`

Nome

**last\_name** `string`

Sobrenome

**email** `string`

E-mail

**phone\_number** `string`

Telefone

**birthdate** `string`

Data de nascimento (DD-MM-YYYY)

**status** `string`

Status do comprador no gateway

**created\_at** `string`

Data de criação (ISO 8601)

**zoop\_buyer\_id** `string`

ID do comprador no gateway (mesmo que `buyer.id`; campo `zoop_buyer_id` na API)

**is\_new** `boolean`

`true` se o comprador foi criado agora; `false` se já existia no gateway

## Exemplo

```bash cURL theme={null}
curl -X POST "https://api.chargefy.io/api/v1/buyers/" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "João",
    "last_name": "Silva",
    "email": "joao@exemplo.com",
    "taxpayer_id": "123.456.789-01",
    "phone_number": "11999990000",
    "birthdate": "15-06-1990"
  }'
```

```typescript SDK theme={null}
import { Chargefy } from '@chargefy/sdk';

const chargefy = new Chargefy({
  accessToken: process.env.CHARGEFY_ACCESS_TOKEN,
});

const result = await chargefy.buyers.create({
  firstName: 'João',
  lastName: 'Silva',
  email: 'joao@exemplo.com',
  taxpayerId: '12345678901',
  phoneNumber: '11999990000',
  birthdate: '15-06-1990',
});
```

## Resposta de Exemplo

```json theme={null}
{
  "success": true,
  "buyer": {
    "id": "gw_buyer_abc123",
    "taxpayer_id": "12345678901",
    "first_name": "João",
    "last_name": "Silva",
    "email": "joao@exemplo.com",
    "phone_number": "11999990000",
    "birthdate": "15-06-1990",
    "status": "active",
    "created_at": "2026-03-20T10:00:00Z"
  },
  "zoop_buyer_id": "gw_buyer_abc123",
  "is_new": true
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.