misturnos.ai

Documentación API

Guía completa para integrar MisTurnos en tus aplicaciones

Autenticación

Todas las requests a la API requieren autenticación con Bearer token

Incluye tu API key en el header Authorization de cada request:

Authorization: Bearer sk_live_YOUR_API_KEY

Importante:

Nunca expongas tu API key en código del lado del cliente. Usa variables de entorno y mantenla segura en tu backend.

Base URL

https://misturnos.ai/api/v1

Widgets Embebibles

Además de la API REST, ofrecemos widgets listos para usar que podés embeber en tu sitio web.

Ver documentación de widgets

Endpoints Disponibles

GET
/v1/availability

Obtiene los slots de disponibilidad para una fecha específica

Query Parameters:

dateYYYY-MM-DD (required)
location_idUUID (optional)
sub_location_idUUID (optional)
duration_minutesnumber (optional, default: 60)

Ejemplo de Request:

curl -X GET \
  'https://misturnos.ai/api/v1/availability?date=2025-01-20&duration_minutes=60' \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json'

Respuesta:

{
  "date": "2025-01-20",
  "location": {
    "id": "loc_123",
    "name": "Sede Principal"
  },
  "operating_hours": {
    "open_time": "09:00",
    "close_time": "21:00"
  },
  "slots": [
    {
      "start_time": "09:00",
      "end_time": "10:00",
      "available": true,
      "booking_id": null,
      "duration_minutes": 60
    },
    {
      "start_time": "10:00",
      "end_time": "11:00",
      "available": false,
      "booking_id": "bkg_456",
      "duration_minutes": 60
    }
  ],
  "total_slots": 12,
  "available_slots": 8
}
GET
/v1/bookings

Lista todas las reservas con filtros opcionales

Query Parameters (todos opcionales):

dateYYYY-MM-DD (filter by specific date)
start_dateYYYY-MM-DD (from date)
end_dateYYYY-MM-DD (to date)
statusconfirmed | pending | cancelled | completed
limitnumber (default: 50, max: 200)
offsetnumber (default: 0)

Ejemplo de Request:

curl -X GET \
  'https://misturnos.ai/api/v1/bookings?status=confirmed&limit=10' \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY'
POST
/v1/bookings

Crea una nueva reserva con validación automática de disponibilidad

Body (JSON):

location_idstring (required)
start_timeISO8601 datetime (required)
end_timeISO8601 datetime (required)
consumer_namestring (required)
consumer_phonestring (required)
consumer_emailstring (optional)

Ejemplo de Request:

curl -X POST \
  'https://misturnos.ai/api/v1/bookings' \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "location_id": "loc_123",
    "start_time": "2025-01-20T10:00:00Z",
    "end_time": "2025-01-20T11:00:00Z",
    "consumer_name": "Juan Pérez",
    "consumer_phone": "+5491112345678",
    "consumer_email": "juan@example.com",
    "notes": "Primera reserva"
  }'

Respuesta Exitosa (201):

{
  "booking": {
    "id": "bkg_789",
    "start_time": "2025-01-20T10:00:00Z",
    "end_time": "2025-01-20T11:00:00Z",
    "status": "confirmed",
    "consumer_name": "Juan Pérez",
    "consumer_phone": "+5491112345678",
    "consumer_email": "juan@example.com",
    "location": {
      "id": "loc_123",
      "name": "Sede Principal"
    },
    "created_at": "2025-01-15T14:30:00Z"
  }
}
PATCH
/v1/bookings/:id

Actualiza una reserva existente (reagendar, cambiar estado, etc.)

Ejemplo de Request:

curl -X PATCH \
  'https://misturnos.ai/api/v1/bookings/bkg_789' \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "start_time": "2025-01-20T14:00:00Z",
    "end_time": "2025-01-20T15:00:00Z",
    "notes": "Reagendado a las 14hs"
  }'
DELETE
/v1/bookings/:id

Cancela una reserva (soft delete - marca como cancelled)

Ejemplo de Request:

curl -X DELETE \
  'https://misturnos.ai/api/v1/bookings/bkg_789' \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY'
GET
/v1/availability-blocks

Obtiene bloques de disponibilidad (períodos donde no se permiten reservas)

