Agenda citas en ReservaYa desde tu propio sistema

Resumen

1. Obtener tu token

Cada negocio en ReservaYa tiene su propio token — no hay credenciales compartidas entre negocios. Solo puede existir un token activo a la vez por negocio.

1. Entra al panel de administración Inicia sesión como administrador del negocio que quieres conectar.
2. Ve a Configuración → API externa Es la última sección del menú de Configuración.
3. Genera un token nuevo Se muestra una sola vez — cópialo y guárdalo en tu sistema antes de salir de la página.
4. Guárdalo como secreto Trátalo como una contraseña: quien lo tenga puede crear y cancelar citas de ese negocio.

2. Autenticación

Cada solicitud debe incluir el token en el encabezado Authorization. No hay autenticación por cookie ni por parámetro en la URL.

Authorization: Bearer tu_token_aqui
Content-Type: application/json

El token identifica al negocio automáticamente — nunca envíes un identificador de negocio aparte. Todo lo que crees o consultes queda limitado a los datos de ese negocio.

Lista los servicios activos disponibles para reservar.

curl https://ry.51x.mx/api/v1/services \
  -H "Authorization: Bearer tu_token_aqui"

{
  "data": [
    {
      "id": 11,
      "name": "Corte de cabello",
      "slug": "corte-de-cabello",
      "description": "Corte, lavado y peinado",
      "duration_minutes": 30,
      "price": "250.00"
    }
  ]
}

Usa el slug del servicio que te interese para consultar sus horarios en el siguiente endpoint.

Devuelve los horarios libres de un servicio para un día específico.

curl "https://ry.51x.mx/api/v1/services/corte-de-cabello/slots?date=2026-08-10" \
  -H "Authorization: Bearer tu_token_aqui"

{
  "date": "2026-08-10",
  "slots": [
    { "start": "2026-08-10T09:00:00-06:00", "end": "2026-08-10T09:30:00-06:00", "label": "09:00" },
    { "start": "2026-08-10T09:30:00-06:00", "end": "2026-08-10T10:00:00-06:00", "label": "09:30" }
  ]
}

Un arreglo vacío significa que no hay horarios libres ese día — no es un error.

Crea una cita confirmada. El cliente recibe su correo de confirmación igual que si hubiera reservado desde el sitio.

curl -X POST https://ry.51x.mx/api/v1/appointments \
  -H "Authorization: Bearer tu_token_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "service_id": 11,
    "starts_at": "2026-08-10T09:00:00-06:00",
    "customer_name": "Ana López",
    "customer_email": "ana@example.com",
    "customer_phone": "5512345678"
  }'

{
  "data": {
    "lookup_code": "40821",
    "status": "confirmed",
    "service": { "id": 11, "name": "Corte de cabello", "slug": "corte-de-cabello" },
    "customer_name": "Ana López",
    "customer_email": "ana@example.com",
    "customer_phone": "5512345678",
    "starts_at": "2026-08-10T09:00:00-06:00",
    "ends_at": "2026-08-10T09:30:00-06:00"
  }
}

Guarda el lookup_code — es lo que usarás para consultar o cancelar esta cita después.

{
  "message": "Este horario ya no está disponible. Por favor selecciona otro.",
  "errors": { "starts_at": ["Este horario ya no está disponible. Por favor selecciona otro."] }
}

Esto pasa si el horario se ocupó entre que consultaste /slots y enviaste la solicitud. Vuelve a consultar los horarios disponibles y reintenta.

Consulta el estado actual de una cita por su código.

curl https://ry.51x.mx/api/v1/appointments/40821 \
  -H "Authorization: Bearer tu_token_aqui"

{
  "data": {
    "lookup_code": "40821",
    "status": "confirmed",
    "service": { "id": 11, "name": "Corte de cabello", "slug": "corte-de-cabello" },
    "customer_name": "Ana López",
    "customer_email": "ana@example.com",
    "customer_phone": "5512345678",
    "starts_at": "2026-08-10T09:00:00-06:00",
    "ends_at": "2026-08-10T09:30:00-06:00"
  }
}

Cancela una cita. El cliente recibe el mismo correo de cancelación que si la hubiera cancelado él mismo.

curl -X POST https://ry.51x.mx/api/v1/appointments/40821/cancel \
  -H "Authorization: Bearer tu_token_aqui"

{
  "data": { "lookup_code": "40821", "status": "cancelled", "…" }
}

Cancelar una cita que ya estaba cancelada no genera error — simplemente devuelve su estado actual.

Lista los recordatorios programados o ya enviados de una cita — útil si tu sistema quiere saber cuándo y por qué canal se le avisará al cliente.

curl https://ry.51x.mx/api/v1/appointments/40821/reminders \
  -H "Authorization: Bearer tu_token_aqui"

{
  "data": [
    {
      "channel": "correo",
      "time_unit": "dia",
      "time_value": 1,
      "status": "programado",
      "execute_at": "2026-08-09T09:00:00-06:00",
      "sent_at": null
    }
  ]
}

status es programado, enviado o cancelado (esto último si la cita se canceló antes de que el recordatorio se enviara). Un arreglo vacío significa que el servicio de esa cita no tiene recordatorios configurados.

Errores

Todos los errores devuelven JSON con al menos un campo message.

Límites y buenas prácticas

• 60 solicitudes por minuto por token — suficiente para un flujo normal de reservas, no está pensado para sincronizaciones masivas continuas.
• Consulta /slots justo antes de crear la cita — la disponibilidad puede cambiar entre una consulta y otra.
• Guarda el lookup_code de cada cita creada; es el único identificador que necesitas para consultarla o cancelarla después.
• Si rotas el token, actualízalo en tu sistema antes de que termine de propagarse — el anterior deja de funcionar de inmediato.