> ## Documentation Index
> Fetch the complete documentation index at: https://docs.garu.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Registrar Cliente

> Cadastre um cliente para o seller autenticado, com dedup automática por CPF/CNPJ

## Visão Geral

Registra um cliente para a conta autenticada. Se já existir um cliente global com o mesmo `document` (CPF ou CNPJ) — vinculado a outro seller — a Garu **não** cria um registro duplicado: reaproveita o cliente global e cria (ou atualiza) o seu próprio perfil vinculado a ele.

<Note>
  **Dedup por documento, não por e-mail.** Dois sellers podem cadastrar o mesmo CPF com e-mails diferentes; cada um enxerga seu próprio perfil (nome, e-mail, telefone) para esse cliente, sem vazar dados do outro seller.
</Note>

## Headers

<ParamField header="Authorization" type="string" required>
  Sua chave de API (`Bearer sk_live_...`)
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

<ParamField header="X-Idempotency-Key" type="string">
  Opcional. Chave única para reenviar a requisição com segurança sem criar um cliente duplicado. A mesma chave devolve o cliente originalmente criado/casado por 24h, por vendedor.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
  Nome completo
</ParamField>

<ParamField body="email" type="string" required>
  E-mail válido
</ParamField>

<ParamField body="document" type="string" required>
  CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números
</ParamField>

<ParamField body="phone" type="string" required>
  Telefone com DDD, 10 ou 11 dígitos, apenas números
</ParamField>

<ParamField body="personType" type="string" required>
  `fisica` ou `juridica`
</ParamField>

<ParamField body="zipCode" type="string">
  CEP com 8 dígitos, sem hífen
</ParamField>

<ParamField body="street" type="string">
  Logradouro
</ParamField>

<ParamField body="number" type="string">
  Número do endereço
</ParamField>

<ParamField body="complement" type="string">
  Complemento
</ParamField>

<ParamField body="neighborhood" type="string">
  Bairro
</ParamField>

<ParamField body="city" type="string">
  Cidade
</ParamField>

<ParamField body="state" type="string">
  Sigla do estado, 2 letras maiúsculas (ex: `SP`)
</ParamField>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://garu.com.br/api/v1/customers \
    -H "Authorization: Bearer sk_live_sua_chave_api" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Maria Silva",
      "email": "maria@exemplo.com.br",
      "document": "12345678909",
      "phone": "11987654321",
      "personType": "fisica"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://garu.com.br/api/v1/customers', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.GARU_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Maria Silva',
      email: 'maria@exemplo.com.br',
      document: '12345678909',
      phone: '11987654321',
      personType: 'fisica'
    })
  });

  const customer = await response.json();
  console.log(customer.uuid);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.post(
      "https://garu.com.br/api/v1/customers",
      headers={
          "Authorization": f"Bearer {os.environ['GARU_API_KEY']}",
          "Content-Type": "application/json",
      },
      json={
          "name": "Maria Silva",
          "email": "maria@exemplo.com.br",
          "document": "12345678909",
          "phone": "11987654321",
          "personType": "fisica",
      },
  )

  customer = response.json()
  print(customer["uuid"])
  ```
</CodeGroup>

## Resposta de Sucesso (201 Created)

```json theme={null}
{
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Maria Silva",
  "email": "maria@exemplo.com.br",
  "phone": "11987654321",
  "document": "12345678909",
  "personType": "fisica",
  "zipCode": null,
  "street": null,
  "number": null,
  "complement": null,
  "neighborhood": null,
  "city": null,
  "state": null,
  "billingEmail": "maria@exemplo.com.br",
  "hasBillingEmailOverride": false,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "updatedAt": "2026-01-15T10:30:00.000Z"
}
```

<Note>
  `billingEmail` é o e-mail resolvido para envios de cobrança: `billingEmailOverride` (se definido) → e-mail deste perfil → e-mail global do cliente. Veja [Definir e-mail de cobrança](/api-reference/clientes/definir-email-cobranca).
</Note>

## Erros

| Código | Quando acontece                               |
| ------ | --------------------------------------------- |
| `400`  | Dados inválidos (documento, telefone, e-mail) |
| `401`  | Chave de API ausente ou inválida              |

## Próximos passos

* [**Cobranças agendadas**](/guias/cobrancas-agendadas) — agende PIX/Boleto para uma data futura para este cliente.
* [**Boleto parcelado**](/guias/carne) — venda em carnê para este cliente.