Query Parameters:

  • date - Fecha (YYYY-MM-DD, opcional, default: hoy)
  • location_id - ID de la locación (opcional)
  • sub_location_id - ID de la sub-locación (opcional)

Ejemplo de Request:

curl 'https://misturnos.ai/api/v1/availability-blocks?date=2025-01-15' \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY'

Ejemplo de Response:

{
  "date": "2025-01-15",
  "blocks": [
    {
      "id": "blk_123",
      "location_id": "loc_456",
      "sub_location_id": "sub_789",
      "start_time": "2025-01-15T12:00:00Z",
      "end_time": "2025-01-15T13:00:00Z",
      "reason": "Mantenimiento",
      "location": { "id": "loc_456", "name": "Sede Centro" },
      "sub_location": { "id": "sub_789", "name": "Cancha 1" }
    }
  ],
  "total": 1,
  "filters": {
    "location_id": null,
    "sub_location_id": null
  }
}

Códigos de Error

401API key inválida o faltante
403No tienes permisos para este recurso (scope requerido faltante)
404Recurso no encontrado
409Conflicto - El slot ya está ocupado
429Rate limit excedido
500Error interno del servidor

Caso de Uso: Torneos Externos

Sistema para organizadores externos que necesitan reservar múltiples turnos bloqueados

Flujo Completo:

  1. Business owner crea bloqueo con "Tipo: Restringido" y asigna código (ej: TORNEO_PADEL_2025)
  2. Organizador del torneo consulta GET /v1/availability-blocks para ver bloques con tournament_key
  3. Organizador crea reservas enviando X-Tournament-Key en header
  4. Sistema valida la clave y permite reservar en horario bloqueado

1. Business owner crea bloqueo:

Desde dashboard → Bloqueos → Nuevo bloqueo:

  • Tipo: Restringido
  • Código de acceso: TORNEO_PADEL_2025
  • Fechas: 15-16 de marzo, 10:00 a 20:00
  • Cancha: Cancha 1

2. Consultar bloques con tournament_key:

curl -X GET \
  'https://misturnos.ai/api/v1/availability-blocks?date=2025-03-15' \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY'

Response:

{
  "date": "2025-03-15",
  "blocks": [
    {
      "id": "uuid...",
      "location_id": "uuid...",
      "sub_location_id": "uuid...",
      "start_time": "2025-03-15T10:00:00Z",
      "end_time": "2025-03-15T20:00:00Z",
      "reason": "Torneo Interclubes de Padel",
      "tournament_key": "TORNEO_PADEL_2025",
      "location": { "id": "...", "name": "Sede Central" },
      "sub_location": { "id": "...", "name": "Cancha 1" }
    }
  ],
  "total": 1
}

3. Crear reserva con tournament_key:

curl -X POST https://misturnos.ai/api/v1/bookings \
  -H 'Authorization: Bearer sk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'X-Tournament-Key: TORNEO_PADEL_2025' \
  -d '{
    "location_id": "uuid...",
    "sub_location_id": "uuid...",
    "start_time": "2025-03-15T14:00:00Z",
    "end_time": "2025-03-15T15:30:00Z",
    "consumer_name": "Juan Pérez vs Pedro Gómez",
    "consumer_phone": "+5491123456789",
    "notes": "Semifinal - Categoría A"
  }'

Respuestas según tournament_key:

Sin header X-Tournament-Key:
{
  "error": "Time slot is blocked for a tournament. Provide X-Tournament-Key header to book.",
  "tournament_required": true
}
Con clave incorrecta:
{ "error": "Invalid tournament key" }
Con clave correcta:
{ "booking": { "id": "...", "status": "confirmed", ... } }

Rate Limits

El límite de requests se configura por API key. Por defecto: 1000 requests/día. Se resetea a medianoche (UTC-3).

Mejores Prácticas

  • Usa HTTPS para todas las requests
  • Guarda tu API key en variables de entorno, nunca en código
  • Implementa retry logic con exponential backoff para errores 5xx
  • Valida conflictos de disponibilidad antes de crear reservas
  • Usa paginación (limit/offset) para listas largas de bookings
MisTurnos.ai - Gestión de Turnos + Directorio de Negocios