> ## Documentation Index
> Fetch the complete documentation index at: https://help.turnito.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia de la API

> Endpoints, convenciones, errores y recetas de la API pública v1.

Complemento de [API pública](/api/index). 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`.

## Convenciones

| 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                                 |

## Endpoints

### 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`.

## Errores

Formato unificado:

```json theme={null}
{
  "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.

## Recetas

### Agendar consultando disponibilidad

```bash theme={null}
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": "juan@example.com",
      "phone": "+5491155555555"
    },
    "modality": "presencial"
  }'
```

### Agendar a un cliente existente

```bash theme={null}
curl -s -H "Authorization: Bearer $TURNITO_API_TOKEN" \
  "https://api.turnito.app/api/public/v1/clients?search=juan@example.com"
```

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

```bash theme={null}
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

```bash theme={null}
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   |

## Páginas relacionadas

* [API pública — overview](/api/index)
* [Panel de cobros](/cobros/index)
* [Soporte](mailto:ayuda@turnito.app)