# Criar Cliente
`POST /v1/customers`
**Área:** Clientes

**Scopes necessários:** `customers/write`

Cadastra um cliente na sua conta a partir do CPF/CNPJ, com endereço opcional.

O documento é a chave do cliente dentro da conta e não pode ser alterado depois. Por padrão, se já existir um cliente com o mesmo documento, a API devolve 200 com o cadastro existente em vez de duplicar. Envie upsert: true para que a tentativa de recadastrar retorne erro 400 (CUSTOMER_ALREADY_EXISTS).

Quando o endereço é informado, o código IBGE do município (cityCode) é resolvido automaticamente a partir do CEP — necessário para emissão de NFS-e.

Case de uso:

_Como plataforma, quero cadastrar meus clientes junto com o endereço de cobrança, para depois gerar assinaturas e cobranças sem redigitar os dados a cada venda._

### Request body

```json
{
  "name": "Alexandre Souza",
  "document": "11144477735",
  "phone": "5511987654321",
  "email": "alexandre@exemplo.com.br",
  "upsert": false,
  "address": {
    "zipCode": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "complement": "Sala 5",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP"
  }
}
```

### Campos do body

**Obrigatórios:** `name`, `document`, `phone`, `address.zipCode`, `address.street`, `address.number`, `address.neighborhood`, `address.city`, `address.state`

| Campo | Descrição |
|---|---|
| `name` | Nome completo ou razão social |
| `document` | CPF (11) ou CNPJ (14), apenas dígitos |
| `phone` | E.164 com DDI 55 |
| `address.zipCode` | 8 dígitos, apenas números |
| `address.street` |  |
| `address.number` |  |
| `address.neighborhood` |  |
| `address.city` |  |
| `address.state` | UF com 2 letras |

**Opcionais**

| Campo | Descrição |
|---|---|
| `email` |  |
| `upsert` | true retorna erro 400 se o documento já existir (default false) |
| `address` |  |
| `address.complement` |  |

### Resposta 201 — 201

```json
{
  "customer": {
    "customerId": "cus_xxx",
    "id": "cus_xxx",
    "name": "Alexandre Souza",
    "document": "11144477735",
    "email": "alexandre@exemplo.com.br",
    "phone": "5511987654321",
    "accountId": "460851686",
    "status": "ACTIVE",
    "createdAt": "2026-08-28T12:00:00.000Z"
  }
}
```

### Resposta 200 — 200

```json
{
  "customer": {
    "customerId": "cus_xxx",
    "document": "11144477735",
    "name": "Alexandre Souza"
  }
}
```

### Resposta 400 — 400

```json
{
    "error": {
        "message": "Já existe um cliente cadastrado com este documento",
        "code": "CUSTOMER_ALREADY_EXISTS",
        "details": null,
        "timestamp": "2026-07-14T21:39:36.322Z"
    }
}
```

---
Página: https://docs.validapay.com.br/documentacao-validapay2/post-criar-cliente
Contrato OpenAPI: https://docs.validapay.com.br/openapi.json