> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar tiendas cercanas

> Encuentra las ubicaciones del comercio más cercanas a una latitud y longitud.

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.

> [!NOTE]
>
> Requiere un access token de Fire spark obtenido mediante [intercambio de
> token](https://firespark.cloud/docs/es/storefront-api/oauth/exchange/post.md). Para el catálogo paginado
> completo, usa [listar tiendas](https://firespark.cloud/docs/es/storefront-api/stores/get.md).

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

```bash theme={null}
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](https://firespark.cloud/docs/es/storefront-api/stores/get.md), incluyendo `cms_template_id` y `cms` cuando hay una plantilla CMS asignada. Solo se incluyen tiendas `ACTIVE`.

```json Éxito theme={null}
{
  "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

1. **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.
2. **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.

> [!TIP]
>
> 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](https://firespark.cloud/docs/es/storefront-api/stores/get.md) 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.