API de resbok (1.17.0)

• https://api.resbok.com/v1 — la dirección de la API desde el 1-oct-2026. Esta página se abre ahí mismo, sin token.
• https://mesas.masmesa.com/callcenter/v1 — la dirección anterior. Sigue funcionando igual (mismas rutas, mismos tokens, mismas respuestas): quien ya está conectado no tiene que cambiar nada. Las integraciones nuevas usan la primera.

• Etapa A: catálogo y disponibilidad.

• Etapa B: crear reservaciones con folio y consultarlas.

• Etapa C: modificar y cancelar (servicio a clientes).

• Etapa D: nivel alto: leer todas las reservaciones de resbok, de cualquier canal (solo lectura).

• Etapa E (pedido de CallMarket): turnos de reservación por día en la ficha; direccion.colonia con la colonia real y direccion.alcaldia nueva; nombres_alternos (también en la búsqueda q); GET /salud.

• Etapa E2 (pedido de CallMarket): cuando está cerrado, mensaje con el horario de reservaciones de ese día (o el siguiente día que abre), horario_del_dia y alternativas del siguiente día con reservaciones; promociones con vigente_desde y vigente_hasta.

• Etapa H1 ("Lucy hostess"): la ficha trae contacto (Instagram, Facebook, micrositio, Google Maps), fotos (principal, logo, galería), servicios (con texto para leer), calificacion, areas y aforo estimado.

• Etapa H2 ("Lucy hostess"): area_id opcional para consultar, reservar y modificar en un área (terraza, salón…); areas_con_lugar y ocupacion ("últimos lugares") en la disponibilidad; area en la reservación.

• Versión 1.8: la ficha trae contacto.pagina_masmesa y fotos.menu; contacto.micrositio solo con dominios que el lugar usa.

• Versión 1.9: jornada — el horario y la reservación dicen a qué noche pertenecen, porque los turnos cruzan la medianoche. Además, un restaurante con los turnos mal cargados ya no se ofrece como reservable.

• Versión 1.10: se puede preguntar por la noche (jornada) en vez de por el día del calendario, y el texto de la jornada habla siempre de esa noche.

• Versión 1.11: teléfonos de cualquier país, con pais o con su lada.

• Versión 1.12: segundo teléfono opcional, fecha de nacimiento validada y festejado.

• Versión 1.13: ocasión del catálogo, festejado guardado aparte, promociones y eventos reales de "Mi sitio".

• Versión 1.14: experiencias de "Mi sitio" (paquetes que se reservan como una mesa y se pagan en el lugar).

• Versión 1.15: el aviso (webhook) sale por todas las reservaciones de los restaurantes habilitados, de cualquier canal, con más datos (evento, canal, cliente, jornada).

• Versión 1.16: respuesta del cliente al seguimiento de asistencia (POST /reservaciones/{folio}/respuesta-cliente), marcado_por: "cliente" en los avisos y el motivo sin_dueno con lugares recomendados.

• Versión 1.17 (esta): la madrugada pertenece a la noche anterior también en la agenda, qr_url con el QR del folio, webhooks por integración y la dirección nueva https://api.resbok.com/v1.

• Dirección nueva: https://api.resbok.com/v1. La anterior sigue funcionando sin cambios.
• qr_url en las respuestas de reservación (POST /reservaciones, GET /reservaciones/{folio}, las listas y la agenda): liga pública a un PNG con el QR del folio. Se le puede mandar al cliente por WhatsApp; lo muestra en la puerta y la hostess lo escanea. Con ?descargar=1 el navegador lo guarda como archivo.
• Agenda por noche: GET /restaurantes/{id}/reservaciones?fecha=2026-09-25 devuelve toda la noche del 25, incluida su madrugada del 26, y ya no la madrugada del 25 (que es de la noche del 24). fecha y hora de cada reservación siguen siendo las del reloj; jornada dice a qué noche pertenece.
• Webhooks por integración: cada integración puede tener su propia URL de avisos, sus eventos y su secreto (ver Avisos (webhooks) más abajo).

