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

# Crear cliente

> Crea un registro de cliente para el usuario autenticado después del intercambio de token.

Crea un cliente en Fire spark para el usuario identificado por el access token. Llama a este endpoint después del [intercambio de token](https://firespark.cloud/docs/es/storefront-api/oauth/exchange/post.md) cuando el cliente inicia sesión por primera vez.

El `id` del cuerpo debe coincidir con el claim `sub` del ID token OIDC del cliente (el mismo valor vinculado al access token).

> [!NOTE]
>
> Requiere un access token de Fire spark obtenido mediante [intercambio de
> token](https://firespark.cloud/docs/es/storefront-api/oauth/exchange/post.md).

## Cuerpo de la solicitud

| Campo | Requerido | Descripción |
| - | - | - |
| `id` | Sí | Identificador externo del cliente. Debe coincidir con el id del token. |
| `is_anonymous` | No | `true` para checkout como invitado. Por defecto `false`. |
| `name` | Sí\* | Nombre completo. No requerido si `is_anonymous` es `true`. |
| `email` | Sí\* | Correo electrónico. No requerido si `is_anonymous` es `true`. |
| `status` | No | `ACTIVE` o `INACTIVE`. Por defecto `ACTIVE`. |
| `gender` | No | `MALE`, `FEMALE` u `OTHER`. |
| `dob` | No | Fecha de nacimiento (ISO 8601 con offset). |
| `document_type` | No | Tipo de documento de identidad. |
| `document_number` | No | Número de documento de identidad. |
| `country` | No | País del cliente. |
| `phone` | No | Teléfono en formato internacional. |
| `registration_date` | No | Fecha de registro en tu sistema. Por defecto la hora actual. |
| `devices` | No | Payloads opcionales de dispositivo al registrar. Usa [actualizar cliente](https://firespark.cloud/docs/es/storefront-api/customers/\[id]/patch) con un array `devices` para gestionar tokens push estructurados después del registro. Por defecto `[]`. |
| `delivery_addresses` | No | Hasta 10 direcciones de entrega. Solo una puede tener `preferred: true`. |
| `billing_profiles` | No | Hasta 10 perfiles de facturación. Solo uno puede tener `preferred: true`. |
| `consent` | No | Consentimiento de marketing. `marketing` por defecto es `false`. |
| `notification_preferences` | No | Preferencias de entrega de email y push. Los flags omitidos por defecto son `true`. |
| `metadata` | No | Metadatos personalizados. Debe serializar a 1MB o menos. |

\* Requerido para clientes no anónimos.

### Consentimiento

Los mensajes transaccionales solo requieren el canal en `notification_preferences`. Los de marketing también requieren `consent.marketing`.

| Campo | Tipo | Por defecto | Descripción |
| - | - | - | - |
| `marketing` | boolean | `false` | Publicidad y promociones en cualquier canal |

### Preferencias de notificación

| Campo | Tipo | Por defecto | Descripción |
| - | - | - | - |
| `email` | boolean | `true` | Recibir correos |
| `push` | boolean | `true` | Recibir notificaciones push |
| `push_token` | string | — | Token de notificaciones push. Debe enviarse junto con `push_token_expires_at`. |
| `push_token_expires_at` | datetime | — | Obligatorio si se envía `push_token`. No se puede enviar sin `push_token`. Debe ser una fecha futura y como máximo 180 días. |

### Dirección de entrega

| Campo | Requerido | Descripción |
| - | - | - |
| `alias` | Sí | Etiqueta como "Casa" u "Oficina". |
| `address_line1` | Sí | Dirección principal. |
| `address_line2` | No | Apartamento, piso o suite. |
| `city` | No | Ciudad. |
| `state` | No | Estado o provincia. |
| `zip` | No | Código postal. |
| `country` | No | País. |
| `reference` | No | Punto de referencia. |
| `latitude` | No | Latitud entre -90 y 90. |
| `longitude` | No | Longitud entre -180 y 180. |
| `instructions` | No | Instrucciones de entrega. |
| `preferred` | No | Marcar como dirección predeterminada. Por defecto `false`. |
| `metadata` | No | Metadatos personalizados de esta dirección (`object` o `null`). |

### Perfil de facturación

| Campo | Requerido | Descripción |
| - | - | - |
| `alias` | Sí | Etiqueta como "Personal" o "Empresa". |
| `type` | Sí | `INDIVIDUAL` o `BUSINESS`. |
| `legal_name` | Sí | Nombre legal para facturación. |
| `address_line1` | Sí | Dirección de facturación principal. |
| `address_line2` | No | Línea adicional de dirección. |
| `city` | No | Ciudad. |
| `state` | No | Estado o provincia. |
| `zip` | No | Código postal. |
| `country` | No | País. |
| `tax_id` | Sí | Valor del identificador fiscal. |
| `tax_id_type` | Sí | Uno de `VAT`, `EIN`, `SSN`, `TIN`, `NIF`, `CUIT`, `RUT`, `NIT`, `RCN`, `RUC`, `CI`, `DNI`, `PASSPORT` u `OTHER`. |
| `preferred` | No | Marcar como perfil predeterminado. Por defecto `false`. |
| `metadata` | No | Metadatos personalizados de este perfil (`object` o `null`). |

## Solicitud

```bash theme={null}
curl -X POST "https://firespark.cloud/api/storefront/v1/customers" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "auth0|abc123",
    "name": "Juan Pérez",
    "email": "juan@example.com",
    "phone": "+593991234567",
    "consent": {
      "marketing": true
    },
    "notification_preferences": {
      "email": true,
      "push": true,
      "push_token": "ExponentPushToken[abc]",
      "push_token_expires_at": "2026-12-15T00:00:00Z"
    },
    "delivery_addresses": [
      {
        "alias": "Casa",
        "address_line1": "Av. Amazonas 123",
        "city": "Quito",
        "preferred": true,
        "metadata": null
      }
    ],
    "billing_profiles": [
      {
        "alias": "Personal",
        "type": "INDIVIDUAL",
        "legal_name": "Juan Pérez",
        "address_line1": "Av. Amazonas 123",
        "tax_id": "1712345678",
        "tax_id_type": "CI",
        "preferred": true,
        "metadata": null
      }
    ]
  }'
```

## Respuesta

Devuelve el cliente creado en `data`. La forma coincide con [obtener cliente](https://firespark.cloud/docs/es/storefront-api/customers/\[id]/get).

## Clientes anónimos

Para checkout como invitado, envía solo `id` e `is_anonymous: true`. Fire spark usa el `id` como nombre cuando no se proporciona `name`.

```bash theme={null}
curl -X POST "https://firespark.cloud/api/storefront/v1/customers" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id": "guest-7f3a", "is_anonymous": true}'
```

## Errores

| Estado | Descripción |
| - | - |
| `400` | Cuerpo de solicitud inválido. |
| `401` | Access token ausente o inválido. |
| `403` | El `id` no coincide con el id del token. |
| `422` | Ya existe un cliente con este `id`. |


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