> ## 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.

# Criar um cliente

> Cadastra o comprador com nome, e-mail e documento para usar depois em cobranças, cartões salvos e assinaturas.

Esta rota cadastra um cliente (objeto `customer`), a pessoa ou empresa que paga. O cadastro devolve um `id` que você guarda no seu sistema e reutiliza: para registrar o cartão no cofre, para criar uma assinatura ou para cobrar sem reenviar os dados pessoais a cada venda.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Fluxo de assinatura com cartão registrado antes (cards-first) | Crie o cliente, depois [registre o cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md) com o `id` devolvido |
| Cadastro feito no seu site antes da primeira compra | Crie o cliente no momento do cadastro e guarde o `id` junto do usuário |
| Recompra com um clique | Cliente criado aqui + cartão salvo + [cobrança com `cardTokenId`](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo) |
| Venda avulsa sem cadastro prévio | Não é preciso chamar esta rota: [Criar cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md) aceita `name` e `email` e cria ou localiza o cliente |

## Antes de chamar

* Tenha uma chave secreta (`sk_`) válida. A chave herda as permissões do usuário que a gerou, e esta rota devolve `403` quando a chave não tem permissão ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* Confira se o cliente já existe com [Listar clientes](https://docs.fastpaybrasil.com/referencia/clientes/listar.md) filtrando por `email` ou `documentId`, para não duplicar o cadastro.
* Se o cliente vai ter cartão salvo ou assinatura, colete **e-mail** e **CPF ou CNPJ**. Sem esses dois dados, o cartão não pode ser salvo.

> [!WARNING]
>
> O documento **não pode ser alterado depois**: [Atualizar cliente](https://docs.fastpaybrasil.com/referencia/clientes/atualizar.md) muda só nome, e-mail e telefone. Para registrar cartão (em `POST /v1/cards` ou no cartão enviado direto em `POST /v1/subscriptions`), o cliente precisa ter e-mail e CPF ou CNPJ. O tipo é deduzido pela quantidade de dígitos de `documentId`: 11 dígitos é CPF e 14 é CNPJ. Qualquer outro documento (passaporte, RG) conta como cliente sem documento, e o cartão é recusado com `400`.

## Corpo da requisição

Campos obrigatórios: `name`, `email`, `documentId` e `documentType`.

**name** `string` *required*

Nome completo do cliente. Ex.: `Joao Silva`.

**email** `string` *required*

E-mail do cliente (formato `email`). Ex.: `joao@email.com`.

**documentId** `string` *required*

Número do documento de identificação. Ex.: `52998224725` (CPF, 11 dígitos) ou `11222333000181` (CNPJ, 14 dígitos).

**documentType** `string` *required*

Tipo do documento. Use `cpf` ou `cnpj`. Para salvar cartão, o que conta é a quantidade de dígitos de `documentId`, e não o valor deste campo.

**phoneNumber** `string`

Telefone do cliente (opcional). Ex.: `+5511987654321`.

> [!TIP]
>
> **Para o desenvolvedor:** envie o `documentId` como string, sem pontos, barras ou traços, como nos exemplos (`52998224725`). Guarde o `id` da resposta na tabela de usuários do seu sistema: ele é a chave para todas as operações seguintes com esse cliente.

## Respostas

**id** `string`

Identificador único do cliente criado. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. Use em `customerId` ao [registrar um cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md) ou criar uma [assinatura](https://docs.fastpaybrasil.com/referencia/assinaturas/criar.md), e em `customer.id` ao [criar uma cobrança](https://docs.fastpaybrasil.com/referencia/cobrancas/criar.md).

A resposta traz só o `id`. Para ver o cadastro completo, use [Consultar cliente](https://docs.fastpaybrasil.com/referencia/clientes/consultar.md).

| HTTP | Significado | Corpo |
| - | - | - |
| `201` | Cliente criado | `{"id": "..."}` |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | Sem permissão | `{ "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 }` |

> [!NOTE]
>
> **Para o negócio:** ter o cliente cadastrado com CPF ou CNPJ e e-mail é a condição para oferecer recompra com cartão salvo e cobrança recorrente. Se o seu produto tem assinatura, peça esses dados já no cadastro do site ou do aplicativo, assim o cliente não precisa preencher nada a mais no momento da contratação.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` |
| `403 Forbidden` | A chave herda as permissões do usuário que a gerou, e esse usuário não tem acesso à rota | Gere a chave com um usuário que tenha a permissão (para integração, use Owner ou Manager) |
| Registro de cartão recusado para o cliente | Cliente sem e-mail ou com documento que não tem 11 nem 14 dígitos | Cadastre o cliente com e-mail e CPF ou CNPJ |
| Documento cadastrado errado | O documento não muda depois da criação | Crie um novo cliente com o documento correto |
| Mesmo cliente cadastrado mais de uma vez | Criação sem verificar se já existia | Antes de criar, consulte [Listar clientes](https://docs.fastpaybrasil.com/referencia/clientes/listar.md) com `email` ou `documentId` |

```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: 'Maria Souza',
    email: 'maria@email.com',
    documentId: '11222333000181',
    documentType: 'cnpj',
  }),
});

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

```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
```

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

```json 401 theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

```json 403 theme={null}
{
  "message": "Acesso negado",
  "error": "Forbidden",
  "statusCode": 403
}
```

## Veja também

> [card] [Guia de clientes](https://docs.fastpaybrasil.com/guias/clientes.md)
>
> Quando cadastrar e como reaproveitar o cliente.

> [card] [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md)
>
> Próximo passo do fluxo cards-first.

> [card] [Cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md)
>
> Como os cartões ficam guardados e são reutilizados.

> [card] [Visão geral de assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Cliente, plano e cartão na cobrança recorrente.


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