> ## 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](/es/developer-api/concepts/environments)). 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.
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](https://docs.maple.inc/llms.txt) (every page is available as Markdown at the page URL plus `.md`)
* The quickstart: [https://docs.maple.inc/developer-api/quickstart.md](https://docs.maple.inc/developer-api/quickstart.md)
* The OpenAPI spec, which is the source of truth for every endpoint and field: [https://docs.maple.inc/openapi/developer-api.json](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.md](https://docs.maple.inc/developer-api/concepts/feedback.md) 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.
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.
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 theme={null}
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.
Ejecute el comando **/me** copiado desde **Getting started**, o use:
```bash theme={null}
curl --include "$MAPLE_BASE/me" \
-H "Authorization: Bearer $MAPLE_KEY"
```
```json Response theme={null}
{
"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.
**Granted locations** muestra los accesos configurados para esta app. Para leer locales mediante la API, use una clave con `locations:read`:
```bash theme={null}
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](/es/developer-api/guides/receive-orders) para conectar el local autorizado. Para reservas, lea el [perfil de reservas y la guía de reservas](/es/developer-api/guides/take-bookings); no cree una conexión de receptor de pedidos solo para probar reservas.
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](/es/developer-api/concepts/webhooks) 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.
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](/es/developer-api/concepts/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.
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
Lea el perfil de reservas, busque disponibilidad, bloquee un horario y cree o cambie reservas.
Conecte un local autorizado y gestione las notificaciones y decisiones de pedidos.
Publique el catálogo para una integración de pedidos/POS aprobada.
Revise la aprobación, las credenciales, los accesos y la configuración de endpoints, todos independientes, que se necesitan para salir en vivo.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.