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

# 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](https://docs.maple.inc/es/developer-api/concepts/entities.md).

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

> [!NOTE]
>
> Trate los totales de Maple como autorizados. Su trabajo al recibir un pedido es decidir si puede prepararlo, no volver a calcular su precio.

## 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](https://docs.maple.inc/es/developer-api/guides/receive-orders.md).
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](https://docs.maple.inc/es/developer-api/guides/receive-orders.md).

## 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](https://docs.maple.inc/es/developer-api/concepts/environments.md).

## Siguiente

- [Inicio rápido](https://docs.maple.inc/es/developer-api/quickstart.md): Haga usted mismo las primeras llamadas.
- [Autenticación](https://docs.maple.inc/es/developer-api/concepts/authentication.md): Claves de API, entornos y alcances en detalle.