Crear cliente

Crea un cliente en Fire spark para el usuario identificado por el access token. Llama a este endpoint después del intercambio de token 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).

Requiere un access token de Fire spark obtenido mediante intercambio de token.

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

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.

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.

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

Documentación de API

Endpoints

Guías

Recursos

Cuerpo de la solicitud

Consentimiento

Preferencias de notificación

Dirección de entrega

Perfil de facturación

Solicitud

Respuesta

Clientes anónimos

Errores

​Cuerpo de la solicitud

​Consentimiento

​Preferencias de notificación

​Dirección de entrega

​Perfil de facturación

​Solicitud

​Respuesta

​Clientes anónimos

​Errores

Cuerpo de la solicitud

Consentimiento

Preferencias de notificación

Dirección de entrega

Perfil de facturación

Solicitud

Respuesta

Clientes anónimos

Errores