• POST /reservaciones/{folio}/respuesta-cliente: lo que contestó el cliente ("sí fui" / "no fui") al día siguiente. Basta un "sí" del cliente o de la hostess para que cuente como asistencia.
• Si la hostess no marca "no llegó" en 48 h, la reservación cuenta como asistida (marcado_por: "sistema").
• Motivo sin_dueno en GET /disponibilidad: nadie ha reclamado la ficha de ese lugar; no se toma reservación ni solicitud y la respuesta trae hasta 3 recomendados de la misma zona que sí reservan.

• El aviso sale por cualquier reservación de un restaurante habilitado (portal, micrositio, libro, Google, otra integración), no solo por las que creó quien recibe el aviso.
• Campos nuevos en el aviso: nombre, apellido, telefono, correo, restaurante_id, jornada, origen, evento (nueva | cambio), canal, pais, telefono_internacional y, al marcar asistencia, marcado_por.

• Experiencias en la ficha: experiencias[] con título, resumen, precio_texto listo para leer ("$4,500 el paquete (hasta 8 personas)"), personas_texto, días (cada_semana), hora_desde/hora_hasta, proximas_fechas (14 días) y cupo_por_dia. El precio es solo informativo: se paga en el lugar, no se cobra en línea.
• Disponibilidad: experiencias que aplican esa noche (la 01:00 del sábado cuenta como el viernes).
• Reservar con experiencia: experiencia_id opcional en POST /reservaciones. Se revisa que aplique esa noche, a esa hora, para esas personas y que quede cupo; si no, 422 experiencia_no_aplica con mensaje para leer al cliente y motivo (dia, hora, personas, sin_cupo, no_disponible), y no se crea nada. Si aplica, la respuesta trae experiencia (id, titulo, total_estimado, se_paga_en_el_lugar) y la nota del restaurante empieza con "Experiencia: …". modo_prueba revisa lo mismo sin ocupar cupo.

• Ocasión del catálogo: ocasion_id al crear y al modificar (GET /ocasiones: 1 Reserva Casual, 2 Cumpleaños, 3 Aniversario, 4 Negocios, 5 Cita, 6 Salida con amigos, 7 Despedida, 8 Otra). El texto ocasion de siempre sigue funcionando y además se traduce al catálogo. La reservación trae ocasion ({id, nombre}) y festejado, guardados aparte de la nota; la nota sigue igual. Una ocasión que no existe → 422 en campos.ocasion_id.
• Promociones de cumpleaños al reservar: con la ocasión Cumpleaños, POST /reservaciones responde promociones_aplicables con las de cumpleaños del lugar que aplican ese día, para ofrecerlas. Solo informativo.
• Promociones reales: promociones[] de la ficha ahora son las que el lugar publica en "Mi sitio" (las mismas de su micrositio), con los campos nuevos tipo (dias | cumpleanos), dias y condiciones, y vigencia.tipo puede ser cumpleanos. Antes salían de las "experiencias" de resbok, que solo tenían datos de prueba: un lugar que no publica promociones en Mi sitio ahora trae la lista vacía. Los campos de precio y descuento siguen, en null, y prepago en false.
• Eventos: la ficha trae eventos (próximos 14 días, máximo 10) y GET /disponibilidad trae los eventos de esa noche, para decir "este viernes hay DJ".

• Segundo teléfono opcional: telefono_2 + pais_2 al crear (POST /reservaciones) y al modificar (PATCH /reservaciones/{folio}), con la misma regla que telefono + pais. Al modificar se puede mandar solo, y vacío o null lo borra. Inválido → 422 en campos.telefono_2 ("El segundo teléfono no es válido para el país indicado."); país que no existe → campos.pais_2. Con horario nuevo sin lugar no se cambia nada.
• Respuestas (reservación y agenda): cliente.telefono_2, cliente.pais_2 y cliente.telefono_2_internacional, null si no hay.
• fecha_nacimiento (ya existía) se guarda en la ficha del cliente del restaurante; ahora además no puede ser futura ni anterior a 1900 → 422 en campos.fecha_nacimiento.
• festejado opcional (máx. 128): de quién es el festejo si no es de quien reserva. Va a la nota que ve el restaurante como "Cumpleaños de: Luis" (o "Festejado: Luis" si la ocasion no es un cumpleaños). nombre_festejado sigue funcionando igual. Antes la nota decía "Festejado: Luis" también en cumpleaños. No se devuelve como campo: queda en nota, que el restaurante puede editar.
• Lo que ya mandan no cambia.

