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

# API pública

> Integrá Turnito con bots, CRMs o sistemas propios: qué hace la API, cómo pedir acceso y arrancar.

La API pública de Turnito te permite consultar agendas, disponibilidad, clientes y turnos, y también agendar, reprogramar y cancelar desde un sistema externo (bot, CRM, app propia, automatización).

Opera **en nombre de tu cuenta**, con las mismas reglas de dueño que cuando agendás desde el panel: no aplican los límites pensados solo para el cliente final (anticipación de cancelación, máximo de reprogramaciones, etc.).

## Para quién es

* Tenés un bot de WhatsApp, Telegram u otro canal que agenda turnos.
* Querés sincronizar Turnito con un CRM o un sistema interno.
* Necesitás listar disponibilidad o cobros sin entrar al panel.

Si solo usás el panel y el link de reserva, **no necesitás la API**.

## Qué podés hacer (v1)

| Acción                                                  | Sí       |
| ------------------------------------------------------- | -------- |
| Listar agendas, servicios (booktypes) y métodos de pago | Sí       |
| Consultar disponibilidad de un día                      | Sí       |
| Listar y buscar clientes                                | Sí       |
| Crear, consultar, reprogramar y cancelar turnos         | Sí       |
| Listar y consultar cobros                               | Sí       |
| Crear o editar agendas / servicios / precios            | No       |
| Reservas recurrentes                                    | No       |
| Webhooks (avisos push hacia tu sistema)                 | No (aún) |

## Cómo obtener acceso

Hoy el token **no se genera desde el panel**. Pedilo por email a [ayuda@turnito.app](mailto:ayuda@turnito.app) indicando:

* El email de tu cuenta de Turnito.
* Para qué lo vas a usar (bot, CRM, etc.).

Te van a emitir un token con formato `tk_live_…`. **Se muestra una sola vez**: guardalo en un secret manager o variable de entorno. Si lo perdés, hay que emitir uno nuevo.

<Danger>
  El token da acceso a **todas** las agendas y clientes de tu cuenta. Tratalo como una contraseña: no lo subas a un repositorio, no lo pegues en chats ni en capturas.
</Danger>

## Quickstart

**Base URL:** `https://api.turnito.app/api/public/v1/`

### 1. Probar conectividad

```bash theme={null}
curl -s -H "Authorization: Bearer $TURNITO_API_TOKEN" \
  https://api.turnito.app/api/public/v1/health
```

Respuesta esperada: `{ "status": "ok" }`.

### 2. Listar agendas

```bash theme={null}
curl -s -H "Authorization: Bearer $TURNITO_API_TOKEN" \
  https://api.turnito.app/api/public/v1/agendas
```

### 3. Agendar un turno

```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/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"
  }'
```

La respuesta incluye el `cancel_id` del turno: lo usás después para reprogramar o cancelar.

## Autenticación y límites

Todas las requests llevan:

```http theme={null}
Authorization: Bearer tk_live_<tu_token>
```

| Tipo      | Métodos         | Límite default |
| --------- | --------------- | -------------- |
| Lectura   | `GET`           | 60 / minuto    |
| Escritura | `POST`, `PATCH` | 10 / minuto    |

Si llegás al tope, la API responde `429` con `Retry-After`. Esperá ese tiempo y reintentá.

Cada respuesta incluye `X-Request-ID`. Si reportás un problema a soporte, **incluí ese id** (y nunca el token).

## Pagos desde la API

Si la agenda tiene cobro activo, al crear un turno podés:

* Dejar que se genere el link de pago (comportamiento por defecto cuando corresponde).
* Elegir el método con `payment_method_uuid` (listalo antes con `GET .../payment_methods`).
* Saltear el cobro con `require_payment: false` (útil cuando cobrás por otro canal).

El detalle de estados, reembolsos al cancelar y recetas está en [Referencia de la API](/api/referencia).

## Si algo no funciona

* **401:** token inválido, vencido o revocado → pedí uno nuevo a [ayuda@turnito.app](mailto:ayuda@turnito.app).
* **404 en una agenda:** el `uuid` no es de tu cuenta o está mal copiado.
* **409 / validation\_error al agendar:** horario ocupado, datos incompletos o método de pago inválido — leé `error.message` y `error.details`.
* **429:** esperá `Retry-After` y reintentá con backoff.

## Limitaciones

* El token no se gestiona desde el panel (por ahora).
* No hay sandbox ni tokens de prueba (`tk_test_`).
* No hay webhooks en v1.
* No crea ni edita la configuración de la agenda.
* No soporta reservas recurrentes.

## Páginas relacionadas

* [Referencia de endpoints y recetas](/api/referencia)
* [Activar el cobro anticipado](/cobros/activar-cobros)
* [Preguntas frecuentes](/faq)