Skip to main content
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:
Use la credencial que corresponda al host (mpk_test_… en el sandbox, mpk_live_… en producción). Consulte Entornos.

​
Autenticación

Envíe una credencial Bearer en cada solicitud:
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.

​
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:
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: Solicite GET /v1/orders?since=<checkpoint>&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 para un pedido activo, o el registro de eventos y la repetición 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.

​
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.