Listar tiendas

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

{
  "data": [
    {
      "id": "ubicacion-pos-01",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization_id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
      "merchant_id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "brand_id": "0001",
      "name": "Calle Principal",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "contact": {
        "email": "principal@comercio.com",
        "phone": "+593991234567",
        "name": "Calle Principal"
      },
      "location": {
        "latitude": -2.1894,
        "longitude": -79.8891,
        "address_line_1": "Calle Principal 456",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090101",
        "business_name": "Restaurante Calle Principal"
      },
      "channels": {
        "UBER_EATS": {
          "id": "uber-eats-principal",
          "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "Uber Eats",
          "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": 8,
                "maximum_order_value": 300,
                "tax_rate": 0.15,
                "fees": []
              },
              "coverage_zones": [
                {
                  "name": "Centro de la ciudad",
                  "type": "RADIUS",
                  "radius_info": {
                    "latitude": -2.1894,
                    "longitude": -79.8891,
                    "radius": 8000
                  }
                }
              ],
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "sunday": { "start_time": "08: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": "Datafast",
                "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 Calle Principal"
          }
        ]
      },
      "overrides": []
    }
  ]
}

GET

stores

Listar tiendas

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

{
  "data": [
    {
      "id": "ubicacion-pos-01",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization_id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
      "merchant_id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "brand_id": "0001",
      "name": "Calle Principal",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "contact": {
        "email": "principal@comercio.com",
        "phone": "+593991234567",
        "name": "Calle Principal"
      },
      "location": {
        "latitude": -2.1894,
        "longitude": -79.8891,
        "address_line_1": "Calle Principal 456",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090101",
        "business_name": "Restaurante Calle Principal"
      },
      "channels": {
        "UBER_EATS": {
          "id": "uber-eats-principal",
          "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "Uber Eats",
          "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": 8,
                "maximum_order_value": 300,
                "tax_rate": 0.15,
                "fees": []
              },
              "coverage_zones": [
                {
                  "name": "Centro de la ciudad",
                  "type": "RADIUS",
                  "radius_info": {
                    "latitude": -2.1894,
                    "longitude": -79.8891,
                    "radius": 8000
                  }
                }
              ],
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "sunday": { "start_time": "08: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": "Datafast",
                "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 Calle Principal"
          }
        ]
      },
      "overrides": []
    }
  ]
}

Devuelve todas las tiendas configuradas para el comercio autenticado. Usa este endpoint para mapear tiendas de Fire spark con ubicaciones en tu POS o RMS antes de sincronizar menús e inyectar pedidos.

Requiere un access token con el scope stores:read. Consulta Autorizar para obtener un token.

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.

Solicitud

curl "https://firespark.vercel.app/api/integrations/v1/stores" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-brand-id: 0001"

Respuesta

La respuesta envuelve un arreglo de tiendas en data. Cada tienda incluye la configuración operativa completa: contacto, ubicación, canales (con fulfillment por canal), pagos, metadatos de plantilla CMS y overrides programados.

{
  "data": [
    {
      "id": "ubicacion-pos-01",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "organization_id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
      "merchant_id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
      "brand_id": "0001",
      "name": "Calle Principal",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "contact": {
        "email": "principal@comercio.com",
        "phone": "+593991234567",
        "name": "Calle Principal"
      },
      "location": {
        "latitude": -2.1894,
        "longitude": -79.8891,
        "address_line_1": "Calle Principal 456",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090101",
        "business_name": "Restaurante Calle Principal"
      },
      "channels": {
        "UBER_EATS": {
          "id": "uber-eats-principal",
          "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
          "name": "Uber Eats",
          "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": 8,
                "maximum_order_value": 300,
                "tax_rate": 0.15,
                "fees": []
              },
              "coverage_zones": [
                {
                  "name": "Centro de la ciudad",
                  "type": "RADIUS",
                  "radius_info": {
                    "latitude": -2.1894,
                    "longitude": -79.8891,
                    "radius": 8000
                  }
                }
              ],
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "tuesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "wednesday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "thursday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "friday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "saturday": { "start_time": "08:00:00", "end_time": "23:00:00" },
                  "sunday": { "start_time": "08: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": "Datafast",
                "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 Calle Principal"
          }
        ]
      },
      "overrides": []
    }
  ]
}

Objeto tienda

Campo	Tipo	Descripción
`id`	string	Identificador externo de la tienda en tu POS o RMS. Solo alfanuméricos, `_` y `-`. 1–64 caracteres. Único por comercio.
`uid`	string (UUID)	Identificador interno de Fire spark.
`organization_id`	string (UUID)	Organización propietaria del comercio.
`merchant_id`	string (UUID)	Comercio al que pertenece la tienda.
`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. Cada canal incluye un mapa `fulfillment`.
`payments`	object	Métodos de pago 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 (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	Arreglo de 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 de tienda a aplicar. Incluye `contact`, `location`, `timezone`, `channels`, `payments` y `cms_template_id`.

Mapear tiendas con tu POS

Relaciona el campo id con el identificador de ubicación en tu POS o RMS. Fire spark usa este ID externo para dirigir la sincronización de menús y la inyección de pedidos al sitio correcto.

Los valores uid son identificadores estables de Fire spark. Usa id para mapeo entre sistemas y uid cuando referencies tiendas en otras llamadas a la API de Fire spark.

Respuestas de error

Estado	Descripción
`401`	Access token ausente o inválido.
`403`	El token no incluye el scope `stores:read`.

Actualizar producto Upsert de tiendas

⌘I

​Headers

​Solicitud

​Respuesta

​Objeto tienda

​Mapear tiendas con tu POS

​Respuestas de error

Headers

Solicitud

Respuesta

Objeto tienda

Mapear tiendas con tu POS

Respuestas de error