> ## 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. # Inicio rápido > Inicie sesión en la consola para desarrolladores, cree su propia clave y verifique las solicitudes a la API y los webhooks firmados. Use la consola para desarrolladores para administrar las credenciales y los webhooks de una app que Maple haya aprobado. Comience en el entorno de pruebas (sandbox) y complete un flujo de negocio compatible antes de solicitar acceso a producción. ## Antes de empezar Necesita una invitación a una organización de desarrolladores, una app aprobada asignada a esa organización y el panel del entorno que va a usar: `https://app.staging.maple.inc` para el sandbox o `https://app.maple.inc` para producción (consulte [Entornos](https://docs.maple.inc/es/developer-api/concepts/environments.md)). Maple prepara su sandbox y otorga los locales que su integración necesita. **Crear una clave no crea un sandbox ni otorga acceso a locales.** Si no tiene una invitación o una app aprobada, [contacte a Maple](https://maple.inc/get-started). El registro público, la aprobación de apps, el acceso a locales y la activación en producción no son de autoservicio. ## Empiece con un agente de programación Si un agente de programación (Claude Code, Cursor, Codex o similar) está construyendo su integración, copie este prompt en él cuando tenga una clave de sandbox en `MAPLE_KEY`. El prompt dirige al agente a estas docs y a la referencia de la API, lo mantiene en el sandbox y le indica cómo reportar cualquier obstáculo de la API. > Configure un agente de programación para construir sobre la Maple Developer API en el sandbox. > > You are building an integration with the Maple Developer API in this repository. > > Read these first: > > - The docs index: > - The quickstart: > - The OpenAPI spec, which is the source of truth for every endpoint and field: > > Rules: > > - Use the sandbox only. The base URL is `https://api.staging.maple.inc/v1`, and the key is in the `MAPLE_KEY` environment variable (it starts with `mpk_test_`). Never print, log, or commit the key, and ask me before doing anything against production. > - Send the key as `Authorization: Bearer $MAPLE_KEY`. Start by calling `GET /me` to confirm the app, the environment, and the scopes the key has, and plan around those scopes. > - Keep the `x-request-id` header from every response. It identifies the request in the developer console and in feedback. > - Branch on an error’s `_tag` and `code`, never its `message`. Follow `Retry-After` on a 429. > - Verify the HMAC signature on every webhook before acting on it. > > When the API gets in your way (a bug, a capability you need that is missing, docs that disagree with what the API does, or an error that does not tell you what to change), report it with `POST /v1/feedback`, citing the `x-request-id` values involved, then carry on with the best workaround you have. See for the fields. > > Start by reading the docs above, calling `GET /me`, and telling me what the key can do and which guide fits what we are building. 1. ### Inicie sesión y seleccione su app Siga su invitación, inicie sesión con el correo invitado y abra **Developers**. Seleccione la organización y la app aprobada correctas. No necesita crear ni seleccionar un restaurante. Revise la insignia **Sandbox** o **Production** y la URL base de la API antes de continuar. Cada panel administra únicamente su propio despliegue. Use la invitación o la URL del panel correspondiente al cambiar de entorno; no suponga que la sesión o los datos se comparten. Si no aparece ninguna app, pida a Maple que la apruebe o la vincule a la organización seleccionada. El acceso como personal por sí solo no hace que una app esté disponible en la consola para desarrolladores. 2. ### Cree y guarde una clave En **Overview & keys**, elija **Create key**, asígnele un nombre y seleccione solo los alcances (scopes) aprobados que su cliente necesita. Guarde la clave completa en un lugar seguro: se muestra una sola vez y no se puede recuperar después de cerrar el cuadro de diálogo. Defina `MAPLE_KEY` en el entorno de su propio cliente. Los ejemplos usan esa variable; no pegue una clave en documentación, control de versiones, capturas de pantalla ni campos del historial de solicitudes. Defina la URL base pública que muestra su consola de sandbox: ```bash export MAPLE_BASE="https://api.staging.maple.inc/v1" ``` Una app suspendida o revocada no puede autenticarse con sus claves. Aun así, puede revisar y revocar claves en la consola. 3. ### Verifique su identidad Ejecute el comando **/me** copiado desde **Getting started**, o use: ```bash curl --include "$MAPLE_BASE/me" \ -H "Authorization: Bearer $MAPLE_KEY" ``` ```json { "object": "developer_app", "id": "dap_...", "name": "Your Integration", "environment": "test", "scopes": ["locations:read", "webhooks:read", "webhooks:write"] } ``` Confirme la app, el entorno y los alcances efectivos. Conserve el encabezado de respuesta **`x-request-id`** para ubicar esta llamada en **Requests**. Los permisos de una clave nunca superan el límite de alcances aprobado actualmente para la app. 4. ### Revise sus locales **Granted locations** muestra los accesos configurados para esta app. Para leer locales mediante la API, use una clave con `locations:read`: ```bash curl --include "$MAPLE_BASE/locations" \ -H "Authorization: Bearer $MAPLE_KEY" ``` Una lista vacía no es una solicitud para crear un restaurante en el portal. Pida a Maple que le proporcione el local de pruebas y el acceso que su integración necesita. Un acceso otorgado y una conexión de receptor de pedidos son cosas distintas. Para una integración de pedidos/POS, siga [Reciba y decida pedidos](https://docs.maple.inc/es/developer-api/guides/receive-orders.md) para conectar el local autorizado. Para reservas, lea el [perfil de reservas y la guía de reservas](https://docs.maple.inc/es/developer-api/guides/take-bookings.md); no cree una conexión de receptor de pedidos solo para probar reservas. 5. ### Registre y pruebe un webhook Abra **Webhooks → Endpoints**, elija **Add endpoint**, ingrese una URL HTTPS pública que usted controle y seleccione los tipos de evento compatibles. Su app necesita `webhooks:read` para ver esta sección y `webhooks:write` para cambiar endpoints o enviar pruebas. Guarde el secreto de firma de un solo uso e implemente la [verificación de firma](https://docs.maple.inc/es/developer-api/concepts/webhooks.md) en su receptor. Crear un endpoint no envía una prueba automáticamente. Elija **Send test**. Un resultado entregado significa que el receptor devolvió un `2xx`; no demuestra que su controlador verificó la firma. Las pruebas fallidas u omitidas no son un éxito. Una prueba es un solo intento, sin reintento automático programado por la acción. 6. ### Encuentre la solicitud y la entrega En **Requests**, busque el `x-request-id` de su llamada a la API. Revise su estado y un resumen seguro del error, sin necesidad de acceder a los registros internos. El historial cubre las solicitudes hechas con las claves o tokens de su app, incluidos los revocados, y se conserva durante 7 días; las solicitudes sin una credencial reconocida no se registran. Un servicio de historial no disponible no equivale a un historial vacío y correcto. En **Webhooks → Deliveries**, revise el resultado de la prueba firmada, el número de intentos, el estado HTTP y las marcas de tiempo. El historial es un agregado por evento/endpoint, no una línea de tiempo por intento. Las URL y el estado habilitado describen la configuración actual del endpoint, no el destino de una solicitud pasada. Para un evento de negocio reproducible, **Review event** muestra una vista previa de un reintento a nivel de evento. Confírmelo para reintentar los destinos elegibles; los pares exitosos y los destinos deshabilitados se omiten. Las filas que son solo de prueba ofrecen **Send another test**, no la reproducción de una entrada inexistente en el registro de eventos. Consulte [Webhooks](https://docs.maple.inc/es/developer-api/concepts/webhooks.md) para conocer los límites y los resultados inciertos. **Check recent activity** en Getting started lee bajo demanda los metadatos recientes de `/me` y de pruebas entregadas. Es una pista de configuración, no una prueba de que su clave actual, la configuración actual de su endpoint o su integración completa estén verificadas. 7. ### Complete su flujo de negocio y verifique la revocación Use la guía de su integración aprobada para ejecutar una operación real en su local de pruebas aislado; por ejemplo, disponibilidad → bloqueo → creación → cambio/cancelación de una reserva. Reciba el evento de negocio resultante y encuentre sus diagnósticos. `/me` y una prueba sintética por sí solos no verifican la integración de negocio. Cuando ya no necesite la clave temporal de aceptación, elija **Revoke** en la consola y confirme. Repita la solicitud `/me` con esa clave y verifique que la autenticación falle. No revoque una clave que otro cliente siga usando. ## Si tiene problemas | Lo que ve | Qué revisar | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | No hay apps aprobadas | El correo invitado, la organización seleccionada y la propiedad/aprobación de la app por parte de Maple | | No hay accesos o la lista de locales está vacía | Los accesos a locales por entorno y `locations:read` en la clave | | No hay solicitudes recientes | Su ID de respuesta/solicitud, los filtros, la retención de 7 días y que llamó con una clave de esta app y de este entorno | | Historial no disponible | Reintente la lectura del historial más tarde; la administración de claves y webhooks es independiente | | Endpoint deshabilitado | Revise su configuración y su historial de fallas antes de volver a habilitarlo | | App suspendida | Contacte a Maple; crear otra clave no evita el estado de la app | | Entorno equivocado | Haga coincidir el panel, la URL base de la API y la credencial; el sandbox no activa producción | ## Continúe con su integración - [Tome reservas](https://docs.maple.inc/es/developer-api/guides/take-bookings.md): Lea el perfil de reservas, busque disponibilidad, bloquee un horario y cree o cambie reservas. - [Reciba y decida pedidos](https://docs.maple.inc/es/developer-api/guides/receive-orders.md): Conecte un local autorizado y gestione las notificaciones y decisiones de pedidos. - [Publique un menú](https://docs.maple.inc/es/developer-api/guides/publish-menu.md): Publique el catálogo para una integración de pedidos/POS aprobada. - [Acceso a producción](https://docs.maple.inc/es/developer-api/concepts/environments.md): Revise la aprobación, las credenciales, los accesos y la configuración de endpoints, todos independientes, que se necesitan para salir en vivo.