Listar tiendas cercanas

Devuelve tiendas que pueden atender un punto de referencia: una tienda ACTIVE con al menos una zona de cobertura ACTIVE que cubre las coordenadas (RADIUS o POLYGON), ordenadas de la más cercana a la más lejana según la ubicación de la tienda. Úsalo para un mapa o un selector de “ubicación más cercana” cuando el cliente comparte GPS o una dirección geocodificada.

Requiere un access token de Fire spark obtenido mediante intercambio de token. Para el catálogo paginado completo, usa listar tiendas.

Parámetros de consulta

Parámetro	Requerido	Descripción
`latitude`	Sí	Latitud de referencia. Entre -90 y 90.
`longitude`	Sí	Longitud de referencia. Entre -180 y 180.
`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.
`channel_id`	No	Solo devuelve tiendas que tengan este canal activo en `channel_ids`.
`fulfillment_id`	No	Solo devuelve tiendas que tengan este fulfillment activo en `fulfillment_ids`.
`limit`	Sí	Máximo de tiendas a devolver. 1–100.

Solicitud

curl "https://firespark.cloud/api/storefront/v1/stores/nearby?brand_id=0001&latitude=-2.1894&longitude=-79.8891&limit=10" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Respuesta

La respuesta envuelve un arreglo de tiendas en data, ordenadas de la más cercana a la más lejana. Cada objeto usa la misma estructura que listar tiendas, incluyendo cms_template_id y cms cuando hay una plantilla CMS asignada. Solo se incluyen tiendas ACTIVE.

{
  "data": [
    {
      "id": "cocina-centro",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "merchant_id": "22222222-2222-2222-2222-222222222222",
      "brand_id": "0001",
      "name": "Cocina Centro",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "contact": {
        "email": "centro@merchant.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."
      },
      "instructions": null,
      "coverage_zones": [],
      "availability": {
        "schedules": null,
        "temporary_closed_reason": null,
        "temporary_closed_until": null,
        "status": "OPEN"
      },
      "channel_ids": ["web", "app"],
      "fulfillment_ids": ["delivery", "pickup"],
      "labels": [],
      "tags": {},
      "cms_template_id": null,
      "cms": null
    }
  ]
}

Cómo funcionan el matching y la distancia

Filtro de cobertura — Solo se devuelven tiendas con una zona ACTIVE que contiene el punto. Las zonas RADIUS usan distancia al centro dentro de radius (metros). Las zonas POLYGON usan punto-en-polígono.
Orden — Las tiendas coincidentes se ordenan por distancia en línea recta desde las coordenadas de la consulta hasta la location de la tienda (geografía PostGIS del punto de la tienda).

Se omiten tiendas sin ubicación geocodificada o sin zonas que cubran el punto.

Combina este endpoint con el GPS del dispositivo o una dirección geocodificada. Usa un limit bajo (por ejemplo 5) para selectores compactos, o un valor mayor al renderizar un mapa con más marcadores.

Campos de la tienda

Consulta listar tiendas para el esquema completo.

Respuestas de error

Estado	Descripción
`400`	`latitude`, `longitude` o `limit` ausentes o inválidos.
`401`	Access token ausente o inválido.
`403`	El token no tiene acceso a las tiendas de este comercio.

Documentación de API

Endpoints

Guías

Recursos

Listar tiendas cercanas

Parámetros de consulta

Solicitud

Respuesta

Cómo funcionan el matching y la distancia

Campos de la tienda

Respuestas de error

​Parámetros de consulta

​Solicitud

​Respuesta

​Cómo funcionan el matching y la distancia

​Campos de la tienda

​Respuestas de error

Parámetros de consulta

Solicitud

Respuesta

Cómo funcionan el matching y la distancia

Campos de la tienda

Respuestas de error