Listar tiendas

curl --request GET \
  --url https://api.example.com/stores

{
  "data": [
    {
      "id": "cocina-centro",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "brand_id": "0001",
      "name": "Cocina Centro",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "contact": {
        "email": "centro@comercio.com",
        "phone": "+593991234567",
        "name": "Cocina Centro"
      },
      "location": {
        "latitude": -2.1894,
        "longitude": -79.8891,
        "address_line_1": "Av. 9 de Octubre 123",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090101",
        "business_name": "Cocina Centro S.A."
      },
      "channels": {
        "APP": {
          "id": "canal-app",
          "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "App móvil",
          "fulfillment": {
            "DELIVERY": {
              "uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
              "id": "delivery",
              "type": "DELIVERY",
              "name": "Delivery",
              "instructions": { "es_ec": "Tocar el timbre en la entrada lateral." },
              "pricing": {
                "is_tax_inclusive": false,
                "minimum_order_value": 10,
                "maximum_order_value": 200,
                "tax_rate": 0.15,
                "fees": [
                  {
                    "id": "tarifa-delivery",
                    "type": "FIXED",
                    "tax_inclusive": false,
                    "name": { "es_ec": "Costo de envío" },
                    "amount": 2.5,
                    "percentage": 0
                  }
                ]
              },
              "coverage_zones": [
                {
                  "name": "Centro",
                  "type": "RADIUS",
                  "radius_info": {
                    "latitude": -2.1894,
                    "longitude": -79.8891,
                    "radius": 5000
                  }
                }
              ],
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "sunday": { "start_time": "10:00:00", "end_time": "23:00:00" }
                }]
              }
            }
          }
        }
      },
      "payments": {
        "orderable": true,
        "methods": [
          {
            "method": "CREDIT",
            "minimum_order_value": 0,
            "maximum_order_value": 500,
            "providers": [
              {
                "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
                "name": "Stripe",
                "status": "ACTIVE"
              }
            ]
          }
        ]
      },
      "cms_template_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
      "cms": {
        "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
        "name": "Landing de tienda",
        "entity": "STORES",
        "status": "ACTIVE",
        "fields": [
          {
            "name": "hero_title",
            "type": "TEXT",
            "label": { "es_ec": "Título principal" },
            "required": true,
            "value": "Bienvenido a Downtown Kitchen"
          }
        ]
      },
      "overrides": []
    }
  ]
}

GET

stores

Listar tiendas

curl --request GET \
  --url https://api.example.com/stores

{
  "data": [
    {
      "id": "cocina-centro",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "brand_id": "0001",
      "name": "Cocina Centro",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "contact": {
        "email": "centro@comercio.com",
        "phone": "+593991234567",
        "name": "Cocina Centro"
      },
      "location": {
        "latitude": -2.1894,
        "longitude": -79.8891,
        "address_line_1": "Av. 9 de Octubre 123",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090101",
        "business_name": "Cocina Centro S.A."
      },
      "channels": {
        "APP": {
          "id": "canal-app",
          "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "App móvil",
          "fulfillment": {
            "DELIVERY": {
              "uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
              "id": "delivery",
              "type": "DELIVERY",
              "name": "Delivery",
              "instructions": { "es_ec": "Tocar el timbre en la entrada lateral." },
              "pricing": {
                "is_tax_inclusive": false,
                "minimum_order_value": 10,
                "maximum_order_value": 200,
                "tax_rate": 0.15,
                "fees": [
                  {
                    "id": "tarifa-delivery",
                    "type": "FIXED",
                    "tax_inclusive": false,
                    "name": { "es_ec": "Costo de envío" },
                    "amount": 2.5,
                    "percentage": 0
                  }
                ]
              },
              "coverage_zones": [
                {
                  "name": "Centro",
                  "type": "RADIUS",
                  "radius_info": {
                    "latitude": -2.1894,
                    "longitude": -79.8891,
                    "radius": 5000
                  }
                }
              ],
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "sunday": { "start_time": "10:00:00", "end_time": "23:00:00" }
                }]
              }
            }
          }
        }
      },
      "payments": {
        "orderable": true,
        "methods": [
          {
            "method": "CREDIT",
            "minimum_order_value": 0,
            "maximum_order_value": 500,
            "providers": [
              {
                "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
                "name": "Stripe",
                "status": "ACTIVE"
              }
            ]
          }
        ]
      },
      "cms_template_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
      "cms": {
        "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
        "name": "Landing de tienda",
        "entity": "STORES",
        "status": "ACTIVE",
        "fields": [
          {
            "name": "hero_title",
            "type": "TEXT",
            "label": { "es_ec": "Título principal" },
            "required": true,
            "value": "Bienvenido a Downtown Kitchen"
          }
        ]
      },
      "overrides": []
    }
  ]
}