• Lo de siempre no cambia: telefono de 10 dígitos sin pais es de México, con los mismos mensajes de error.
• pais opcional (ISO de 2 letras: MX, US, ES…) al crear, consultar, modificar y cancelar, y en GET /reservaciones, GET /reservaciones/{folio} y GET /agenda/reservaciones. También se acepta el teléfono con su lada ("+1 212 555 1234", "+34 612 345 678"); la lada escrita manda sobre pais.
• Cada país con su largo válido (México 10 dígitos; EE. UU. y Canadá 10; España 9…). Número que no sirve para su país → 422 con "El teléfono no es válido para el país indicado."; país que no existe → 422 en campos.pais.
• Folio + teléfono identifica al cliente con número y país: los mismos 10 dígitos como número de México y como número de EE. UU. son clientes distintos. Si crearon la reservación con pais, consúltenla con el mismo pais (o con la lada).
• Respuestas: cliente.pais y cliente.telefono_internacional ("+525512345678", listo para marcar), junto a cliente.telefono, que sigue siendo el número nacional. En la agenda son null si el número guardado por otro canal no se reconoce.

• GET /disponibilidad acepta jornada=AAAA-MM-DD en lugar de fecha: es la noche a la que pertenece la hora, como la dice el cliente. jornada=2026-09-18&hora=02:00 ("el viernes a las 2 de la mañana") consulta el sábado 19 a las 02:00 y responde con la fecha real. Las dos juntas, o ninguna, responden 422 parametros_invalidos.

• El bloque jornada de la respuesta ahora habla de la noche a la que pertenece la hora consultada, con el horario de esa noche. Antes tomaba el día del calendario: preguntando por el sábado a las 02:00 decía "El sábado…", que confundía a quien había preguntado por el viernes. Si ya leen ese texto, ahora dice lo que esperaban.

• Aclaración (no cambia el comportamiento): la hora de cierre del turno se puede reservar. En un turno de 23:00 a 01:00, la 01:00 es válida; la primera que ya no entra es la 01:15.

• Motivo cerrado_por_el_lugar en GET /disponibilidad: el restaurante cerró sus reservaciones de ese día (evento, reservas solo en el local o cerrado). No trae alternativas y no debe ofrecerse como "lleno".

• disponibilidad: campo nuevo jornada (fecha, dia, ventanas, texto), con el horario dicho como lo entiende el cliente y listo para leerse por teléfono: "El viernes 18 de septiembre recibe reservaciones de 22:00 a 01:00. La 01:00 es de la madrugada del sábado y cuenta como la noche del viernes." Es del día que se consultó, y null cuando no hay horario que decir (ese día no abre, o el motivo no es cerrado).
• Cada ventana de horario_del_dia trae termina_al_dia_siguiente.
• Reservación: campo nuevo jornada (fecha, dia, es_madrugada, texto) con la noche a la que pertenece la mesa. fecha y hora siguen siendo las del calendario real; jornada.fecha es el día del turno, el mismo con que la reservación queda en el libro del restaurante. La madrugada (hasta las 05:45) pertenece a la noche anterior.
• Restaurantes con los turnos mal cargados: un lugar solo aparece como reservable en línea si su turno es coherente por dentro y tiene al menos una mesa activa. Los que no lo cumplen responden no_acepta_api y ya no devuelven horario, en vez de anunciar un rango que después rechazaban a cualquier hora.

