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

# Clientes

> Cadastre os compradores uma vez e reutilize o cadastro em cobranças, cartões salvos e assinaturas.

O cadastro de clientes guarda os dados de quem compra de você: nome, e-mail, documento e telefone. Com o cliente cadastrado, cobranças, cartões salvos e assinaturas passam a apontar para o mesmo registro, o que facilita localizar o histórico de um comprador e evita digitar os mesmos dados a cada venda.

> [!NOTE]
>
> **Para o negócio:** um cadastro único por comprador é o que permite oferecer recompra com cartão salvo e assinaturas, e também facilita o atendimento: com o e-mail ou o CPF do cliente, o seu time encontra o cadastro. Para operações de venda avulsa, o cadastro prévio é opcional, porque a própria cobrança pode criar o cliente.

## Quando usar

| Situação | Recomendação |
| - | - |
| Venda avulsa por Pix ou cartão, sem recompra | Envie os dados do cliente direto na cobrança. A API cria ou localiza o cliente junto com a cobrança |
| Cliente que volta a comprar (área logada, app) | Cadastre o cliente uma vez, guarde o `id` e use `customer.id` nas próximas cobranças |
| Salvar cartão para recompra com um clique | Cadastro prévio obrigatório: `POST /v1/cards` exige `customerId` |
| Assinatura | Use um cliente cadastrado (`customerId`) ou envie o objeto `customer` na criação da assinatura |
| Sincronizar com o seu CRM ou ERP | Cadastre pela API e guarde o `id` da Finvia junto do seu registro |

## Como funciona

O desenho abaixo mostra como o cadastro do cliente se liga às cobranças, aos cartões salvos e às assinaturas.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    SEU["Seu sistema<br/>guarda o id do cliente"]:::lojista
    VIS(["Comprador visitante<br/>sem cadastro prévio"]):::comprador
    CLI["Cliente na Finvia<br/>name, email, documento"]:::finvia
    CARD["Cartão salvo<br/>POST /v1/cards<br/>exige e-mail e CPF ou CNPJ"]:::lojista
    COB["Cobrança<br/>POST /v1/charges"]:::lojista
    ASS["Assinatura<br/>POST /v1/subscriptions"]:::lojista
    SEU -->|"1. POST /v1/customers"| CLI
    CLI -.->|"2. devolve o id"| SEU
    SEU -->|"customer.id"| COB
    SEU -->|"customerId"| CARD
    SEU -->|"customerId"| ASS
    CARD -->|"id do cartão vira<br/>cardTokenId + CVV"| COB
    CARD -->|"cardTokenId"| ASS
    VIS -->|"objeto customer<br/>na cobrança"| COB
    COB -.->|"cria ou localiza<br/>o cliente"| CLI
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef finvia fill:#017AFF,stroke:#0060CC,stroke-width:1.5px,color:#FFFFFF,font-weight:600
```

**1. Crie o cliente**

`POST /v1/customers` com nome, e-mail e documento. A resposta traz o `id`.

**2. Guarde o id**

Grave o `id` no cadastro do comprador no seu sistema.

**3. Use o id nas operações**

Em cobranças, envie `customer.id`. Em cartões, `customerId`. Em assinaturas, `customerId`.

**4. Mantenha o cadastro atualizado**

Atualize nome, e-mail e telefone com `PUT /v1/customers/{id}` quando o comprador alterar os dados.

## Criar o cliente antes ou na cobrança

Há dois caminhos, e eles podem conviver na mesma integração.

| | Criar antes (`POST /v1/customers`) | Criar na cobrança (inline) |
| - | - | - |
| Como | Chamada própria, depois `customer.id` na cobrança | Objeto `customer` com `name` e `email` (ou `phone`) dentro de `POST /v1/charges` |
| O que a API faz | Cria o cliente e devolve o `id` | Cria ou localiza o cliente junto com a cobrança |
| Dados exigidos | `name`, `email`, `documentId`, `documentType` | `email` ou `phone` (quando não há `id`) |
| Serve para cartão salvo | Sim | Só depois de obter o `id` do cliente |
| Indicado para | Áreas logadas, recompra, assinaturas, integração com CRM | Checkout de visitante, venda única |

> [!NOTE]
>
> Quando a cobrança recebe `customer.id`, os outros campos de `customer` ficam opcionais e o cadastro existente é usado como está. Os dados enviados junto não atualizam o cadastro. Para mudar nome, e-mail ou telefone, use `PUT /v1/customers/{id}`.

## Regras de negócio

| Regra | Detalhe |
| - | - |
| Campos obrigatórios na criação | `name`, `email`, `documentId`, `documentType` |
| Tipos de documento | Use `cpf` ou `cnpj` em `documentType` |
| Documento imutável | `documentId` e `documentType` não podem ser alterados depois da criação |
| Cartão salvo e assinatura | O cliente precisa de **e-mail** e de **CPF ou CNPJ**. O tipo é deduzido pela quantidade de dígitos do documento: 11 é CPF, 14 é CNPJ. Qualquer outro tamanho conta como cliente sem documento, e o cartão é recusado |
| Exclusão | Lógica (soft delete): o cliente é removido do sistema e a rota responde `204` |
| Listagens | Paginação por `page` e `size` (padrão 1 e 10). Um parâmetro `limit` é ignorado sem erro |
| Nome do campo de telefone | `phoneNumber` no cadastro de clientes e nas assinaturas; `phone` dentro de `customer` na cobrança |

> [!WARNING]
>
> Se o cliente vai ter cartão salvo ou assinatura, cadastre com CPF ou CNPJ e e-mail desde o início. Sem isso, o cadastro do cartão responde `400` com `Failed to register card: O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador`. Como o documento não pode ser alterado, um cliente criado com outro documento (passaporte, RG) não serve para esses fluxos, e será preciso criar outro cadastro.

## Passo a passo

### 1. Criar um cliente

```http REST (JSON) theme={null}
POST /v1/customers HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json