Devuelve un listado paginado de tiendas desde las que un cliente puede pedir. Usa este endpoint para selectores de ubicación o para explorar el catálogo completo. Para encontrar tiendas cercanas al cliente, usa listar tiendas por coordenadas.

Requiere un access token de Fire spark obtenido mediante intercambio de token. El token limita las solicitudes al cliente autenticado y al comercio correspondiente.

Headers

Header	Requerido	Descripción
`x-brand-id`	No	Filtra tiendas por marca. Identificador externo de la marca — solo alfanuméricos, `_` y `-`. 1–64 caracteres. Si se omite, se devuelven todas las tiendas del comercio.

Parámetros de consulta

Parámetro	Requerido	Descripción
`from`	Sí	Índice inicial (base 0).
`to`	Sí	Índice final (inclusivo). Debe ser mayor o igual que `from`.
`limit`	Sí	Máximo de registros por solicitud. 1–100. El rango `to - from` no puede superar `limit`.

Solicita la primera página con from=0, to=24 y limit=25. Para la siguiente página, usa from=25, to=49 y el mismo limit.

Solicitud

curl "https://firespark.vercel.app/api/storefront/v1/stores?from=0&to=24&limit=25" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-brand-id: 0001"

Respuesta

La respuesta envuelve un arreglo de tiendas en data. Cada tienda incluye ubicación, canales, fulfillment, pagos y disponibilidad para que tu canal determine dónde puede pedir el cliente.

{
  "data": [
    {
      "id": "cocina-centro",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "brand_id": "0001",
      "name": "Cocina Centro",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "contact": {
        "email": "centro@comercio.com",
        "phone": "+593991234567",
        "name": "Cocina Centro"
      },
      "location": {
        "latitude": -2.1894,
        "longitude": -79.8891,
        "address_line_1": "Av. 9 de Octubre 123",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090101",
        "business_name": "Cocina Centro S.A."
      },
      "channels": {
        "APP": {
          "id": "canal-app",
          "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "App móvil",
          "fulfillment": {
            "DELIVERY": {
              "uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
              "id": "delivery",
              "type": "DELIVERY",
              "name": "Delivery",
              "instructions": { "es_ec": "Tocar el timbre en la entrada lateral." },
              "pricing": {
                "is_tax_inclusive": false,
                "minimum_order_value": 10,
                "maximum_order_value": 200,
                "tax_rate": 0.15,
                "fees": [
                  {
                    "id": "tarifa-delivery",
                    "type": "FIXED",
                    "tax_inclusive": false,
                    "name": { "es_ec": "Costo de envío" },
                    "amount": 2.5,
                    "percentage": 0
                  }
                ]
              },
              "coverage_zones": [
                {
                  "name": "Centro",
                  "type": "RADIUS",
                  "radius_info": {
                    "latitude": -2.1894,
                    "longitude": -79.8891,
                    "radius": 5000
                  }
                }
              ],
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "10:00:00", "end_time": "23:00:00" },
                  "sunday": { "start_time": "10:00:00", "end_time": "23:00:00" }
                }]
              }
            }
          }
        }
      },
      "payments": {
        "orderable": true,
        "methods": [
          {
            "method": "CREDIT",
            "minimum_order_value": 0,
            "maximum_order_value": 500,
            "providers": [
              {
                "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
                "name": "Stripe",
                "status": "ACTIVE"
              }
            ]
          }
        ]
      },
      "cms_template_id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
      "cms": {
        "id": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
        "name": "Landing de tienda",
        "entity": "STORES",
        "status": "ACTIVE",
        "fields": [
          {
            "name": "hero_title",
            "type": "TEXT",
            "label": { "es_ec": "Título principal" },
            "required": true,
            "value": "Bienvenido a Downtown Kitchen"
          }
        ]
      },
      "overrides": []
    }
  ]
}

