Ir al contenido
Maple

    Primeros pasos

    Cómo funciona Maple

    Los objetos y relaciones detrás de cada integración: apps, locales, conexiones y la división de responsabilidades entre usted y Maple.

    Antes de escribir código, conviene tener todo el modelo en mente. Hay solo unos pocos objetos y encajan en una sola dirección.

    Los objetos

    Developer app

    su identidad

    Su integración aprobada, asignada explícitamente por Maple a una organización de desarrolladores. Los miembros invitados de la organización crean claves mediante la consola de desarrolladores. Las credenciales, autorizaciones y suscripciones son independientes por entorno; el sandbox y producción son implementaciones separadas. La aprobación de la app y los límites de los alcances (scopes) siguen a cargo de Maple.

    Location

    un restaurante

    Un solo restaurante: la unidad con la que trabaja la Developer API (ID str_…). Un comercio autoriza a su app a acceder a un local; esa autorización le permite leerlo. Los locales tienen un status (active, inactive, paused) que usted debe respetar. Los locales dependen de comercios y organizaciones; consulte Organizaciones, comercios y locales.

    Connection

    usted es el receptor de pedidos

    Conectarse a un local autorizado convierte a su app en su receptor de pedidos. Los pedidos llegan a usted solo después de que existe una conexión. Un local puede estar conectado a exactamente una app por entorno.

    Order

    lo que pidió un cliente

    El pedido de un cliente en un local conectado, con artículos, totales (calculados por Maple) y un objeto de pago. Usted lo conduce por su ciclo de vida con llamadas de decisión.

    Menu

    de dónde se pide

    El catálogo de un local (categorías, artículos, variantes, modificadores y definiciones de impuestos y cargos), publicado como un solo documento JSON con sus propios IDs externos.

    Webhook subscription

    cómo se entera de los eventos

    Un endpoint HTTPS más los tipos de evento que desea. Maple firma y entrega los eventos a ese endpoint, y mantiene un registro de eventos desde el cual puede repetirlos.

    Cómo se conectan

    flowchart LR
  App[Your developer app] -- granted --> Loc[Location]
  App -- connection --> Loc
  Loc -- emits --> Order[Order]
  App -- publishes --> Menu[Menu]
  Order -- order.notification --> Hook[Your webhook endpoint]
  Hook -- accept / deny / ready / complete --> Order

    Un comercio le autoriza un local → usted se conecta a él → los pedidos de ese local se envían a su webhook → usted decide cada pedido. En paralelo, usted publica el menú con el que se arman esos pedidos.

    Quién es responsable de qué

    Esto es lo más importante de entender, y lo que la mayoría de las integraciones de restaurantes hace mal. Maple se encarga de las partes que conllevan riesgo:

    Maple se encarga de Usted se encarga de
    El ciclo de pago del cliente (enlaces de pago respaldados por Stripe) Recibir los pedidos y decidirlos
    Todo cálculo de totales, impuestos y cargos que ve el cliente Reflejar el estado del pedido (accept, ready, complete)
    Los datos de tarjetas y el alcance de PCI Publicar un menú preciso
    Entregar, reintentar y firmar los webhooks Verificar firmas y eliminar eventos duplicados

    Usted nunca calcula un precio, toca una tarjeta ni construye un flujo de pago. Maple le entrega un pedido con totals ya definitivos y un objeto payment que puede leer pero no administrar.

    El ciclo de pedidos, de principio a fin

    1. Un cliente hace un pedido en un local conectado.
    2. (Opcional) Maple envía order.validation_requested y espera que usted confirme que el pedido se puede preparar. Consulte validación de pedidos.
    3. Maple envía order.notification con el pedido completo.
    4. Usted lo acepta o lo rechaza.
    5. Usted informa el avance (ready y luego complete) o cancela si debe hacerlo después de aceptar.
    6. Usted recibe order.cancelled si el cliente o el local cancela.

    Toda llamada de decisión es segura ante repeticiones, así que los reintentos son inofensivos. La secuencia completa está en Reciba y decida pedidos.

    Entornos

    Maple opera dos entornos aislados, cada uno con su propia URL base:

    • Sandbox — https://api.staging.maple.inc/v1, con su clave mpk_test_…. Para desarrollo y pruebas.
    • Producción — https://api.maple.inc/v1, con su clave mpk_live_…. Tráfico real.

    Usted construye y verifica todo en el sandbox con datos aislados y luego apunta el mismo código a producción una vez aprobada su integración. Los dos entornos nunca ven los datos del otro. Más en Entornos y modo de prueba.

    Siguiente

    Inicio rápido

    Haga usted mismo las primeras llamadas.

    Autenticación

    Claves de API, entornos y alcances en detalle.