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

# Criar

> Cadastre um novo cliente na sua conta Avantti Finance

## Visão geral

Use este endpoint para cadastrar um novo cliente na sua conta. Os clientes podem ser associados a transações, assinaturas e links de pagamento, facilitando a gestão de relacionamento e a conciliação financeira.

## Endpoint

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.avanttifinance.com/v1/customers \
    -H "Authorization: Bearer {access_token}" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Maria da Silva",
      "email": "maria.silva@email.com",
      "document": "12345678900",
      "phone": "+5511999999999"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.avanttifinance.com/v1/customers", {
    method: "POST",
    headers: {
      "Authorization": \`Bearer \${accessToken}\`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "Maria da Silva",
      email: "maria.silva@email.com",
      document: "12345678900",
      phone: "+5511999999999"
    })
  });

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

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

  url = "https://api.avanttifinance.com/v1/customers"
  headers = {
      "Authorization": f"Bearer {access_token}",
      "Content-Type": "application/json"
  }
  payload = {
      "name": "Maria da Silva",
      "email": "maria.silva@email.com",
      "document": "12345678900",
      "phone": "+5511999999999"
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```
</CodeGroup>

## Parâmetros do corpo

<ParamField body="name" type="string" required>
  Nome completo ou razão social do cliente.
</ParamField>

<ParamField body="email" type="string" required>
  Endereço de e-mail do cliente, utilizado para comunicações e identificação.
</ParamField>

<ParamField body="document" type="string" required>
  CPF ou CNPJ do cliente, sem pontuação.
</ParamField>

<ParamField body="phone" type="string">
  Número de telefone do cliente, no formato E.164 (ex: `+5511999999999`).
</ParamField>

<ParamField body="metadata" type="object">
  Conjunto de pares chave-valor para armazenar informações adicionais sobre o cliente.
</ParamField>

## Resposta

<ResponseField name="id" type="string">
  Identificador único do cliente, no formato `cus_xxxxxxxxxxxx`.
</ResponseField>

<ResponseField name="name" type="string">
  Nome completo ou razão social do cliente.
</ResponseField>

<ResponseField name="email" type="string">
  Endereço de e-mail do cliente.
</ResponseField>

<ResponseField name="document" type="string">
  CPF ou CNPJ do cliente.
</ResponseField>

<ResponseField name="phone" type="string">
  Número de telefone do cliente.
</ResponseField>

<ResponseField name="created_at" type="string">
  Data e hora de criação do cliente, no formato ISO 8601.
</ResponseField>

### Exemplo de resposta

```json theme={null}
{
  "id": "cus_8f72a1b3c4d5",
  "name": "Maria da Silva",
  "email": "maria.silva@email.com",
  "document": "12345678900",
  "phone": "+5511999999999",
  "metadata": {},
  "created_at": "2025-01-15T10:30:00Z"
}
```

<Tip>
  Verifique se o e-mail e o documento informados são válidos e únicos. Tentativas de cadastro com documentos já existentes retornarão erro `409 Conflict`.
</Tip>

## Erros comuns

| Código HTTP | Significado                                                  |
| ----------- | ------------------------------------------------------------ |
| 400         | Dados inválidos ou campos obrigatórios ausentes              |
| 401         | Token de autenticação inválido ou ausente                    |
| 409         | Já existe um cliente cadastrado com este documento ou e-mail |

## Próximos passos

<CardGroup cols={2}>
  <Card title="Listar clientes" icon="user-round-search" href="/listar">
    Consulte todos os clientes cadastrados.
  </Card>

  <Card title="Editar cliente" icon="user-pen" href="/editar-1">
    Atualize os dados de um cliente existente.
  </Card>
</CardGroup>