Objeto tienda

Campo	Tipo	Descripción
`id`	string	Identificador externo de la tienda en tus sistemas. Solo alfanuméricos, `_` y `-`. 1–64 caracteres.
`uid`	string (UUID)	Identificador interno de Fire spark.
`brand_id`	string	Identificador externo de la marca. Solo alfanuméricos, `_` y `-`. 1–64 caracteres. Opcional — `null` cuando el comercio opera con una sola marca.
`name`	string	Nombre visible. 1–100 caracteres.
`status`	string	`ACTIVE` o `INACTIVE`.
`timezone`	string	Zona horaria IANA para horarios y overrides.
`contact`	object	Datos de contacto de la tienda.
`location`	object	Dirección física y coordenadas.
`channels`	object	Configuración de fulfillment por canal, indexada por código de canal. Cada canal contiene un mapa `fulfillment`.
`payments`	object	Métodos de pago aceptados y límites de pedido.
`cms_template_id`	string (UUID)	Plantilla CMS vinculada a esta tienda. `null` cuando no hay plantilla asignada.
`cms`	object	Solo lectura. `null` cuando `cms_template_id` es `null`. Si está asignada, la plantilla CMS resuelta con definiciones de campos y valores guardados.
`overrides`	array	Cambios de configuración programados.

contact

Campo	Tipo	Requerido	Descripción
`email`	string	Sí	Dirección de correo válida.
`phone`	string	Sí	Formato E.164 (por ejemplo `+593991234567`).
`name`	string	No	Nombre de contacto.

location

| Campo | Tipo | Requerido | Descripción | | ----- | ---- | --------- | ----------- | | latitude | number | Sí | Entre -90 y 90. | | longitude | number | Sí | Entre -180 y 180. | | address_line_1 | string | Sí | 3–255 caracteres. | | address_line_2 | string | No | 3–255 caracteres. | | city | string | Sí | 1–100 caracteres. | | country | string | Sí | 1–100 caracteres. | | postal_code | string | Sí | Solo números. 4–10 dígitos. | | business_name | string | Sí | Razón social o nombre comercial. 1–100 caracteres. | | unit_number | string | No | Solo números. 1–10 dígitos. |

channels

Mapa de códigos de canal a su configuración. Cada entrada contiene:

Campo	Tipo	Descripción
`id`	string	Identificador externo del canal.
`uid`	string (UUID)	Identificador del canal en Fire spark.
`name`	string	Nombre visible.
`fulfillment`	object	Mapa de tipos de fulfillment disponibles en este canal. Cada clave es un código de fulfillment (por ejemplo `DELIVERY`, `PICKUP`).

Cada entrada de fulfillment requiere uid, id, type, name, pricing, coverage_zones y availability. instructions es opcional como objeto localizado.

pricing

Campo	Tipo	Descripción
`is_tax_inclusive`	boolean	Si los precios incluyen impuestos.
`minimum_order_value`	number	Monto mínimo de pedido. ≥ 0.
`maximum_order_value`	number	Monto máximo de pedido. 0–1,000,000.
`tax_rate`	number	Tasa de impuesto como decimal (por ejemplo `0.15` para 15%). 0–1.
`fees`	array	Cargos adicionales aplicados al pedido.

Cada cargo:

Campo	Tipo	Descripción
`id`	string	Identificador externo del cargo.
`type`	string	`FIXED` o `PERCENTAGE`.
`tax_inclusive`	boolean	Si el cargo incluye impuestos.
`name`	object	Etiqueta localizada por locale (por ejemplo `es_ec`).
`description`	object	Descripción localizada opcional.
`amount`	number	Monto fijo cuando `type` es `FIXED`. ≥ 0.
`percentage`	number	Tasa cuando `type` es `PERCENTAGE`. 0–1.

availability

Campo	Tipo	Descripción
`status`	string	`OPEN`, `CLOSED` o `TEMPORARILY_CLOSED`.
`schedules`	array \| null	Mapas de horario semanal indexados por día (`monday` a `sunday`). `null` cuando no hay restricción de horarios.
`temporary_closed_reason`	object	Motivo localizado cuando está temporalmente cerrado.
`temporary_closed_until`	string	Fecha y hora ISO 8601 en que termina el cierre temporal.

