Saltar al contenido principal
GET
/
stores
/
nearby
Listar tiendas cercanas
curl --request GET \
  --url https://api.example.com/stores/nearby
{
  "data": [
    {
      "id": "cocina-centro",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Cocina Centro",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "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": "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",
              "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" }
                }]
              }
            }
          }
        }
      }
    },
    {
      "id": "plaza-norte",
      "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Plaza Norte",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "location": {
        "latitude": -2.1523,
        "longitude": -79.9021,
        "address_line_1": "Av. Francisco de Orellana 890",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090150",
        "business_name": "Plaza Norte S.A."
      },
      "channels": {
        "APP": {
          "id": "app",
          "uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "name": "App móvil",
          "fulfillment": {
            "PICKUP": {
              "uid": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
              "id": "pickup",
              "type": "PICKUP",
              "name": "Pickup",
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "09:00:00", "end_time": "21:00:00" },
                  "saturday": { "start_time": "10:00:00", "end_time": "20:00:00" },
                  "sunday": { "start_time": "10:00:00", "end_time": "20:00:00" }
                }]
              }
            }
          }
        }
      }
    }
  ]
}
Devuelve tiendas ordenadas por distancia desde un punto de referencia. Usa este endpoint cuando el cliente comparte su ubicación y necesitas las tiendas más cercanas hasta un límite dado — por ejemplo, un mapa o un selector de “ubicación más cercana”.
Requiere un access token de Fire spark obtenido mediante intercambio de token. Para el catálogo paginado completo, usa listar tiendas.

​
Headers

HeaderRequeridoDescripción
x-brand-idNoFiltra 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ámetroRequeridoDescripción
latitudeSíLatitud de referencia. Entre -90 y 90.
longitudeSíLongitud de referencia. Entre -180 y 180.
limitSíMáximo de tiendas a devolver. 1–100.

​
Solicitud

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

​
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",
      "name": "Cocina Centro",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "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": "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",
              "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" }
                }]
              }
            }
          }
        }
      }
    },
    {
      "id": "plaza-norte",
      "uid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Plaza Norte",
      "status": "ACTIVE",
      "timezone": "America/Guayaquil",
      "location": {
        "latitude": -2.1523,
        "longitude": -79.9021,
        "address_line_1": "Av. Francisco de Orellana 890",
        "city": "Guayaquil",
        "country": "Ecuador",
        "postal_code": "090150",
        "business_name": "Plaza Norte S.A."
      },
      "channels": {
        "APP": {
          "id": "app",
          "uid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "name": "App móvil",
          "fulfillment": {
            "PICKUP": {
              "uid": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
              "id": "pickup",
              "type": "PICKUP",
              "name": "Pickup",
              "availability": {
                "status": "OPEN",
                "schedules": [{
                  "monday": { "start_time": "09:00:00", "end_time": "21:00:00" },
                  "saturday": { "start_time": "10:00:00", "end_time": "20:00:00" },
                  "sunday": { "start_time": "10:00:00", "end_time": "20:00:00" }
                }]
              }
            }
          }
        }
      }
    }
  ]
}

​
Cómo se calcula la distancia

Fire spark ordena las tiendas por distancia en línea recta desde las coordenadas proporcionadas hasta location.latitude y location.longitude de cada tienda. Las zonas de cobertura de delivery no se aplican en esta etapa — revisa channels[canal].fulfillment[tipo].coverage_zones después de que el cliente seleccione una tienda.
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

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