{
  "name": "Joao Silva",
  "email": "joao@email.com",
  "documentId": "52998224725",
  "documentType": "cpf",
  "phoneNumber": "+5511987654321"
}
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Joao Silva",
    "email": "joao@email.com",
    "documentId": "52998224725",
    "documentType": "cpf",
    "phoneNumber": "+5511987654321"
  }'
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch('https://api-global.fastpaybrasil.com/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Joao Silva',
    email: 'joao@email.com',
    documentId: '52998224725',
    documentType: 'cpf',
    phoneNumber: '+5511987654321',
  }),
});

const { id } = await response.json(); // guarde este id
```

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

import requests

payload = {
    "name": "Joao Silva",
    "email": "joao@email.com",
    "documentId": "52998224725",
    "documentType": "cpf",
    "phoneNumber": "+5511987654321",
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/customers",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    json=payload,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$payload = [
    'name' => 'Joao Silva',
    'email' => 'joao@email.com',
    'documentId' => '52998224725',
    'documentType' => 'cpf',
    'phoneNumber' => '+5511987654321',
];

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/customers');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        String payload = """
            {
              "name": "Joao Silva",
              "email": "joao@email.com",
              "documentId": "52998224725",
              "documentType": "cpf",
              "phoneNumber": "+5511987654321"
            }
            """;

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(payload))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var payload = """
{
  "name": "Joao Silva",
  "email": "joao@email.com",
  "documentId": "52998224725",
  "documentType": "cpf",
  "phoneNumber": "+5511987654321"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/customers");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)

func main() {
	payload := strings.NewReader(`{
	  "name": "Joao Silva",
	  "email": "joao@email.com",
	  "documentId": "52998224725",
	  "documentType": "cpf",
	  "phoneNumber": "+5511987654321"
	}`)

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/customers", payload)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "json"
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/customers")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
  "name" => "Joao Silva",
  "email" => "joao@email.com",
  "documentId" => "52998224725",
  "documentType" => "cpf",
  "phoneNumber" => "+5511987654321",
})

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

Resposta `201`:

```json theme={null}
{
  "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q"
}
```

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `name` | string | Sim | Nome completo do cliente |
| `email` | string (e-mail) | Sim | E-mail do cliente |
| `documentId` | string | Sim | Número do documento: CPF (11 dígitos) ou CNPJ (14 dígitos) |
| `documentType` | string | Sim | Tipo do documento: `cpf` ou `cnpj` |
| `phoneNumber` | string | Não | Telefone do cliente. Ex.: `+5511987654321` |

### 2. Usar o cliente numa cobrança

```json theme={null}
{
  "amount": 150,
  "currency": "BRL",
  "customer": { "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q" },
  "paymentMethod": { "type": "pix", "expirationInSeconds": 1800 },
  "items": [
    { "title": "Consultoria online", "type": "digital", "description": "Sessão de 1 hora por vídeo", "unit_price": 150, "quantity": 1 }
  ]
}
```

A alternativa sem cadastro prévio é enviar os dados no próprio `customer`:

```json theme={null}
{
  "customer": {
    "name": "Maria Souza",
    "email": "maria@email.com",
    "document": { "type": "cpf", "id": "52998224725" }
  }
}
```

### 3. Buscar e listar clientes

`GET /v1/customers` devolve uma lista paginada, dos clientes mais recentes para os mais antigos, e aceita estes filtros:

| Parâmetro | Tipo | Padrão | Descrição |
| - | - | - | - |
| `search` | string | | Busca por nome, e-mail, documento ou telefone |
| `email` | string | | Filtra pelo e-mail exato |
| `documentId` | string | | Filtra pelo número do documento |
| `page` | integer | `1` | Número da página (começa em 1). Valor menor que 1 ou não numérico volta ao padrão |
| `size` | integer | `10` | Itens por página. Valor menor que 1 ou não numérico volta ao padrão |

```bash Busca por texto theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/customers?search=joao&page=1&size=10" \
  -u "$FINVIA_API_KEY:"
