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

# Criar Cliente

> Endpoint principal para cadas novos clientes

Este endpoint permite cadastrar um novo cliente na plataforma Autorizou. O cliente é uma entidade obrigatória para processar qualquer pagamento e pode ter múltiplos cartões associados.

## Casos de Uso

* **Cadastro inicial** de novos compradores
* **Onboarding** de usuários em marketplaces
* **Gestão de relacionamento** com compradores
* **Preparação** para futuros pagamentos

## Parâmetros Obrigatórios

<ParamField body="name" type="string" required>
  Nome completo do cliente (máximo 191 caracteres)
</ParamField>

<ParamField body="email" type="string" required>
  Email válido e único por merchant (máximo 191 caracteres)
</ParamField>

## Parâmetros Opcionais

### Documentos

<ParamField body="documents" type="array">
  Lista de documentos do cliente (CPF, CNPJ, RG, Passaporte ou Outro)

  <Expandable title="Propriedades">
    <ParamField body="documents[].type" type="string" required>
      Tipo do documento: `cpf`, `cnpj`, `rg`, `passport` ou `other`
    </ParamField>

    <ParamField body="documents[].value" type="string" required>
      Número do documento sem formatação (apenas dígitos)
    </ParamField>
  </Expandable>
</ParamField>

### Endereços

<ParamField body="addresses" type="array">
  Lista de endereços do cliente

  <Expandable title="Propriedades">
    <ParamField body="addresses[].type" type="string" required>
      Tipo do endereço: `billing` (cobrança) ou `shipping` (entrega)
    </ParamField>

    <ParamField body="addresses[].postal_code" type="string" required>
      CEP (apenas números)
    </ParamField>

    <ParamField body="addresses[].line_1" type="string" required>
      Logradouro (rua, avenida, etc.)
    </ParamField>

    <ParamField body="addresses[].line_2" type="string">
      Complemento (apartamento, sala, etc.)
    </ParamField>

    <ParamField body="addresses[].number" type="string" required>
      Número do endereço
    </ParamField>

    <ParamField body="addresses[].neighborhood" type="string" required>
      Bairro
    </ParamField>

    <ParamField body="addresses[].city" type="string" required>
      Cidade
    </ParamField>

    <ParamField body="addresses[].state" type="string" required>
      Estado (2 caracteres - ex: SP, RJ)
    </ParamField>

    <ParamField body="addresses[].country" type="string" required>
      País (ISO 3166-1 alpha-2 - ex: BR)
    </ParamField>
  </Expandable>
</ParamField>

### Telefone

<ParamField body="phone" type="object">
  Informações de contato telefônico

  <Expandable title="Propriedades">
    <ParamField body="phone.type" type="string" required>
      Tipo do telefone: `mobile`, `commercial`, `residential` ou `public`
    </ParamField>

    <ParamField body="phone.ddi" type="string" required>
      Código do país (ex: 55 para Brasil)
    </ParamField>

    <ParamField body="phone.ddd" type="string" required>
      Código de área (ex: 11 para São Paulo)
    </ParamField>

    <ParamField body="phone.number" type="string" required>
      Número do telefone (apenas dígitos)
    </ParamField>
  </Expandable>
