Primeros pasos

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). 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. 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: https://docs.maple.inc/llms.txt

The quickstart: https://docs.maple.inc/developer-api/quickstart

The OpenAPI spec, which is the source of truth for every endpoint and field: https://docs.maple.inc/openapi/developer-api.json

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 https://docs.maple.inc/developer-api/concepts/feedback 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.

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.
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:
Terminal window
```
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.
Verifique su identidad
Ejecute el comando /me copiado desde Getting started, o use:
Terminal window
```
curl --include "$MAPLE_BASE/me" \
  -H "Authorization: Bearer $MAPLE_KEY"
```
```
{
  "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.
Revise sus locales
Granted locations muestra los accesos configurados para esta app. Para leer locales mediante la API, use una clave con locations:read:
Terminal window
```
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 para conectar el local autorizado. Para reservas, lea el perfil de reservas y la guía de reservas; no cree una conexión de receptor de pedidos solo para probar reservas.
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 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.
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 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.
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