Configure las reservas

​

Requisitos previos

• Su app tiene el permiso sobre el local.
• Publicar requiere bookings:configure; leer requiere bookings:read.
• Maple habilitó el indicador de despliegue bookings-public-api del local.
• El local tiene una conexión nativa de Maple, o todavía no tiene ninguna conexión de reservas. Los locales administrados por un proveedor responden 422 capability_unsupported.

​

Publique una configuración

{
  "timeZone": "America/New_York",
  "currency": "USD",
  "areas": [
    {
      "poolId": "dining",
      "name": "Dining Room",
      "kind": "seat",
      "units": [
        { "unitId": "t1", "seats": { "min": 1, "max": 2 } },
        { "unitId": "t2", "seats": { "min": 1, "max": 4 }, "tags": ["window"] }
      ],
      "combinations": [
        { "unitIds": ["t1", "t2"], "seats": { "min": 3, "max": 6 } }
      ]
    }
  ],
  "turnBands": [
    { "minGuests": 1, "maxGuests": 2, "minutes": 90 },
    { "minGuests": 3, "maxGuests": 6, "minutes": 120 }
  ],
  "shifts": [
    { "day": "FRI", "start": "17:00", "end": "23:00" },
    { "day": "SAT", "start": "12:00", "end": "23:00" }
  ],
  "pacing": { "intervalMinutes": 15, "maxCovers": 12, "enforcement": "hard" },
  "bookingPolicy": {
    "minLeadMinutes": 60,
    "maxHorizonDays": 60,
    "slotAlignment": "quarter_hourly",
    "autoConfirm": true
  },
  "cancellationPolicy": {
    "requiresCardOnFile": false,
    "tiers": [],
    "rescheduleCutoffHours": 2,
    "policyText": "Please contact the venue for late changes."
  }
}

​

Publique sin sobrescribir lo del establecimiento

{ "...": "the whole configuration", "expected_revision": "<revision from your last read>" }

​

Reglas de publicación

• El documento reemplaza la configuración de reservas definida por el establecimiento, no su menú ni otros recursos y políticas del catálogo no relacionados. Las publicaciones posteriores del proveedor o del menú también conservan esa configuración de reservas.
• Volver a publicar una configuración idéntica no crea otra versión. La configuración no tiene un campo idempotency_key.
• Los cambios en los tiempos de rotación o en las políticas rigen para las nuevas cotizaciones de disponibilidad. Las reservas existentes conservan los términos con los que se fijaron.
• La moneda debe coincidir con la de un catálogo existente. Una primera configuración establece la moneda cuando no hay catálogo.
• Las horas son HH:MM en la hora local del establecimiento; el fin de un turno debe ser posterior a su inicio. Divida los horarios que cruzan la medianoche entre días.
• Los tramos de rotación deben estar ordenados y sin traslapes. Las combinaciones deben nombrar unidades distintas de su propia área.
• Todas las áreas se pueden reservar. La disponibilidad prueba primero la primera área de areas y luego las demás en orden de poolId (el orden en que las devuelve una lectura), y sienta al grupo en la primera que tenga una mesa o combinación libre en la que quepa; una reserva se queda en el área donde se sentó. Los turnos y las fechas de cierre aplican a todo el local.
• Los campos desconocidos, las zonas o fechas no válidas y los límites no válidos se rechazan. Las respuestas de validación 400 identifican el dato no válido. 422 configuration_rejected significa que el documento no se puede aplicar al catálogo.
• Una lectura antes de que exista una configuración responde 404.

​

Fechas bloqueadas

PUT /v1/locations/{locationId}/booking_blackouts

{
  "blackout_dates": [
    { "start_date": "2026-12-24", "end_date": "2026-12-26", "reason": "Holidays" },
    { "start_date": "2026-10-10", "end_date": "2026-10-10", "start_time": "18:00", "end_time": "22:00" }
  ],
  "expected_revision": "<blackout_dates_revision from the booking profile>"
}

• El cuerpo es la lista completa: los rangos que omita se eliminan, y [] los borra todos. El establecimiento edita la misma lista en su panel, así que lea blackout_dates y blackout_dates_revision del perfil, edite y envíe esa revisión como expected_revision. Si la lista cambió desde que la leyó, la escritura responde 409 stale_blackout_dates y no cambia nada: léala de nuevo y vuelva a aplicar su edición. Sin expected_revision, la escritura reemplaza lo que haya.
• Las fechas están en la hora local del establecimiento e inclusivas. Un rango sin horas bloquea días completos; start_time aplica al primer día y end_time al último. Máximo 100 rangos, con notas de hasta 200 caracteres.
• Los rangos no válidos (una fecha que no existe, un fin anterior al inicio, una hora mal formada) responden 400 invalid_blackout_dates y no cambian nada.
• La disponibilidad omite los espacios dentro de una fecha bloqueada; los locales nativos también retienen las sentadas que invadirían una. Una cotización tomada antes de agregar una fecha bloqueada se rechaza al retenerla o reservarla: 409 slot_unavailable en los locales nativos y 422 date_blocked en los administrados por un proveedor. Las reservas existentes dentro de una nueva fecha bloqueada no se cancelan, ni tampoco una reserva de un local administrado por un proveedor que ya esté en curso cuando se guarda la fecha bloqueada.
• Una fecha bloqueada detiene las reservas, no la recepción: los clientes sin reserva (POST /v1/locations/{locationId}/walk_ins) y los grupos de la lista de espera que se van a sentar siguen funcionando dentro de una, según la disponibilidad normal de mesas.
• En un local administrado por un proveedor, los canales propios del proveedor (como el sitio web de OpenTable) no ven la lista de Maple; el establecimiento también debe bloquear las fechas allí.

​

Aprovisione un sandbox de reservas