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

<ParamField path="Developer app" type="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.
</ParamField>

<ParamField path="Location" type="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](/es/developer-api/concepts/entities).
</ParamField>

<ParamField path="Connection" type="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.
</ParamField>

<ParamField path="Order" type="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.
</ParamField>

<ParamField path="Menu" type="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.
</ParamField>

<ParamField path="Webhook subscription" type="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.
</ParamField>

## Cómo se conectan

```mermaid theme={null}
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.

<Info>
  Trate los totales de Maple como autorizados. Su trabajo al recibir un pedido es decidir si puede prepararlo, no volver a
  calcular su precio.
</Info>

## 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](/es/developer-api/guides/receive-orders).
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](/es/developer-api/guides/receive-orders).

## 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](/es/developer-api/concepts/environments).

## Siguiente

<CardGroup cols={2}>
  <Card title="Inicio rápido" icon="rocket" href="/es/developer-api/quickstart">
    Haga usted mismo las primeras llamadas.
  </Card>

  <Card title="Autenticación" icon="key" href="/es/developer-api/concepts/authentication">
    Claves de API, entornos y alcances en detalle.
  </Card>
</CardGroup>


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