Endpoints
Los endpoints de la API v1 agrupados por tema, con el scope que pide cada uno, y qué áreas son solo del panel.
Actualizado:
El contrato legible por máquina está en el repositorio, en packages/openapi/openapi.yaml (OpenAPI 3.1). Esta página resume lo que podés usar con una clave de API. Las áreas marcadas como "solo panel" usan la sesión de una persona del equipo (ver Autenticación).
Agenda: horarios y reservas
| Método | Path | Scope | Descripción |
|---|---|---|---|
| GET | /slots | slots:read | Horarios disponibles para un servicio |
| POST | /holds | bookings:write | Crear pre-reserva de 10 minutos |
| POST | /holds/{id}/confirm | bookings:write | Confirmar (o pending_payment si pide seña) |
| DELETE | /holds/{id} | bookings:write | Liberar pre-reserva |
| POST | /bookings | bookings:write | Pre-reserva y confirmación en una llamada |
| GET | /bookings | bookings:read | Listar (from, to, status, resource_id, customer_id) |
| GET / PATCH | /bookings/{id} | bookings:read / write | Leer, actualizar notas o datos de ingreso |
| POST | /bookings/{id}/cancel, /reschedule, /check-in, /no-show, /complete, /fail | bookings:write | Cambiar el estado |
Trabajo: tareas y acciones
Una reserva es una tarea con etapas. Las tareas sin horario (por ejemplo entregas) viven en la cola de un equipo hasta que alguien las toma. Ver Trabajo y acciones.
| Método | Path | Scope | Descripción |
|---|---|---|---|
| GET | /work-items | bookings:read | Consulta unificada: filtros por view (inbox, today, upcoming), status, stage, unassigned, priority, tag, origin, q, rango de fechas y caja geográfica |
| PATCH | /work-items/{id} | bookings:write | Cambiar prioridad, etiquetas o vencimiento (con expected_version opcional) |
| POST | /bookings/{id}/actions/{key} | bookings:write | Ejecutar una acción de la etapa (tomar, soltar, completar, "no estaba"…) con Idempotency-Key |
| GET | /bookings/{id}/stage-history | bookings:read | Historial de etapas |
| GET | /bookings/{id}/comments, /timeline | bookings:read | Comentarios y línea de tiempo |
| GET | /bookings/{id}/attachments, /location-events | bookings:read | Evidencia de trabajo |
| GET | /conversations/{id}/work-items | bookings:read | Tareas creadas desde una conversación |
| GET | /team/overview, /resources/{id}/stats | bookings:read | Ocupación y estadísticas del equipo |
Catálogo y etapas
| Método | Path | Scope |
|---|---|---|
| GET / POST | /services, /resources, /resource-groups, /schedules | config:read / config:write |
| GET / PATCH / DELETE | /services/{id}, /resources/{id}, /resource-groups/{id}, /schedules/{id} | config:read / config:write |
| POST / DELETE | /schedules/{id}/overrides, /schedules/{id}/overrides/{date} | config:write |
| GET | /schedule-overrides | config:read |
| GET | /flows, /flows/{id}, /flows/{id}/versions, /flows/{id}/versions/{version} | config:read |
| GET | /flow-message-catalog | config:read |
| POST | /flows | settings:write |
| PATCH | /flows/{id} | settings:write |
| POST | /flows/{id}/validate, /flows/{id}/copy, /flows/{id}/versions/{version}/revert | settings:write |
| GET | /flow-examples, /base-states | config:read |
Clientes
| Método | Path | Scope | Descripción |
|---|---|---|---|
| GET | /customers | customers:read | Listar y buscar (q: nombre, email, empresa, etiqueta o teléfono; phone, tag) |
| POST | /customers | customers:write | Alta manual. El teléfono es único: si ya existe, 409 customer_exists |
| GET / PATCH | /customers/{id} | customers:read / write | Leer o editar (incluye dirección con formatted, lat y lng) |
| GET | /customers/{id}/bookings, /summary, /timeline, /comments | customers:read | Historial, resumen en vivo, línea de tiempo y comentarios |
Un cliente puede tener varias identidades (WhatsApp, Telegram, WebChat) en identities[].
Conversaciones
| Método | Path | Scope |
|---|---|---|
| GET | /conversations, /conversations/{id}, /conversations/{id}/messages | messages:read |
| POST | /conversations/{id}/messages | messages:write (responde 409 channel_paused si el canal está pausado) |
| POST | /conversations/{id}/mode, /read, /resolve | messages:write |
Bot y conocimiento
| Método | Path | Scope |
|---|---|---|
| GET / PUT | /bot | config:read / config:write |
| GET / POST | /knowledge, /knowledge/files | config:read / config:write |
| POST | /knowledge/search | config:read |
| PATCH / DELETE | /knowledge/{id} | config:write |
| GET / POST / PATCH | /automations, /automations/{id} | config:read / config:write |
Webhooks salientes
| Método | Path | Scope |
|---|---|---|
| GET / POST | /webhook-endpoints | webhooks:manage |
| GET / PATCH / DELETE | /webhook-endpoints/{id} | webhooks:manage |
| POST | /webhook-endpoints/{id}/rotate-secret, /ping, /deliveries/{delivery_id}/resend | webhooks:manage |
| GET | /webhook-endpoints/{id}/deliveries | webhooks:manage |
Detalle en Webhooks.
Plataforma
| Método | Path | Scope |
|---|---|---|
| GET | /me | cualquiera |
Solo panel (no aceptan claves de API)
| Área | Rutas |
|---|---|
| Canales y pausas | /channels, /channels/whatsapp, /channels/telegram, /channels/service-status, /channels/pauses, /channels/{channel}/pause y /resume; ver Pausas y Estado |
| Política del bot por canal | /bot/channel-policies (ver WebChat) |
| Fuentes de conocimiento | /knowledge/sources (ver Conocimiento) |
| Reglas | /automation-flows (ver Reglas) |
| IA del proyecto | /ai/usage, /ai/pause, /ai/resume, /ai/spam-guard, /ai/notices |
| Wagy | /assistant/*, el asistente de configuración del panel |
| Equipo y cuenta | /team/*, /api-keys, /workspaces, /me/telegram, /me/notification-preferences |
| WebChat | /webchat-site (gestión) y /public/webchat/* (públicos, con la clave publicable del widget) |
Ejemplo: slots
GET /v1/slots?service_id=svc_laser&from=2026-10-20T09:00:00-03:00&to=2026-10-20T20:00:00-03:00&around=2026-10-20T18:00:00-03:00
{
"data": [
{ "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:30:00-03:00", "resource_ids": ["res_ana", "res_laser1", "res_room2"] },
{ "start": "2026-10-20T18:45:00-03:00", "end": "2026-10-20T19:30:00-03:00", "resource_ids": ["res_carla", "res_laser1", "res_room1"] }
],
"unavailable_reason": null
}
Ejemplo: objeto de reserva
{
"id": "bkg_7Qx1",
"status": "confirmed",
"stage": "confirmed",
"service_id": "svc_laser",
"start": "2026-10-20T17:45:00-03:00",
"end": "2026-10-20T18:30:00-03:00",
"party_size": 1,
"customer": { "id": "cus_31", "name": "Marina", "phone": "+5521988887777", "locale": "pt" },
"allocations": [
{ "resource_id": "res_ana", "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:40:00-03:00" },
{ "resource_id": "res_laser1", "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:40:00-03:00" },
{ "resource_id": "res_room2", "start": "2026-10-20T17:45:00-03:00", "end": "2026-10-20T18:40:00-03:00" }
],
"priority": "normal",
"tags": [],
"source": "whatsapp",
"created_at": "2026-10-19T11:02:13-03:00"
}
Las asignaciones incluyen el buffer (acá, 10 minutos después del servicio). En las tareas con cola, start y end vienen en null hasta que alguien las toma.
Cambios recientes
Estas son las novedades de la API, todas aditivas. El historial completo vive en el repositorio (docs/api/CHANGELOG.md).
- Clientes: alta manual, datos ampliados, dirección con
formatted,latylng, eidentities[]multicanal. - Tareas y acciones: consulta unificada
GET /work-items, ejecutor de acciones con efectos (tomar, soltar, resultados) y409 already_claimed. - Mensajes con ubicación: WhatsApp, Telegram y WebChat guardan la ubicación compartida en la conversación.
- Pausas: al pausar un canal, enviar un mensaje responde
409 channel_paused. - Conocimiento: fuentes de tipo sitio con
max_pagesy errores por causa.
Las confirmaciones conservan título y cuerpo en los tres idiomas. La API admite hasta 42 etapas para preservar las identidades anteriores y las canónicas del sistema. Las canónicas aisladas no añaden acciones ni permisos; las salidas configuradas conservan la validación del grafo. Validar, guardar y restaurar aceptan esas configuraciones migradas.