```

```bash Por e-mail exato theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/customers?email=joao@email.com" \
  -u "$FINVIA_API_KEY:"
```

```bash Por documento theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/customers?documentId=52998224725" \
  -u "$FINVIA_API_KEY:"
```

A resposta `200` usa o envelope plano das listagens da API: `{ data, total, page, size, pages }`. Para percorrer todos os clientes, avance `page` até chegar a `pages`. Os campos de cada cliente em `data` serão publicados na [referência da rota](https://docs.fastpaybrasil.com/referencia/clientes/listar.md) quando o time técnico liberar o formato final.

> [!TIP]
>
> **Para o desenvolvedor:** o tamanho da página vai em `size`. Um `limit` na URL é ignorado sem erro, e a página continua com 10 itens.

Para buscar um cliente específico, use `GET /v1/customers/{id}`:

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -u "$FINVIA_API_KEY:"
```

A resposta `200` traz o cadastro do cliente. Os campos estão descritos em [Consultar cliente](https://docs.fastpaybrasil.com/referencia/clientes/consultar.md).

### 4. Atualizar um cliente

`PUT /v1/customers/{id}` altera nome, e-mail e telefone. Todos os campos são opcionais: envie só o que mudou. O documento (`documentId` e `documentType`) não pode ser alterado.

```bash cURL theme={null}
curl -X PUT "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -u "$FINVIA_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "joao.silva@email.com",
    "phoneNumber": "+5511912345678"
  }'
```

A resposta `200` traz o cadastro do cliente, no mesmo formato da consulta.

### 5. Excluir um cliente

```bash cURL theme={null}
curl -X DELETE "https://api-global.fastpaybrasil.com/v1/customers/2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -u "$FINVIA_API_KEY:"
```

A exclusão é lógica (soft delete): o cliente é marcado como removido. A resposta é `204`, sem corpo.

> [!NOTE]
>
> A documentação não detalha o efeito da exclusão do cliente sobre cartões salvos e assinaturas já existentes. Antes de excluir um cliente com assinatura ativa, cancele a assinatura e exclua os cartões pelas rotas próprias.

## Boas práticas para evitar duplicidade

Clientes duplicados dificultam o atendimento e espalham o histórico de um comprador em vários registros. Algumas práticas ajudam:

1. **Guarde o `id` da Finvia** no cadastro do comprador no seu sistema e use sempre esse `id` quando ele existir.
2. **Procure antes de criar.** Se o seu sistema não tem o `id`, consulte `GET /v1/customers?email=...` ou `?documentId=...`. Crie só se a busca vier vazia.
3. **Padronize os dados.** Envie o documento só com números (`52998224725`) e o e-mail em minúsculas, para que as buscas exatas encontrem o registro.
4. **Use o objeto `customer` com cuidado.** Na cobrança e na assinatura, o objeto `customer` cria ou localiza o cliente (na assinatura, a busca é pelo e-mail). Se o mesmo comprador usar e-mails diferentes, podem surgir dois cadastros. Na assinatura, quando já existe um cliente com o mesmo e-mail, vale o documento desse cadastro, e não o enviado na requisição.

O desenho abaixo resume essas práticas em uma sequência de decisões.

```mermaid placement="top-right" className="finvia-diagrama" theme={null}
%%{init: {"theme": "base", "fontFamily": "Inter, sans-serif", "themeVariables": {"fontFamily": "Inter, Arial, sans-serif", "fontSize": "15px", "primaryColor": "#EAF3FF", "primaryBorderColor": "#017AFF", "primaryTextColor": "#070D15", "secondaryColor": "#F3F5F8", "tertiaryColor": "#FFFFFF", "lineColor": "#5B6B82", "textColor": "#070D15", "edgeLabelBackground": "#FFFFFF", "clusterBkg": "#F7F9FC", "clusterBorder": "#D5DCE6", "actorBkg": "#FFFFFF", "actorBorder": "#98A2B3", "actorTextColor": "#070D15", "actorLineColor": "#B8C2D1", "signalTextColor": "#070D15", "labelBoxBkgColor": "#EAF3FF", "labelBoxBorderColor": "#017AFF", "labelTextColor": "#003A7A", "loopTextColor": "#070D15", "noteBkgColor": "#FFF6E5", "noteBorderColor": "#F0B44C", "noteTextColor": "#5C3D00", "activationBkgColor": "#EAF3FF", "activationBorderColor": "#017AFF", "sequenceNumberColor": "#FFFFFF", "signalColor": "#5B6B82"}, "flowchart": {"defaultRenderer": "elk", "curve": "basis", "nodeSpacing": 45, "rankSpacing": 55, "padding": 18}, "sequence": {"mirrorActors": false, "showSequenceNumbers": true, "actorMargin": 60, "messageMargin": 38, "boxMargin": 10, "noteMargin": 12, "wrap": true}}}%%
flowchart TB
    INI(["Comprador vai pagar"]):::comprador
    Q1{"Já tem o id<br/>da Finvia?"}:::decisao
    USE(["Use o id: customer.id<br/>na cobrança, customerId<br/>no cartão e na assinatura"]):::ok
    BUS["Procure antes de criar<br/>GET /v1/customers<br/>?email= ou ?documentId="]:::lojista
    Q2{"Achou?"}:::decisao
    Q3{"Cartão salvo, assinatura<br/>ou recompra?"}:::decisao
    CRIA["POST /v1/customers<br/>com e-mail e CPF ou CNPJ<br/>só com números"]:::lojista
    INL["Venda avulsa: envie<br/>o objeto customer<br/>direto na cobrança"]:::neutro
    GRD["Guarde o id junto do<br/>cadastro no seu sistema"]:::lojista
    INI --> Q1
    Q1 -->|"sim"| USE
    Q1 -->|"não"| BUS --> Q2
    Q2 -->|"sim"| GRD
    Q2 -->|"não"| Q3
    Q3 -->|"sim"| CRIA --> GRD
    Q3 -->|"não"| INL
    GRD --> USE
    classDef comprador fill:#FFF6E5,stroke:#B45309,stroke-width:1.5px,color:#5C3D00
    classDef lojista fill:#F3F5F8,stroke:#475467,stroke-width:1.5px,color:#101828
    classDef ok fill:#E8F7EE,stroke:#15803D,stroke-width:1.5px,color:#0B4A23
    classDef decisao fill:#FFFFFF,stroke:#017AFF,stroke-width:2px,color:#070D15
    classDef neutro fill:#FFFFFF,stroke:#B8C2D1,stroke-width:1.5px,color:#344054
```

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `401` `Unauthorized` | Chave inválida ou cabeçalho mal montado | Confira a autenticação em [Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md) |
| `403` `Acesso negado` ao criar | Chave sem permissão | Gere a chave com usuário Owner ou Manager |
| `404` `Customer not found` | `id` inexistente ou cliente excluído | Confira o `id` ou busque por e-mail ou documento |
| Documento não muda após o `PUT` | `documentId` e `documentType` são imutáveis | Crie um novo cadastro com o documento correto |
| Cartão ou assinatura recusados com `O cliente precisa ter e-mail e CPF/CNPJ para salvar o cartão neste processador` | Cliente sem e-mail, ou com documento que não tem 11 nem 14 dígitos | Use um cadastro com e-mail e CPF ou CNPJ |
| Assinatura recusada mesmo com CPF na requisição | Já existe um cliente com o mesmo e-mail, cadastrado com outro documento. Vale o documento do cadastro | Crie um cliente com e-mail e CPF ou CNPJ e envie o `customerId` dele |
| A página sempre volta com 10 clientes | Tamanho enviado como `limit` | Envie `size` |
| Telefone não salvo | Campo enviado como `phone` no cadastro | No cadastro de clientes o campo é `phoneNumber` |

## Perguntas frequentes

> [accordion] Preciso cadastrar o cliente antes de cobrar?
>
> Não. A cobrança aceita o objeto `customer` com `name` e `email` (ou `phone`) e cria ou localiza o cliente. O cadastro prévio é necessário para salvar cartão e recomendado para recompra e assinaturas.

> [accordion] Posso corrigir um CPF digitado errado?
>
> Não. O documento não pode ser alterado depois da criação. Crie um novo cadastro com o documento correto e passe a usar o novo `id` (em assinaturas, envie `customerId`). Se você enviar o objeto `customer` com o mesmo e-mail do cadastro antigo, a assinatura usa o documento do cadastro antigo.

> [accordion] Posso cadastrar cliente estrangeiro?
>
> Cartão salvo e assinaturas exigem CPF ou CNPJ: o tipo é deduzido pela quantidade de dígitos do documento, e um passaporte conta como cliente sem documento. Para vendas avulsas, a cobrança pode ser feita com os dados do cliente na própria requisição.

> [accordion] A API impede a criação de dois clientes com o mesmo e-mail?
>
> A documentação não informa se há bloqueio de duplicidade em `POST /v1/customers`. Procure o cliente antes de criar, como mostrado em [Boas práticas](#boas-práticas-para-evitar-duplicidade).

> [accordion] Excluir o cliente apaga as cobranças dele?
>
> A exclusão é lógica (soft delete). A documentação não descreve o efeito sobre as cobranças já feitas para esse cliente.

## Como testar

O cadastro de clientes funciona com a chave de teste (`sk_test_`). Crie, atualize e exclua um cliente no sandbox antes de ir para produção. O cadastro de cartão e as assinaturas não têm modo de teste: veja [Cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md).

| Código | Cenário | Relação com clientes |
| - | - | - |
| SUB-01 | Registrar cartão | O cliente precisa ter e-mail e CPF ou CNPJ |
| SUB-04 | Criar assinatura | Com `customerId` ou objeto `customer` |

## Veja também

> [card] [Cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md)
>
> Salve cartões vinculados ao cliente.

> [card] [Assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Cobrança recorrente a partir do cliente cadastrado.

> [card] [Criar cliente](https://docs.fastpaybrasil.com/referencia/clientes/criar.md)
>
> Contrato completo da rota.

> [card] [Listar clientes](https://docs.fastpaybrasil.com/referencia/clientes/listar.md)
>
> Filtros e paginação.


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