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

# Organizaciones, comercios y locales

> Cómo estructura Maple los negocios con los que usted se integra, y por qué la Developer API trabaja a nivel de local.

Maple organiza cada negocio en una jerarquía de tres niveles. Usted trabajará sobre todo con el nivel inferior (los locales), pero entender la estructura completa evita suposiciones erróneas sobre a qué se refiere un ID y qué acceso tiene.

```mermaid theme={null}
flowchart TD
  Org[Organization] --> M1[Merchant]
  Org --> M2[Merchant]
  M1 --> L1[Location]
  M1 --> L2[Location]
  M2 --> L3[Location]
```

## Los tres niveles

<ParamField path="Organization" type="cuenta de nivel superior">
  La cuenta del socio. Una organización contiene uno o más comercios, y los miembros de su equipo pueden administrarlos todos.
</ParamField>

<ParamField path="Merchant" type="un negocio / una marca">
  Un negocio o una marca de restaurantes dentro de una organización. Un comercio contiene uno o más locales. Su entidad legal tiene a cargo la configuración de pagos y facturación.
</ParamField>

<ParamField path="Location" type="un solo restaurante">
  Un restaurante físico: la unidad con la que trabaja la Developer API y la unidad que Maple cotiza y factura. Un local pertenece a exactamente un comercio. Su ID tiene la forma `str_…` y la API lo expone como el recurso `location`.
</ParamField>

## Cardinalidad y por qué importa

* Una organización tiene **muchos** comercios; un comercio tiene **muchos** locales.
* Un local pertenece a **exactamente un** comercio, y un comercio a **como máximo una** organización. Esto no cambia: un local no se puede reasignar a otro comercio.
* **Los datos operativos viven en el local.** Los pedidos, menús, conexiones y webhooks están todos asociados a un local, no a un comercio ni a una organización. Dos locales del mismo comercio son independientes para su integración.

## Qué expone la Developer API

La Developer API expone **locales**. El recurso `location` incluye el ID del local (`str_…`), su nombre, estado, zona horaria, teléfono y dirección, pero no su comercio ni su organización de origen. Cuando lista locales, se conecta, recibe pedidos o publica un menú, siempre opera sobre un solo local mediante su ID `str_…`.

<Info>
  **El acceso es por local.** Un comercio otorga a su app acceso a locales específicos, uno por uno. Tener permiso sobre un
  local no le da acceso a los demás locales del mismo comercio: cada local se otorga (y se conecta) por separado. Consulte
  [Cómo funciona Maple](/es/developer-api/how-maple-works) para conocer los permisos y las conexiones.
</Info>

## Estado del local

El `status` de un local indica si está abierto para recibir pedidos:

| Estado | Significado |
| - | - |
| `active` | En vivo y aceptando pedidos |
| `paused` | Temporalmente sin aceptar pedidos |
| `inactive` | Aún no está en vivo (configuración incompleta) o fue desactivado |

Respételo: no espere pedidos de un local que no esté `active` ni le encamine trabajo.

## El ciclo de vida de la conexión

Su acceso a un local pasa por cuatro momentos, y tres eventos de webhook los marcan:

<Steps>
  <Step title="Aprovisionado (Provisioned)">
    Un comercio otorga a su app acceso a un local. Usted recibe **`store.provisioned`** y el local aparece en
    `GET /v1/locations`. Puede leerlo, pero los pedidos todavía no se dirigen a usted.
  </Step>

  <Step title="Conectado (Connected)">
    Usted llama a `POST /v1/locations/{id}/connection` para convertirse en el receptor de pedidos del local. El `status`
    de la conexión pasa a `active` y se dispara **`store.status.changed`** con `status: "connected"`. Ahora los pedidos se
    dirigen a usted.
  </Step>

  <Step title="Desconectado (Disconnected)">
    Usted (o Maple) elimina la conexión con `DELETE`. Se dispara **`store.status.changed`** con `status: "disconnected"`
    y los pedidos dejan de dirigirse a usted. El permiso se mantiene, por lo que puede volver a conectarse más adelante.
  </Step>

  <Step title="Desaprovisionado (Deprovisioned)">
    El comercio revoca el permiso. Usted recibe **`store.deprovisioned`** y pierde por completo el acceso al local.
  </Step>
</Steps>

Un local tiene como máximo una app conectada por entorno, así que un `POST` a un local que otra app ya tiene devuelve `409`. Consulte [Webhooks](/es/developer-api/concepts/webhooks) para suscribirse a estos eventos.

## Identificadores que verá

| Recurso | Prefijo del ID | ¿En la Developer API? |
| - | - | - |
| Local | `str_…` | Sí: el recurso `location` y cada `location_id` |
| Pedido | `ord_…` | Sí |
| Suscripción de webhook | `dws_…` | Sí |
| Evento | `evt_…` | Sí |

Los ID de comercio y de organización existen internamente, pero no forman parte de la Developer API: usted direcciona todo por local.

Para saber cómo administran los socios las organizaciones, los comercios y los locales en el panel, consulte [Cómo está organizado Maple](/es/partners/overview).


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