Referencia de la API

Usá esta referencia para implementar la API pública v1. Base URL: https://api.turnito.app/api/public/v1/. Todas las requests requieren Authorization: Bearer tk_live_… y, si llevan body, Content-Type: application/json.

Formatear requests y respuestas

Tema	Regla
Fechas de turno	`date` = `YYYY-MM-DD`, `time` = `HH:MM` (24 h), en la zona horaria de la agenda
Timestamps de respuesta	ISO 8601 UTC (`2026-05-26T10:00:00Z`)
Agenda	`uuid` corto (slug), ej. `"demo"`
Cliente / servicio / cobro	UUID estándar
Turno	`cancel_id` (string) para consultar, reprogramar o cancelar
Listas	`page` (default 1), `page_size` (default 50, máx. 200), salvo agendas y booktypes

Estado de un turno (`appointment.status`)

Valor	Significado
`confirmed`	Turno activo
`pending_payment`	Esperando que el cliente complete el pago
`cancelled`	Cancelado

Elegir un endpoint

Salud y agendas

Método	Path	Para qué
`GET`	`/health`	Smoke test de conectividad
`GET`	`/agendas`	Listar agendas de la cuenta
`GET`	`/agendas/{agenda_uuid}`	Detalle de una agenda
`GET`	`/agendas/{agenda_uuid}/booktypes`	Servicios / tipos de turno
`GET`	`/agendas/{agenda_uuid}/payment_methods`	Métodos de pago activos (opcional: `booktype_uuid`, `coupon_code`)
`GET`	`/agendas/{agenda_uuid}/availability`	Horarios libres (`date` obligatorio; opcional `booktype_uuid`)

Turnos

Método	Path	Para qué
`GET`	`/agendas/{agenda_uuid}/appointments`	Listar turnos (filtros: `from`, `to`, `status`, `client_uuid`, …)
`GET`	`/appointments/{cancel_id}`	Detalle de un turno
`POST`	`/agendas/{agenda_uuid}/appointments`	Crear turno
`PATCH`	`/appointments/{cancel_id}/reschedule`	Reprogramar
`POST`	`/appointments/{cancel_id}/cancel`	Cancelar

Clientes y cobros

Método	Path	Para qué
`GET`	`/clients`	Buscar / listar clientes (`search`, paginación)
`GET`	`/clients/{client_uuid}`	Detalle de un cliente
`GET`	`/payments`	Listar cobros (`status`, `from`, `to`, …)
`GET`	`/payments/{payment_uuid}`	Detalle de un cobro

Crear un turno — campos útiles

Body típico de POST /agendas/{agenda_uuid}/appointments:

Campo	Obligatorio	Notas
`date`, `time`	Sí	Día y hora del turno
`client`	Sí	`name` + `email` y/o `phone`, o `uuid` de un cliente existente
`modality`	Según agenda	`presencial`, `virtual` o la que permita la agenda
`booktype_uuid`	Si hay múltiples servicios	UUID del servicio
`require_payment`	No	`false` para confirmar sin pasar por el checkout
`payment_method_uuid`	No	Elegir método concreto

Si hay cobro, la respuesta puede incluir appointment.payment.url (link para que pague el cliente) y appointment.payment.uuid.

Manejar errores

Formato unificado:

{
  "error": {
    "code": "validation_error",
    "message": "Mensaje legible",
    "details": {},
    "request_id": "req_..."
  }
}

HTTP	Situación típica
`401`	Token inválido, vencido o revocado
`404`	Recurso inexistente o de otra cuenta
`409`	Conflicto de negocio (horario ocupado, etc.)
`422` / `400`	Validación de campos
`429`	Rate limit; respetá `Retry-After`

Al escribir a soporte, incluí el request_id y nunca el token.

Implementar flujos comunes

Agendar consultando disponibilidad

curl -s -H "Authorization: Bearer $TURNITO_API_TOKEN" \
  "https://api.turnito.app/api/public/v1/agendas/AGENDA_UUID/availability?date=2026-06-10"

curl -s -X POST \
  -H "Authorization: Bearer $TURNITO_API_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.turnito.app/api/public/v1/agendas/AGENDA_UUID/appointments \
  -d '{
    "date": "2026-06-10",
    "time": "14:30",
    "client": {
      "name": "Juan Pérez",
      "email": "[email protected]",
      "phone": "+5491155555555"
    },
    "modality": "presencial"
  }'

Agendar a un cliente existente

curl -s -H "Authorization: Bearer $TURNITO_API_TOKEN" \
  "https://api.turnito.app/api/public/v1/[email protected]"

Usá el uuid del resultado en "client": { "uuid": "..." } al crear el turno.

Agendar con link de pago

Creá el turno sin require_payment: false. Si la agenda cobra, la respuesta trae appointment.payment.url: enviáselo al cliente. Consultá el cobro con GET /payments/{uuid}.

Cancelar

curl -s -X POST \
  -H "Authorization: Bearer $TURNITO_API_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.turnito.app/api/public/v1/appointments/CANCEL_ID/cancel \
  -d '{ "reason": "Cliente avisó", "skip_refund": false }'

Si el turno tenía pago y la agenda admite devolución, la respuesta incluye un objeto refund. Con "skip_refund": true cancelás sin reembolsar.

Reprogramar

curl -s -X PATCH \
  -H "Authorization: Bearer $TURNITO_API_TOKEN" \
  -H "Content-Type: application/json" \
  https://api.turnito.app/api/public/v1/appointments/CANCEL_ID/reschedule \
  -d '{ "date": "2026-06-12", "time": "11:00" }'

Changelog breve

Versión	Cambios
v1.1	`GET /payments`, `GET /payments/{uuid}`; `payment.uuid` en el turno
v1.0	Lectura de agendas/clientes/turnos; crear, reprogramar y cancelar

Para precargar datos en un iframe, no uses el token de la API: seguí Implementar el embed firmado.

Primeros pasos

Panel

Agendas

Reservas

Clientes

Presencia pública

Integraciones

Cobros

Notificaciones

Cuenta y soporte

API

Formatear requests y respuestas

Estado de un turno (`appointment.status`)

Elegir un endpoint

Salud y agendas

Turnos

Clientes y cobros

Crear un turno — campos útiles

Manejar errores

Implementar flujos comunes

Agendar consultando disponibilidad

Agendar a un cliente existente

Agendar con link de pago

Cancelar

Reprogramar

Changelog breve

​Formatear requests y respuestas

​Estado de un turno (appointment.status)

​Elegir un endpoint

​Salud y agendas

​Turnos

​Clientes y cobros

​Crear un turno — campos útiles

​Manejar errores

​Implementar flujos comunes

​Agendar consultando disponibilidad

​Agendar a un cliente existente

​Agendar con link de pago

​Cancelar

​Reprogramar

​Changelog breve

Formatear requests y respuestas

Estado de un turno (`appointment.status`)

Elegir un endpoint

Salud y agendas

Turnos

Clientes y cobros

Crear un turno — campos útiles

Manejar errores

Implementar flujos comunes

Agendar consultando disponibilidad

Agendar a un cliente existente

Agendar con link de pago

Cancelar

Reprogramar

Changelog breve