</ParamField>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://pay.autorizou.dev/api/v1/customers \
    -H "Authorization: Bearer 4eC39HqLyjWDarjtT1zdp7dc" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Maria da Silva Santos",
      "email": "maria.santos@exemplo.com.br",
      "documents": [
        {
          "type": "cpf",
          "value": "12345678901"
        }
      ],
      "addresses": [
        {
          "type": "billing",
          "postal_code": "01310100",
          "line_1": "Av. Paulista",
          "number": "1000",
          "line_2": "Conjunto 101",
          "neighborhood": "Bela Vista",
          "city": "São Paulo", 
          "state": "SP",
          "country": "BR"
        }
      ],
      "phone": {
        "type": "mobile",
        "ddi": "55",
        "ddd": "11", 
        "number": "987654321"
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const customer = await fetch('https://pay.autorizou.dev/api/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer 4eC39HqLyjWDarjtT1zdp7dc',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Maria da Silva Santos',
      email: 'maria.santos@exemplo.com.br',
      documents: [
        {
          type: 'CPF',
          value: '12345678901'
        }
      ],
      addresses: [
        {
          type: 'billing',
          postal_code: '01310100',
          line_1: 'Av. Paulista',
          number: '1000',
          line_2: 'Conjunto 101',
          neighborhood: 'Bela Vista',
          city: 'São Paulo',
          state: 'SP',
          country: 'BR'
        }
      ],
      phone: {
        type: 'mobile',
        ddi: '55',
        ddd: '11',
        number: '987654321'
      }
    })
  });

  const result = await customer.json();
  console.log('Cliente criado:', result);
  ```

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

  $data = [
      'name' => 'Maria da Silva Santos',
      'email' => 'maria.santos@exemplo.com.br',
      'documents' => [
          [
              'type' => 'CPF',
              'value' => '12345678901'
          ]
      ],
      'addresses' => [
          [
              'type' => 'billing',
              'postal_code' => '01310100',
              'line_1' => 'Av. Paulista',
              'number' => '1000',
              'line_2' => 'Conjunto 101',
              'neighborhood' => 'Bela Vista',
              'city' => 'São Paulo',
              'state' => 'SP',
              'country' => 'BR'
          ]
      ],
      'phone' => [
          'type' => 'mobile',
          'ddi' => '55',
          'ddd' => '11',
          'number' => '987654321'
      ]
  ];

  $curl = curl_init();
  curl_setopt_array($curl, [
      CURLOPT_URL => 'https://pay.autorizou.dev/api/v1/customers',
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_POST => true,
      CURLOPT_HTTPHEADER => [
          'Authorization: Bearer 4eC39HqLyjWDarjtT1zdp7dc',
          'Content-Type: application/json'
      ],
      CURLOPT_POSTFIELDS => json_encode($data)
  ]);

  $response = curl_exec($curl);
  $customer = json_decode($response, true);
  curl_close($curl);

  echo "Cliente criado: " . json_encode($customer, JSON_PRETTY_PRINT);
  ?>
  ```
</CodeGroup>

## Resposta de Sucesso

```json theme={null}
{
  "id": "142465c6-4c9d-4fd1-9632-2c40af316da3",
  "hash": "AUTCUS01K8RSCH3T5FNB7EVACV8DQVNX",
  "name": "Maria da Silva Santos",
  "email": "maria.santos@exemplo.com.br",
  "created_at": "29/10/2025 17:08:42",
  "updated_at": "29/10/2025 17:08:42"
}
```

## Códigos de Erro

<AccordionGroup>
  <Accordion title="400 - Bad Request" icon="circle-xmark">
    Requisição malformada ou parâmetros inválidos

    ```json theme={null}
    {
      "error": {
        "code": "invalid_request",
        "message": "Dados da requisição são inválidos"
      }
    }
    ```
  </Accordion>

  <Accordion title="422 - Validation Error" icon="circle-xmark">
    Erro de validação nos dados fornecidos

    ```json theme={null}
    {
      "message": O email já está em uso.",
      "errors": {
        "email": [
          "O email já está em uso."
        ]
      } 
    }
    ```
  </Accordion>
</AccordionGroup>

## Regras de Negócio

<Note>
  **Email único:** O email deve ser único por merchant. Tentativas de criar clientes com emails duplicados retornarão erro 422.
</Note>

<Note>
  **Validação de documentos:** CPF e CNPJ são validados automaticamente. Apenas documentos válidos são aceitos.
</Note>

<Warning>
  **Dados obrigatórios para pagamentos:** Embora endereços e telefone sejam opcionais na criação, alguns métodos de pagamento podem exigir essas informações posteriormente.
</Warning>

## Próximos Passos

Após criar um cliente, você pode:

1. [Tokenizar cartões de crédito](/api-reference/cards/criar-cartao)
2. [Processar pagamentos](/api-reference/charges/criar-ordem)
3. [Buscar dados do cliente](/api-reference/customers/buscar-cliente)