Ir al contenido
Maple

    Conceptos clave

    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.

    flowchart TD
  Org[Organization] --> M1[Merchant]
  Org --> M2[Merchant]
  M1 --> L1[Location]
  M1 --> L2[Location]
  M2 --> L3[Location]

    Los tres niveles

    Organization

    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.

    Merchant

    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.

    Location

    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.

    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_….

    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:

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

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

    3. 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.

    4. Desaprovisionado (Deprovisioned)

      El comercio revoca el permiso. Usted recibe store.deprovisioned y pierde por completo el acceso al local.

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