• Ficha: contacto.pagina_masmesa (página del lugar en www.masmesa.com) y fotos.menu (fotos o ligas de la carta, las mismas del micrositio).
• contacto.micrositio ya no trae dominios que el restaurante dejó de usar (cuando su sitio web capturado apunta a otra parte).

• GET /disponibilidad: parámetro opcional area_id; campos nuevos area_id, areas_con_lugar y ocupacion.
• POST /reservaciones y PATCH /reservaciones/{folio}: campo opcional area_id. Un área que no es del restaurante → 422 area_invalida.
• Reservación: campo nuevo area (área de la mesa asignada).

• Ficha: campos nuevos contacto, fotos, servicios, calificacion, areas, aforo.

• disponibilidad: campo nuevo horario_del_dia (vacío salvo motivo = cerrado). El mensaje de cerrado ahora agrega el horario del día; si su código compara el texto exacto, cámbienlo por motivo.
• promociones[]: campos nuevos vigente_desde y vigente_hasta.

• direccion.colonia ahora es la colonia como la dice la gente (Polanco, Condesa). Antes traía la alcaldía, que ahora viene en direccion.alcaldia. Puede venir null si resbok todavía no la captura para un lugar nuevo.
• El filtro colonia busca en la colonia y en la alcaldía.
• politicas.tolerancia ya no viene null cuando la tolerancia es "Ilimitado": trae el texto para leerlo.
• Campos nuevos (no rompen): nombres_alternos, turnos, direccion.alcaldia y en reglas: tolerancia_ilimitada, mesas_maximo, personas_de_pie_maximo, intervalo_minutos (todo el formulario de configuración del dashboard).

• Token fijo por cliente en la cabecera Authorization: Bearer <token> (también se acepta X-API-Key: <token>).
• Solo HTTPS.
• Límite de peticiones por minuto por token; al pasarlo responde 429. Muchos tokens inválidos desde la misma IP también dan 429 (un token válido siempre pasa).
• Cada token tiene permisos (ver catálogo, ver disponibilidad, crear, consultar, modificar, cancelar, ver todas las reservas). Sin el permiso de una operación responde 403. resbok entrega un token con todos los permisos; el callcenter decide qué extensión o área usa cada operación (por ejemplo, reservar en una y dar seguimiento en otra). Para modificar o cancelar siempre se confirma con el folio y el teléfono de la reservación.

• JSON en UTF-8.
• Fechas AAAA-MM-DD y horas HH:MM en 24 h, en la zona horaria del restaurante (zona_horaria).
• Las horas de reservación van en cuartos de hora (:00, :15, :30, :45).

Todos los errores responden {"error": "<código>", "mensaje": "<texto>"}. El mensaje está escrito para leerse tal cual al cliente.

• Catálogo siempre al día: aparecen todos los restaurantes activos en resbok, los mismos del portal. Uno nuevo aparece solo; uno dado de baja deja de aparecer y su ficha responde 404. Sincronicen GET /restaurantes periódicamente (por ejemplo cada hora) y usen actualizado_en para saber qué cambió.
• Buscar por teléfono (GET /reservaciones?telefono=, GET /agenda/reservaciones?telefono=) lleva el teléfono en la URL: no la guarden en bitácoras de su lado.
• acepta_reservas_por_api = true: se reserva en línea igual que en el portal. false: el lugar no reserva en línea. Se registra una solicitud pendiente, pero antes se revisan personas y anticipación: un grupo fuera de rango o una hora pasada se rechaza igual.
• Mínimo y máximo de personas, anticipación mínima y porcentaje de asistencia salen de la configuración de cada restaurante en resbok; si el restaurante la cambia, la API lo refleja de inmediato.

Todos los restaurantes activos de resbok (como el portal) y su ficha técnica completa.

Si hay lugar en un día, hora y número de personas, con alternativas.

Crear, consultar, modificar y cancelar las reservaciones creadas por el mismo token.

Todas las reservaciones de resbok, de cualquier canal (solo lectura, permiso reservas.leer_todas).