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

# Crear clientes

> Crea un nuevo cliente en tu cuenta.

### Headers

<ParamField header="x-idempotency" type="string" required placeholder="Token único para garantizar la idempotencia de la petición">
  Token único para garantizar la idempotencia de la petición
</ParamField>

### Body

<ParamField body="user_type" type="string" required placeholder="natural, company">
  Tipo de usuario, valores permitidos: natural, company
</ParamField>

<ParamField body="first_name" type="string" required>
  Primer Nombre del cliente
</ParamField>

<ParamField body="last_name" type="string" required>
  Apellidos del cliente
</ParamField>

<ParamField body="email" type="string" required>
  Correo electrónico del cliente
</ParamField>

<ParamField body="phone" type="string" required>
  Número de teléfono del cliente usa el prefijo de la región ejemplo: +57
</ParamField>

<ParamField body="document_type" type="string" required placeholder="CC, CE, NIT, PASSPORT">
  Tipo de documento de identidad (CC, CE, NIT, PASSPORT)
</ParamField>

<ParamField body="document_number" type="string" required>
  Número de documento de identidad
</ParamField>

<ParamField body="enable_notifications" type="boolean" required default="true">
  Habilita notificaciones automáticas por email y SMS al cliente sobre pagos aprobados, rechazados, y links de pago. Valor por defecto: `true`.
</ParamField>

<ParamField body="nationality" type="string" placeholder="CO, Formato ISO 3166-1 alpha-2">
  Nacionalidad del cliente, Formato ISO 3166-1 alpha-2
</ParamField>

<ParamField body="birthdate" type="string" placeholder="YYYY-MM-DD, Fecha de nacimiento del cliente">
  Fecha de nacimiento del cliente, formato YYYY-MM-DD
</ParamField>

<ParamField body="related_to" type="string" placeholder="Id del cliente al que se relaciona">
  Id del cliente al que se relaciona
</ParamField>

### Response

<ResponseField name="id" type="string">
  Identificador único del cliente en formato UUID
</ResponseField>

<ResponseField name="name" type="string">
  Nombre del cliente
</ResponseField>

<ResponseField name="email" type="string">
  Correo electrónico del cliente
</ResponseField>

<ResponseField name="phone" type="string">
  Número de teléfono del cliente
</ResponseField>

<ResponseField name="document_number" type="string">
  Número de documento de identidad del cliente
</ResponseField>

<ResponseField name="document_type" type="string">
  Tipo de documento de identidad del cliente (ej. DNI, RUC, CE)
</ResponseField>

<ResponseField name="created_at" type="date">
  Fecha y hora de creación del cliente
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id":"9da58912-101d-46f8-86c9-20a52119c0bf",
    "first_name":"John",
    "last_name":"Doe",
    "email":"john.doe@example.com",
    "phone":"+573100001020",
    "document_type":"CC",
    "document_number":"1060500333",
    "nationality":"CO",
    "birthdate":"1990-01-01",
    "created_at":"2024-12-04T20:09:08.000000Z"
  }
  ```

  ```json 422 theme={null}
  {
     "message":"El campo nombre es obligatorio. (y 6 errores m\u00e1s)",
     "code":10001,
     "code_name":"validation_error",
     "errors":{
        "first_name":[
           "El campo nombre es obligatorio."
        ],
        "last_name":[
           "El campo apellido es obligatorio."
        ],
        "phone":[
           "El campo tel\u00e9fono es obligatorio."
        ],
        "email":[
           "El campo correo electr\u00f3nico es obligatorio."
        ],
        "user_type":[
           "El campo user type es obligatorio."
        ],
        "document_type":[
           "El campo document type es obligatorio."
        ],
        "document_number":[
           "El campo document number es obligatorio."
        ],
        "nationality":[
           "El código de país debe seguir el formato ISO 3166-1 alpha-2"
        ],
        "birthdate":[
           "La fecha debe tener el formato YYYY-MM-DD"
        ]
     }
  }
  ```

  ```json 409 theme={null}
  {
    "message": "No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency",
    "code": 10003,
    "code_name": "idempotency_error"
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/customers \
    -X POST \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "Content-Type: application/json" \
    -H "x-idempotency: customer-001" \
    -d '{
      "user_type": "natural",
      "first_name": "Juan",
      "last_name": "Pérez",
      "email": "juan@example.com",
      "phone": "+573001234567",
      "document_type": "CC",
      "document_number": "1234567890",
      "enable_notifications": true
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/customers', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'Content-Type': 'application/json',
      'x-idempotency': 'customer-001'
    },
    body: JSON.stringify({
      user_type: 'natural',
      first_name: 'Juan',
      last_name: 'Pérez',
      email: 'juan@example.com',
      phone: '+573001234567',
      document_type: 'CC',
      document_number: '1234567890',
      enable_notifications: true
    })
  });

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

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

  response = requests.post(
      'https://api.onepay.la/v1/customers',
      headers={
          'Authorization': 'Bearer sk_test_xxx',
          'Content-Type': 'application/json',
          'x-idempotency': 'customer-001'
      },
      json={
          'user_type': 'natural',
          'first_name': 'Juan',
          'last_name': 'Pérez',
          'email': 'juan@example.com',
          'phone': '+573001234567',
          'document_type': 'CC',
          'document_number': '1234567890',
          'enable_notifications': True
      }
  )

  customer = response.json()
  print(customer)
  ```

  ```php PHP theme={null}
  <?php
  $curl = curl_init();

  curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.onepay.la/v1/customers",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
      "Authorization: Bearer sk_test_xxx",
      "Content-Type: application/json",
      "x-idempotency: customer-001"
    ],
    CURLOPT_POSTFIELDS => json_encode([
      "user_type" => "natural",
      "first_name" => "Juan",
      "last_name" => "Pérez",
      "email" => "juan@example.com",
      "phone" => "+573001234567",
      "document_type" => "CC",
      "document_number" => "1234567890",
      "enable_notifications" => true
    ])
  ]);

  $response = curl_exec($curl);
  curl_close($curl);

  $customer = json_decode($response, true);
  print_r($customer);
  ?>
  ```
</RequestExample>