> ## 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. # Convenciones > URL base, convenciones de recursos, IDs, dinero y comportamiento de las listas comunes a todos los endpoints de la Developer API. La Developer API es una API REST con JSON. Todos los endpoints de esta referencia están agrupados en la barra lateral por recurso: auth, locations, connections, menu, orders y webhooks. Esta página cubre las convenciones que todos comparten; las páginas de conceptos enlazadas profundizan más. ## URL base Cada entorno tiene su propio host, ambos servidos bajo el prefijo `/v1`: ``` https://api.staging.maple.inc/v1 # Sandbox — development and testing https://api.maple.inc/v1 # Production — live traffic ``` Use la credencial que corresponda al host (`mpk_test_…` en el sandbox, `mpk_live_…` en producción). Consulte [Entornos](/es/developer-api/concepts/environments). ## Autenticación Envíe una credencial `Bearer` en cada solicitud: ```http theme={null} Authorization: Bearer mpk_test_… ``` Envíe su clave de API (`mpk_test_…` para el sandbox, `mpk_live_…` para producción) como el token bearer. `GET /v1/me` devuelve la aplicación, el entorno y los alcances (scopes) de cualquier clave. Encontrará todos los detalles en [Autenticación](/es/developer-api/concepts/authentication). ## Convenciones de recursos * **Los IDs opacos** llevan un prefijo de tipo: `str_` (local), `ord_` (pedido), `dws_` (suscripción de webhook), `evt_` (evento), etc. Trátelos como cadenas opacas. * **El dinero se expresa en centavos de USD enteros.** `450` significa \$4.50. Nunca interprete los montos como números de punto flotante. Los códigos de moneda siempre van en mayúsculas ISO‑4217 (`USD`). * **Formato de los campos.** Los payloads de menú usan camelCase (`externalId`, `minSelections`, `modifierGroups`); los payloads de pedidos y webhooks usan snake\_case (`fulfillment_type`, `menu_entity_id`, `payment_status`). El `menu_entity_id` de un artículo del pedido contiene el `externalId` que usted publicó para ese objeto del menú. * **Las marcas de tiempo** de eventos y pedidos están en segundos Unix (el campo `created`). * **Tipado de objetos.** La mayoría de los recursos incluyen un campo `object` (`order`, `location`, `event`, …) para distinguirlos. ## Listas Los endpoints de listas devuelven un sobre con un `object` de valor `list` y un arreglo `data`: ```json theme={null} { "object": "list", "data": [ /* … */ ] } ``` Las listas devuelven una **ventana acotada** con un indicador `has_more` en lugar de un total: * `GET /v1/orders` devuelve hasta 100 pedidos de sus locales conectados. De forma predeterminada, los más recientes primero; consulte los parámetros de puesta al día más abajo. * `GET /v1/webhook_events` devuelve hasta 50 eventos, los más recientes primero. * `GET /v1/locations` y `GET /v1/webhook_subscriptions` devuelven el conjunto completo de su aplicación. ### Recuperar pedidos después de una interrupción `GET /v1/orders` acepta tres parámetros de consulta opcionales, pensados para conciliar un atraso: | Parámetro | Significado | | - | - | | `since` | Punto de control ISO 8601 (UTC), exclusivo. Con `since`, los resultados van **del más antiguo al más reciente** para que pueda avanzar sin omitir pedidos que comparten una marca de tiempo. | | `starting_after` | El último ID de pedido (`ord_…`) de la página anterior. Requiere `since`, y el pedido debe pertenecer a su aplicación. | | `limit` | Tamaño de página, de 1 a 100. El valor predeterminado es 100. | Solicite `GET /v1/orders?since=&limit=100` y luego repita con `starting_after` igual al último ID de pedido devuelto mientras `has_more` sea verdadero. No hay filtro por `location_id`; filtre en el cliente por `location_id`. Para que Maple vuelva a entregar un webhook en lugar de obtener el pedido usted mismo, use [`POST /v1/orders/{orderId}/resend`](/es/developer-api/guides/receive-orders) para un pedido activo, o el [registro de eventos y la repetición](/es/developer-api/concepts/webhooks) cuando importe la identidad del evento original. ### Listado de reservas `GET /v1/bookings` lee las reservas de los locales con permiso, y se puede acotar con `location_id`. Use `start`/`end` como instantes ISO-8601 que abarquen como máximo 31 días; sin ninguno, la ventana son los próximos siete días. Como alternativa, `updated_since` recupera las actualizaciones de la más antigua a la más reciente y no se puede combinar con una ventana de tiempo. Para encontrar la reserva sobre la que un huésped llama o escribe, pase `location_id` con `phone`, `confirmation_code` o ambos. El teléfono se normaliza primero, por lo que `(415) 555-0142` y `+14155550142` corresponden al mismo huésped. Sin una ventana, la búsqueda encuentra reservas de cualquier fecha, ordenadas por inicio del horario; agregue `start`/`end` para limitarla a los próximos días. En un local administrado por un proveedor, una búsqueda con `phone` también consulta al proveedor, así que se encuentran las reservas hechas directamente allí; una búsqueda solo por código cubre las que Maple ya conoce. Una búsqueda sin `location_id` devuelve `400 location_required`, y un teléfono inutilizable devuelve `400 invalid_phone`. Pagine con `limit` (de 1 a 100, 20 de forma predeterminada) y use el `next_cursor` opaco de la página anterior como `starting_after`. Mantenga los filtros sin cambios entre páginas. Una ventana predeterminada permanece fija a lo largo de sus páginas. Para sondeos con punto de control, solape unos segundos y elimine duplicados por `id` y `version` de la reserva. Las reservas usan IDs `bkg_…` y las entradas de la lista de espera `bkw_…`; todas las retenciones de socios usan `bkh_…`, incluidas las administradas por proveedores. Los tokens de bloqueo del proveedor no se exponen. Los recursos de reservas usan snake\_case; la configuración de reservas usa camelCase. `created` está en segundos Unix; `starts_at`, `updated_at`, `expires_at`, `published_at` y `as_of` del piso son instantes ISO-8601. Los límites de la búsqueda de disponibilidad son, en cambio, valores de hora local del establecimiento. ## Errores Los errores usan códigos de estado HTTP estándar con un cuerpo JSON que incluye un `_tag` estable y un `message` legible. Base su lógica en el tag, no en el mensaje. El catálogo completo está en [Errores](/es/developer-api/concepts/errors). ## Límites de frecuencia Las reservas tienen por defecto 60 búsquedas de disponibilidad por minuto y 300 otras solicitudes de reservas por minuto (incluidas las de lista de espera), de forma independiente por aplicación y entorno en todos los locales. Cada aplicación también tiene un límite atómico de diez retenciones activas o pendientes por local. Un `429` incluye `Retry-After` y `retry_after` en el JSON, en segundos. Estos presupuestos de reservas no se aplican a las rutas existentes de pedidos y menús; las solicitudes de tokens OAuth tienen su propio límite. Responda a los webhooks de forma asíncrona, evite los ciclos de sondeo intensivos y conserve la clave de idempotencia original al reintentar escrituras. Consulte [Tomar reservas](/es/developer-api/guides/take-bookings). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.