# Clientes

Um cliente é o titular (pessoa física ou jurídica) dono de uma ou mais contas. Ao criar um cliente, a Monetarie abre a primeira conta e roda a análise de conformidade. O parceiro só enxerga os clientes que ele mesmo criou.

## Cadastrar cliente

Cria o titular e a primeira conta em uma única operação.

```http
POST /api/partner/v1/customers
Authorization: Bearer {{access_token}}
Content-Type: application/json
Idempotency-Key: {{uuid}}

{
  "document": "56936427200",
  "name": "Maria de Souza",
  "password": "S3nh@Forte!2026",
  "email": "maria@exemplo.com.br",
  "phone": "+5511999998888",
  "user_type": "member_pf",
  "account_type": "payment"
}
```

- **Escopo:** `customer:create`
- **Obrigatórios:** `document`, `name`, `password`.
- **Opcionais:** `email`, `phone`, `login`, `user_type`, `account_type`, `kyc`.

### Campo `document`

O `document` (CPF ou CNPJ) é gravado como identificador do titular. Formato aceito: **CPF com 11 dígitos** ou **CNPJ com 14** (o novo CNPJ alfanumérico segue o padrão de 12 posições alfanuméricas em maiúsculas seguidas de 2 dígitos). Envie apenas os dígitos, sem pontos, barras ou hífens. Um documento fora desse formato responde `422`.

### Tipo de titular (`user_type`)

| `user_type` | Titular |
|---|---|
| `member_pf` (padrão) | Pessoa física |
| `member_pj` | Pessoa jurídica |

Se omitido, assume `member_pf`.

### Tipo de conta (`account_type`)

Veja a lista de tipos aceitos em [Contas e saldo](/endpoints/contas#tipos-de-conta). Se omitido, assume `payment`.

Resposta `201`:

```json
{
  "data": {
    "id": 25165,
    "name": "Maria de Souza",
    "document": "56936427200",
    "status": "active",
    "partner_id": "6b70e220-63e8-462b-bd5e-dfb96e4bbb7f",
    "kyc": {
      "outcome": "active",
      "edd_required": false,
      "sanctions_hit": false,
      "pep_hit": false,
      "compliance_case_id": "c38a0710-bcf1-47c9-ab88-f0a275cee9ed"
    },
    "accounts": [
      { "id": 10024283, "kind": 3, "account_type": "payment", "agency": "0001", "account_number": "119341-4", "status": "active" }
    ]
  }
}
```

### Conta em análise

A criação passa por verificação de conformidade. Quando a análise aponta risco (sanções ou PEP), o `kyc.outcome` vem `"blocked"`, o `kyc.edd_required` vem `true` e a conta nasce bloqueada para movimentação até a conclusão. Acompanhe pelo `status` da conta.

## Consultar cliente

```http
GET /api/partner/v1/customers/{id}
Authorization: Bearer {{access_token}}
```

- **Escopo:** `customer:read`

```json
{
  "data": {
    "id": 25165,
    "name": "Maria de Souza",
    "document": "56936427200",
    "status": "active",
    "partner_id": "6b70e220-...",
    "kyc": { "status": "active", "risk_level": "low", "is_pep": false, "last_reviewed_at": "2026-07-11T02:25:00Z", "edd_required": false },
    "accounts": [ { "id": 10024283, "kind": 3, "account_type": "payment", "agency": "0001", "account_number": "119341-4", "status": "active" } ]
  }
}
```

Um `id` desconhecido ou de outro parceiro responde `404`.

## Abrir conta adicional

Um mesmo titular pode ter várias contas.

```http
POST /api/partner/v1/customers/{id}/accounts
Authorization: Bearer {{access_token}}
Content-Type: application/json

{ "account_type": "savings" }
```

- **Escopo:** `account:write`
- Aceita `account_type` (obrigatório o valor ser válido), `agency` e `account_number` (opcionais).

Resposta `201`:

```json
{ "data": { "id": 10024284, "kind": 3, "account_type": "savings", "agency": "0001", "account_number": "119342-2", "status": "active" } }
```

Um `account_type` fora da lista responde `422` com `invalid account_type`. Um cliente de outro parceiro responde `404`.