Cada mapa de horario se indexa por día (monday a sunday). Incluye solo los días en que opera la tienda. Cada día:

Campo	Tipo	Descripción
`start_time`	string	Hora ISO (por ejemplo `09:00:00`).
`end_time`	string	Hora ISO (por ejemplo `22:00:00`).

fulfillment

Campo	Tipo	Descripción
`uid`	string (UUID)	Identificador de fulfillment en Fire spark.
`id`	string	Identificador externo de fulfillment.
`type`	string	Código de tipo de fulfillment (por ejemplo `DELIVERY`, `PICKUP`).
`name`	string	Nombre visible.
`instructions`	object	Instrucciones localizadas opcionales para el cliente.
`pricing`	object	Reglas de precio para este tipo de fulfillment.
`coverage_zones`	array	Zonas de entrega o servicio.
`availability`	object	Horarios y estado operativo.

Zona de cobertura:

Campo	Tipo	Descripción
`name`	string	Etiqueta de la zona.
`type`	string	`RADIUS` o `POLYGON`.
`radius_info`	object	Requerido cuando `type` es `RADIUS`. Contiene `latitude`, `longitude` y `radius` (metros, 0–100,000).
`polygon_info`	object	Requerido cuando `type` es `POLYGON`. Contiene `polygon`, un arreglo de puntos `{ latitude, longitude }`.

payments

Campo	Tipo	Descripción
`orderable`	boolean	Si la tienda acepta pedidos.
`methods`	array	Métodos de pago aceptados.

Cada método de pago:

Campo	Tipo	Descripción
`method`	string	`CREDIT`, `DEBIT`, `CASH`, `BANK_TRANSFER` u `OTHER`.
`minimum_order_value`	number	Pedido mínimo para este método. ≥ 0.
`maximum_order_value`	number	Pedido máximo para este método. 0–1,000,000.
`providers`	array	Proveedores de pago para este método.

Cada proveedor:

Campo	Tipo	Descripción
`id`	string (UUID)	Identificador del proveedor.
`name`	string	Nombre visible del proveedor.
`status`	string	`ACTIVE` o `INACTIVE`.

cms

Presente solo cuando cms_template_id no es null. Contiene la plantilla CMS resuelta asignada a la tienda.

Campo	Tipo	Descripción
`id`	string (UUID)	Identificador de la plantilla. Coincide con `cms_template_id`.
`name`	string	Nombre de la plantilla. 1–100 caracteres.
`entity`	string	Siempre `STORES` en respuestas de tienda.
`status`	string	`ACTIVE` o `INACTIVE`.
`fields`	array	Campos de la plantilla con sus valores guardados actuales.

Cada campo en fields:

Campo	Tipo	Descripción
`name`	string	Clave del campo.
`type`	string	`TEXT`, `SELECT`, `IMAGE` o `LIST`.
`label`	object	Etiqueta localizada opcional por locale.
`required`	boolean	Si el campo es obligatorio.
`placeholder`	string	Texto de placeholder opcional.
`options`	array	Para campos `SELECT` — objetos con `label` y `value`.
`altText`	string	Para campos `IMAGE` — texto alternativo.
`src`	string	Para campos `IMAGE` — URL de la imagen.
`href`	string	Para campos `IMAGE` — URL de enlace opcional.
`value`	varía	Valor guardado actual para esta tienda. Se omite cuando está vacío.

overrides

Cambios programados que entran en vigor en una fecha futura. Cada override contiene:

Campo	Tipo	Descripción
`start_date`	string	Fecha y hora ISO 8601 en que el override se activa.
`changes`	object	Configuración parcial de tienda a aplicar. Incluye `contact`, `location`, `timezone`, `channels`, `payments` y `cms_template_id`.

Respuestas de error

Estado	Descripción
`400`	Parámetros de paginación inválidos. `from` debe ser ≤ `to`, y `to - from` no debe superar `limit`.
`401`	Access token ausente o inválido.
`403`	El token no tiene acceso a las tiendas de este comercio.

Obtener canal Listar tiendas cercanas

⌘I

​Headers

​Parámetros de consulta

​Solicitud

​Respuesta

​Objeto tienda

​Respuestas de error

Headers

Parámetros de consulta

Solicitud

Respuesta

Objeto tienda

Respuestas de error