Documentación · API v1
API de Tactivo
Una API REST para que el CRM, la centralita, el asistente de IA o cualquier otro sistema de una clínica trabaje con sus clientes, su agenda, sus bonos y su facturación. Esta documentación se genera desde el propio código de la API, así que siempre está al día.
Primeros pasos
Conexión
Base URL: https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1
Autorización: Authorization: Bearer ta_api_...
Formato: JSON sobre HTTPS
Zona horaria: la de la clínica (Europe/Madrid; Atlantic/Canary en Canarias)
Límite: 120 peticiones por minuto y token
Escrituras: 2000 operaciones nuevas cada 24 h y token (429 DAILY_WRITE_LIMIT)El token identifica automáticamente la clínica y sus permisos. El consumidor no debe ni puede enviar un company_id. Para solicitar una credencial de producción o ampliar permisos hay que contactar con soporte de Tactivo.
El token de producción debe guardarse únicamente como secreto del backend. No debe incluirse en URLs, frontend, aplicaciones móviles, repositorios, capturas o tickets.
Entorno de pruebas (sandbox)
No es necesario tocar los datos de ninguna clínica real para desarrollar una integración. Tactivo mantiene una clínica de pruebas permanente con datos ficticios y un token público de sandbox:
Token de sandbox: ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2La URL base, el formato y todos los endpoints son exactamente los mismos que en producción; solo cambia la credencial. El token de sandbox solo puede acceder a la clínica de pruebas, por lo que puede usarse con menos cautelas que uno de producción, pero sigue sujeto al límite de peticiones.
Contenido de la clínica de pruebas:
- Servicios de cita: Fisioterapia (60 min), Nutrición (45 min) y Sesión de seguimiento (30 min).
- Servicio de clase: Clase de pilates (60 min, aforo 8).
- Bonos: 5 sesiones de fisioterapia, 1 sesión de nutrición y 8 clases de pilates.
- Suscripciones de catálogo: 2 clases/semana de pilates y 1 clase/semana de pilates.
- Salas: Cabina 1 y Sala de pilates, en el centro principal.
- Profesionales: Laura Sanz, fisioterapia (mañanas de lunes a viernes) y Pablo Gil, nutrición (tardes de lunes a viernes y sábados por la mañana).
- Centros: Centro principal y Centro Sur.
- Horario de la clínica: lunes a viernes de 9:00 a 20:00 y sábados de 10:00 a 14:00 (domingos cerrado), zona Europe/Madrid.
- Un cliente de ejemplo, María López Pruebas, con teléfono
+34600200003, vinculado a la entidad Mutua Pruebas (GET /entities). - El token de sandbox tiene todos los permisos de la API, salvo el legado
legacy:read.
Condiciones de uso del sandbox:
- No introduzcas nunca datos personales reales: es un entorno público de pruebas.
- Los datos pueden reiniciarse periódicamente y sin previo aviso.
- El token de sandbox es compartido por todos los integradores y comparte el límite de 120 peticiones por minuto.
Tu primera llamada
Con el token público del entorno de pruebas, tal cual. Devuelve los datos de la clínica de pruebas.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/company" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Todos los ejemplos de la referencia usan este mismo token. Cambia los valores en mayúsculas (como SERVICE_ID) por los identificadores que devuelven las lecturas.
Acceso a producción
- 1
Prueba sin pedir nada
El entorno de pruebas es una clínica ficticia con un token público. Tiene las mismas rutas y las mismas respuestas que producción, así que puedes desarrollar toda la integración antes de tocar datos reales.
- 2
Pide el token de producción
Los tokens de producción los crea el equipo de Tactivo para cada clínica, solo con los permisos que necesita la integración. Escribe a soporte indicando la clínica y qué quieres conectar; si más adelante necesitas más permisos, se amplían por la misma vía.
- 3
Guárdalo solo en tu backend
El token de producción identifica a la clínica: guárdalo como un secreto del servidor. Nunca en una web, una app móvil, una URL, un repositorio, una captura o un ticket.
Para pedir un token de producción o ampliar sus permisos, escribe a soporte indicando la clínica y qué quieres conectar:
Permisos
Un token solo puede hacer lo que permiten sus permisos, y solo en su clínica. Cada endpoint de la referencia indica el que exige.
| Permiso | Da acceso a |
|---|---|
bonuses:read | Bonos |
bonuses:write | Bonos |
calendar:read | Reservas (flujo de agenda), Agenda |
calendar:write | Reservas (flujo de agenda) |
catalog:read | Reservas (flujo de agenda), Catálogo |
clients:read | Clientes, Reservas (flujo de agenda) |
clients:write | Clientes, Reservas (flujo de agenda) |
company:read | Clínica |
finance:read | Facturación, ventas y gastos |
metrics:read | Métricas |
worklogs:read | Registro de jornada |
Guía
Clientes
Para dar de alta un cliente en la lista de la clínica, sin crear una cita:
POST /clients
Idempotency-Key: crm-contact-123{
"name": "María",
"last_name": "López",
"phone": "+34600111222",
"email": "maria@example.com",
"dni": "12345678Z",
"gender": "mujer",
"birth_date": "1990-05-12",
"address": "Calle Mayor 1, Madrid",
"occupation": "Profesora",
"sport": "Natación",
"origins": ["Google"],
"review_opt_out": false
}Nombre, apellidos y teléfono son obligatorios; el teléfono debe ser un número válido (CLIENT_PHONE_INVALID si está incompleto). El resto de campos de la ficha son opcionales. La API permite compartir teléfono y rechaza un DNI que ya exista en esa clínica (409). Los orígenes se envían como texto y se crean en el catálogo de la clínica si no existen. La respuesta incluye id y client_number para guardar el vínculo en el sistema externo. El cliente queda como ficha normal (is_guest: false), no como invitado. La foto no se puede enviar por API.
GET /clients lista las fichas de la clínica y GET /clients/{client_number} devuelve la ficha completa de un cliente por su número. El id de cada ficha es el que usan las citas (client en GET /events), los bonos y las cuotas (client_id); GET /clients?id=... busca una ficha por él. Para editar:
PATCH /clients/00006
Idempotency-Key: crm-contact-123-edit-1{ "phone": "+34600444555", "sport": "Ciclismo", "origins": null }Solo se actualizan los campos presentes; un valor null vacía el campo. El email no se puede cambiar mientras el cliente tenga cuenta de usuario (409 CLIENT_EMAIL_LOCKED). No hay borrado por API.
POST /booking/clients pertenece solo al flujo de agenda: crea un invitado para poder reservar. No lo uses para sincronizar un CRM.
Entidades
GET /entities (permiso finance:read) lista las entidades de la clínica (mutuas, aseguradoras, federaciones, clubes…) con sus datos fiscales, la retención de IRPF que practican y, en clients, los clientes cuya ficha las tiene como responsable de facturación (client_number, name, last_name):
{
"id": "ENTITY_ID",
"name": "Mutua Ejemplo",
"nif": "A12345678",
"irpf_retention_percentage": 15,
"external_billing": false,
"clients": [
{ "client_number": "00006", "name": "María", "last_name": "López" }
]
}Filtra con id o con q (nombre o NIF). La lista refleja la entidad actual de cada ficha; una sesión concreta puede haberla pagado otra entidad.
Caja: cobros y devoluciones
GET /cash-movements (permiso finance:read) es el libro de Caja de la clínica: cada cobro, devolución o corrección es un movimiento con su identificador, fecha (occurred_at), importe, forma de pago y origen. Es la consulta indicada para contabilidad y conciliación bancaria:
GET /cash-movements?from=2026-10-31T23:00:00Z&to=2026-11-30T22:59:59ZLas fechas van en ISO 8601. En la URL, escribe la hora en UTC (Z) o codifica el + del desfase como %2B (2026-11-01T00:00:00%2B01:00); un + sin codificar se lee como un espacio y la petición falla.
amountes positivo si entra dinero y negativo si sale. Una devolución, un cambio de importe o de forma de pago nunca modifican un movimiento anterior: se apuntan como movimientos nuevos (por ejemplo,-40con TPV y+40con Efectivo).source_typedice de dónde viene el dinero y qué identificador lo enlaza:
source_type | Origen | Identificador |
|---|---|---|
appointment | Cita | source_event_id (GET /events) |
bonus_assignment | Venta de un bono | source_bonus_assignment_id (GET /bonus-assignments) |
class_subscription | Cuota mensual de una suscripción | source_class_subscription_charge_id (GET /subscription-charges) |
inventory_sale | Venta de productos | source_inventory_sale_id (GET /inventory-sales) |
free_invoice | Factura libre | source_invoice_id (GET /invoices) |
entity_receivable | Pago de una entidad (mutua, aseguradora…) | entity_receivable |
La suma de amount de un mismo origen es lo cobrado neto al cliente. Un bono puede cobrarse en varios pagos y en días distintos: cada pago es un movimiento con su fecha. Las sesiones consumidas con un bono no generan movimiento (su cobro es el del bono), así que no se cuentan dos veces; en GET /events, las citas aparecen con forma de pago Bono y el bonus_assignment_id usado.
Cuando paga una entidad, el movimiento es entity_receivable y el objeto entity_receivable dice qué entidad pagó (entity_id, entity_name_snapshot) y qué cita, bono, cuota o venta saldó, con su importe y la retención de IRPF. Su source_type usa sus propios valores: appointment, bonus, class_subscription o product. La clínica ve estos cobros en Caja › Entidades, no en Caja › Movimientos: si comparas con esa pantalla, la diferencia son ellos.
Filtros: from y to (sobre occurred_at), created_from, source_type, payment_method, event_id, bonus_assignment_id e id.
Un movimiento puede llevar una fecha anterior a cuando se registró (una cita marcada como cobrada días después) y la clínica puede corregir su fecha. Para no perder nada en un periodo ya cerrado, pide también lo registrado desde tu última lectura con created_from y, antes de cerrar un periodo, vuelve a leerlo entero. Si el origen de un cobro se borra después, el movimiento se conserva, aunque su identificador puede quedar vacío o dejar de aparecer en los otros listados.
IVA. Todos los importes (de citas, bonos, cuotas, ventas y Caja) llevan el IVA incluido. Cada cita lleva en GET /events el IVA de su servicio en el momento de crearla (service_snapshot_vat_percentage, con finance:read) y cada bono vendido, el suyo en vat_percentage de GET /bonus-assignments; al facturarlos se aplica el IVA vigente del servicio o del bono en el catálogo (GET /services y GET /bonuses), y lo ya facturado conserva el de su factura. Cada cuota lleva el suyo en GET /subscription-charges. 0 significa exento. Una clínica canaria (por el código postal de su dirección) factura con IGIC en lugar de IVA: sus tipos son 0, 3 y 7 en los mismos campos vat_*, y cada factura de GET /invoices dice el suyo en indirect_tax (iva o igic).
Bonos
La API permite consultar el catálogo de bonos y su configuración con un token que tenga bonuses:read:
| Operación | Contenido |
|---|---|
| GET /bonuses | Catálogo de bonos: identificador, nombre, créditos, precio y caducidad. |
| GET /bonus-service-credits?bonus_id=... | Créditos y servicios incluidos en un bono. |
| GET /bonus-assignments?client_id=... | Bonos ya asignados o vendidos a un cliente. |
Lo cobrado de cada bono (amount_paid, paid_in_full, payment_method, invoice_id y purchase_reference) y el filtro invoice_id requieren además finance:read; sin él, el listado trae precio, IVA y créditos, pero no esos campos.
Para asignar un bono del catálogo a un cliente:
POST /bonus-assignments
Idempotency-Key: crm-bonus-sale-123{
"client_number": "00006",
"bonus_id": "BONUS_ID",
"starts_on": "2026-09-22"
}Esta operación requiere bonuses:write. starts_on es opcional; si se omite, se usa la fecha actual de Europe/Madrid. Tactivo copia el precio, la caducidad y los créditos vigentes del catálogo. No registra ningún cobro ni movimiento de Caja: el precio completo queda pendiente y la clínica debe registrar después el cobro real en Tactivo. Si el cliente ya tiene citas o clases compatibles pendientes de bono, la asignación puede consumir inmediatamente los créditos necesarios para regularizarlas; la respuesta informa cuántos se han consumido.
La API no permite cobrar, cancelar ni modificar bonos. Los filtros, la paginación y los campos completos están definidos en openapi.json.
Suscripciones
La API permite consultar el catálogo de planes de clase con catalog:read:
| Operación | Contenido |
|---|---|
| GET /subscription-plans | Planes: nombre, precio mensual y límite semanal. |
| GET /subscription-plan-services | Servicios de clase incluidos en cada plan. |
GET /subscription-charges (permiso finance:read) lista las cuotas mensuales de los clientes: mes (period_month), plan, importe, IVA, lo cobrado y su estado. paid_at es cuándo quedó pagada del todo, no la fecha de cada pago. Si la paga una entidad (forma de pago Entidad), la cuota sale pagada desde que se crea: significa que corre a cargo de la entidad. Los pagos reales de cada cuota, con fecha y forma, están en GET /cash-movements (los de una entidad, como entity_receivable).
No hay alta, cobro ni cancelación de suscripciones de clientes por API.
Ocupación de profesionales
GET /occupancy (permiso metrics:read) devuelve la ocupación de cada profesional con las mismas cifras que el Dashboard y el Analista de Tactivo:
GET /occupancy?from=2026-10-01&to=2026-10-31&group_by=monthfromytoson obligatorios (Europe/Madrid, ambos incluidos): hasta 366 días, o 92 congroup_by=day.group_by:professional(por defecto, una fila por profesional),day,week(lunes a domingo) omonth;professional_idlimita a una persona.- Cada fila trae, en minutos, el horario del día (semanal, semana A/B u horario especial), lo bloqueado dentro de ese horario, lo disponible (horario menos bloqueos), lo ocupado y lo libre. Ocupado es solo el tiempo de citas y clases no canceladas que cae dentro de lo disponible: sumar duraciones de GET /events no cuadra si hay citas fuera de horario.
occupancy_pctes ocupado ÷ disponible × 100, con un decimal, y esnullsi todo el horario estaba bloqueado (vacaciones).totalssuma todo el equipo. - Solo hay fila para quien tiene horario en ese día, semana o mes: un día cerrado con un horario especial no aparece. Cuenta el personal con agenda; quien está archivado o es solo recepción queda fuera aunque salga en GET /staff. Para todo el equipo, mejor una llamada sin
professional_idque una por persona. - Los días futuros cuentan lo ya programado. Los horarios semanales no tienen histórico: un periodo pasado se calcula con el horario vigente.
Flujo de agenda
Para integrar una agenda deben utilizarse las rutas con prefijo /booking. En particular, el catálogo para reservar se consulta en GET /booking/services: devuelve duration_minutes y omite precios. Por defecto incluye los servicios que la clínica ofrece en su reserva online; a petición de la clínica, Tactivo puede habilitar todos sus servicios de cita para una integración concreta. Profesionales y horarios son siempre los que la clínica abre a la reserva online. GET /services pertenece al área general de lectura y no sustituye a esa ruta dentro del flujo de reservas.
Los filtros professional_id y location_id son opcionales al consultar disponibilidad. Cada hueco devuelto ya contiene una hora, profesional y ubicación concretos; deben utilizarse esos valores al reservar.
Si la clínica no deja elegir profesional en su reserva online, la API tampoco: professional_id responde 422 PROFESSIONAL_CHOICE_DISABLED y la disponibilidad trae un solo hueco por hora y sede, con uno de los profesionales libres. Para mover una cita se consulta con appointment_id, que da los huecos de su profesional y su sede (el cambio los conserva) también en esas clínicas, sin contar como ocupada la propia cita; si ese profesional no se ofrece en la reserva online, responde 422 APPOINTMENT_REQUIRES_RECEPTION.
La búsqueda de un cliente ya existente se realiza con POST /booking/clients/search, para no introducir datos personales en la URL. Puede buscarse por teléfono, DNI o nombre y apellido juntos (al menos 2 letras cada uno; un nombre o un apellido sueltos no devuelven candidatos):
{ "phone": "+34 600 111 222" }Una búsqueda ambigua devuelve hasta diez candidatos con teléfono y DNI parcialmente ocultos. El sistema externo no debe elegir automáticamente entre ellos.
Disponibilidad y citas
- El horizonte máximo es de 90 días.
- Las fechas de cita se transmiten en ISO 8601 con offset, por ejemplo
2026-09-01T10:00:00+02:00, y son el instante real de la cita. Los días (fromytode la disponibilidad) y las horas locales del resumen son los de la zona de la clínica: Europe/Madrid o, en Canarias, Atlantic/Canary. - Tactivo vuelve a validar el hueco al reservar para impedir citas simultáneas sobre el mismo profesional.
- Las citas se crean pendientes y sin cobrar.
Crear una cita:
{
"client_id": "CLIENT_ID",
"service_id": "SERVICE_ID",
"professional_id": "PROFESSIONAL_ID",
"location_id": "LOCATION_ID",
"starts_at": "2026-09-01T10:00:00+02:00",
"note": "Llegaré unos minutos antes"
}note es opcional (hasta 2.000 caracteres): es la nota de la reserva que ve solo el personal de la clínica, la misma que deja quien reserva online. Para añadir algo después, POST /booking/appointments/{appointment_id}/note con { "client_id": "CLIENT_ID", "note": "..." } y una Idempotency-Key: el texto va en una línea nueva de esa nota, que en total no pasa de 8.000 caracteres (si no cabe, 400 NOTE_TOO_LONG). La cita debe ser del cliente y no estar cancelada, y el cliente no recibe ningún aviso.
Mover una cita conserva cliente, servicio, profesional y ubicación. Los huecos para moverla se consultan con GET /booking/availability?service_id=...&appointment_id=...&from=...&to=...:
{
"client_id": "CLIENT_ID",
"starts_at": "2026-09-02T11:00:00+02:00"
}Cancelar una cita:
{
"client_id": "CLIENT_ID",
"reason": "Cancelada a petición del cliente"
}Por defecto la cita no se borra: queda en la agenda con estado cancelada (la respuesta lleva deleted: false) y con una nota automática para el equipo. En los listados sigue apareciendo con ese estado y modifiable: false. El hueco sigue ocupado hasta que la clínica borre la cita.
Si la clínica elimina las citas al cancelarlas (Ajustes › Centro), la respuesta lleva deleted: true: la cita deja de aparecer en los listados y el hueco queda libre. Una cita con un cobro registrado se cancela sin eliminarse.
Si una cita devuelve modifiable: false, debe intervenir recepción.
Idempotencia y errores
Todas las escrituras exigen la cabecera Idempotency-Key, de 8 a 200 caracteres. Debe utilizarse una clave nueva para cada operación y reutilizar la misma clave y el mismo cuerpo al reintentar un timeout. Nunca debe reutilizarse con un cuerpo diferente.
Los errores tienen un código estable:
{ "error": "SLOT_UNAVAILABLE" }| HTTP | Actuación recomendada |
|---|---|
400 | Corregir parámetros o cuerpo |
401 | Revisar la credencial o contactar con soporte |
403 | Solicitar permiso para esa área |
409 | Resolver duplicado, idempotencia o consultar otro hueco |
422 | Derivar la operación a recepción |
429 | Reintentar con espera exponencial |
5xx | Reintentar con espera exponencial |
Límites de clientes y agenda v1
Los clientes cubren alta, edición y consulta de los campos de la ficha, salvo la foto. El teléfono de alta y de edición se valida con el mismo criterio que la ficha de Tactivo. La consulta de bonos se realiza mediante los endpoints específicos descritos arriba; su única escritura es asignar un bono pendiente de cobro. Las suscripciones de clase se consultan en el catálogo; no se asignan por API. No se exponen historia clínica ni documentos, y las operaciones de la API no registran cobros ni generan facturas. El responsable de facturación solo se expone en modo manual (nombre, apellidos, documento y dirección), sin vincularlo a otro cliente o receptor.
En agenda solo se gestionan citas individuales presenciales. No se incluyen clases, domicilios, salas, recurrencias, cobros, señales, bonos, facturación, notas internas, documentos ni información clínica.
Tactivo aplica siempre los horarios y excepciones reales, antelación mínima, intervalos, bloqueos, citas existentes, desplazamientos y compatibilidades. GET /booking/availability devuelve la antelación mínima en min_notice_hours, para que un día sin huecos por esa regla se pueda explicar al cliente. Citas pasadas, realizadas, recurrentes, con varios clientes o vinculadas a pagos, señales, bonos o facturas requieren recepción. También las que ya están dentro del plazo de cancelación o cambio que se le comunica al cliente: el que la clínica configura si permite cancelar o modificar online y, si no, 24 horas.
Las rutas, campos, respuestas, permisos y códigos completos están definidos en openapi.json.
Teléfonos compartidos
Los dos endpoints de alta (POST /clients y POST /booking/clients) permiten teléfonos compartidos. El teléfono es un contacto, no la identidad del cliente. Antes de reservar, confirma nombre y apellidos y usa el client_id de la persona atendida. No selecciones automáticamente el primer resultado ni asumas que exact_match identifica a una persona: solo indica coincidencia de teléfono o DNI. Aunque solo aparezca la madre, puede ser necesario crear al hijo. La búsqueda devuelve hasta diez candidatos y excluye archivados.
Reutiliza la misma Idempotency-Key al reintentar un alta y una diferente para otra persona. Sin DNI, altas con claves diferentes pueden crear fichas repetidas; la API no deduce identidad por nombre y teléfono. Los avisos enviados al número compartido podrán referirse a varios clientes. Compartir teléfono no establece parentesco, acceso a otras fichas ni responsabilidad de pago. No uses el DNI de la madre en la ficha del hijo.
Referencia
Los 46 endpoints, generados desde el contrato OpenAPI: lo que ves aquí es lo que responde la API. Todas las rutas cuelgan de https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1.
General
2 endpointsGET/ health
Estado de la API
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/health"Respuestas
200Estado básico de la API4XXPetición no admitida por el gateway
Qué hacer ante cada error: Idempotencia y errores.
GET/ openapi.json
Contrato OpenAPI 3.1
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/openapi.json"Respuestas
200Contrato público vigente4XXPetición no admitida por el gateway
Qué hacer ante cada error: Idempotencia y errores.
Clínica
1 endpointGET/ company
Datos de la clínica
Devuelve la configuración principal de la clínica asociada al token.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/company" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Respuestas
200Clínica encontrada.objectdataobjectobligatorio
401Token inválido o expirado.403Token sin permiso para consultar la clínica.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
Clientes
4 endpointsGET/ clients
Clientes de la clínica, sin contenido clínico libre ni documentos. id es el identificador que usan client (GET /events), client_id (GET /bonus-assignments, GET /subscription-charges y demás) y las rutas /booking.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/clients" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de cliente.
client_numberstringen la consultaFiltra por número de cliente.
created_datestringen la consultaFiltra clientes creados en una fecha YYYY-MM-DD.
qstringen la consultaBusca por nombre, apellidos, email o teléfono.
is_guestbooleanen la consultaFiltra por invitado true/false.
treatment_statusstringen la consultaFiltra por estado de tratamiento.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
POST/ clients
Crear cliente
Crea un cliente normal en la lista de la clínica, sin cita, con todos los campos editables de la pestaña Datos salvo la foto. Nombre, apellidos y teléfono son obligatorios; el teléfono debe ser un número internacional válido (CLIENT_PHONE_INVALID). El resto de campos son opcionales. Se permite compartir teléfono; un DNI repetido en la clínica devuelve CLIENT_ALREADY_EXISTS (409). Los orígenes se envían como etiquetas y se crean en el catálogo si no existen. No sustituye a POST /booking/clients, que crea un invitado para reservar.
curl -X POST "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/clients" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2" \
-H "Idempotency-Key: crm-contact-123" \
-H "Content-Type: application/json" \
-d '{
"name": "María",
"last_name": "López",
"phone": "+34600111222",
"email": "maria@example.com",
"gender": "mujer",
"birth_date": "1990-05-12",
"origins": [
"Google"
]
}'Parámetros
Idempotency-KeystringcabeceraobligatorioIdentificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.
De 8 a 200 caracteres · Ejemplo: crm-contact-123
Cuerpo (JSON, obligatorio)
Ejemplo: {"name":"María","last_name":"López","phone":"+34600111222","email":"maria@example.com","gender":"mujer","birth_date":"1990-05-12","origins":["Google"]}
namestringobligatoriolast_namestringobligatoriophonestringobligatorioNúmero de teléfono válido, con o sin prefijo internacional. Ejemplo: +34600111222.
emailstring (email) | nulldnistring | nullgenderstring | nullSexo del cliente.
Valores: hombre, mujer, null
birth_datestring (date) | nullFecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.
Ejemplo: 1990-05-12
addressstring | nullDirección.
occupationstring | nullOcupación.
sportstring | nullActividad física.
originsarray<string> | nullOrígenes del cliente como etiquetas de texto. Las que no existan en el catálogo de la clínica se crean automáticamente. En PATCH, null elimina todos los orígenes.
Ejemplo: ["Google","Derivación"]
legal_guardian_namestring | nullNombre y apellidos del responsable legal del menor.
legal_guardian_identity_document_typestring | nullTipo de documento del responsable legal.
Valores: dni, nie, null
legal_guardian_identity_numberstring | nullNúmero de documento del responsable legal.
billing_info_enabledbooleanActiva el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales.
billing_namestring | nullNombre del responsable de facturación.
billing_last_namestring | nullApellidos del responsable de facturación.
billing_tax_idstring | nullNIF del responsable de facturación.
billing_addressstring | nullDirección del responsable de facturación.
review_opt_outbooleanExcluye al cliente de las solicitudes de valoración.
Respuestas
201Cliente creadoobjectdataobjectobligatorioFicha completa de la pestaña Datos. GET /clients/{client_number} añade treatment_status y has_account como contexto de solo lectura.
26 campos dentro de data
idstring (uuid)obligatorioclient_numberstringobligatorioEjemplo: 00006
createdstring (date) | nullEjemplo: 2026-09-18
namestringobligatorioEjemplo: María
last_namestringobligatorioEjemplo: López
phonestring | nullEjemplo: +34600111222
emailstring (email) | nullEjemplo: maria@example.com
dnistring | nullEjemplo: 12345678Z
is_guestfalseobligatoriogenderstring | nullSexo del cliente.
Valores: hombre, mujer, null
birth_datestring (date) | nullFecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.
Ejemplo: 1990-05-12
addressstring | nullDirección.
occupationstring | nullOcupación.
sportstring | nullActividad física.
originsarray<string>Etiquetas de origen del catálogo de la clínica.
Ejemplo: ["Google"]
legal_guardian_namestring | nullNombre y apellidos del responsable legal del menor.
legal_guardian_identity_document_typestring | nullTipo de documento del responsable legal.
Valores: dni, nie, null
legal_guardian_identity_numberstring | nullNúmero de documento del responsable legal.
billing_info_enabledbooleanActiva el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales.
billing_namestring | nullNombre del responsable de facturación.
billing_last_namestring | nullApellidos del responsable de facturación.
billing_tax_idstring | nullNIF del responsable de facturación.
billing_addressstring | nullDirección del responsable de facturación.
review_opt_outbooleanExcluye al cliente de las solicitudes de valoración.
treatment_statusstring | nullValores: en_tratamiento, alta_parcial, alta, null
has_accountbooleanTrue si el cliente tiene cuenta de usuario; en ese caso el email no se puede editar.
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación409Cliente duplicado o conflicto de idempotencia429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
GET/ clients/ {client_number}
Ficha completa de un cliente
Devuelve todos los campos de la pestaña Datos del cliente identificado por su número de cliente, único por clínica. La respuesta añade treatment_status y has_account como contexto de solo lectura.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/clients/CLIENT_NUMBER" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
client_numberstringen la rutaobligatorioNúmero de cliente visible en la clínica (ej. 00006).
Formato: ^[A-Za-z0-9]+$
Respuestas
200Cliente encontrado.objectdataobjectobligatorio
400Número de cliente inválido.401Token inválido o expirado.403Token sin permiso para consultar clientes.404Cliente no encontrado.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
PATCH/ clients/ {client_number}
Editar cliente
Edita parcialmente los campos de la pestaña Datos del cliente identificado por su número de cliente: solo se actualizan los campos presentes en el cuerpo y un valor null los vacía. Un teléfono informado debe ser válido (CLIENT_PHONE_INVALID). El email no se puede cambiar mientras el cliente tenga cuenta de usuario (CLIENT_EMAIL_LOCKED, 409); un DNI repetido en la clínica devuelve CLIENT_ALREADY_EXISTS (409). Los orígenes se envían como etiquetas y se crean en el catálogo si no existen; null elimina todos.
curl -X PATCH "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/clients/CLIENT_NUMBER" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2" \
-H "Idempotency-Key: crm-contact-123-update" \
-H "Content-Type: application/json" \
-d '{
"phone": "+34600444555",
"sport": "Ciclismo"
}'Parámetros
client_numberstringen la rutaobligatorioNúmero de cliente visible en la clínica (ej. 00006).
Formato: ^[A-Za-z0-9]+$
Idempotency-KeystringcabeceraobligatorioIdentificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.
De 8 a 200 caracteres · Ejemplo: crm-contact-123-update
Cuerpo (JSON, obligatorio)
Edición parcial: solo los campos presentes se actualizan y un valor null vacía el campo. La foto no se puede informar por API.
Ejemplo: {"phone":"+34600444555","sport":"Ciclismo"}
namestring | nulllast_namestring | nullphonestring | nullNúmero válido, o null para vaciarlo. Un valor incompleto devuelve CLIENT_PHONE_INVALID.
emailstring (email) | nulldnistring | nullgenderstring | nullSexo del cliente.
Valores: hombre, mujer, null
birth_datestring (date) | nullFecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.
Ejemplo: 1990-05-12
addressstring | nullDirección.
occupationstring | nullOcupación.
sportstring | nullActividad física.
originsarray<string> | nullOrígenes del cliente como etiquetas de texto. Las que no existan en el catálogo de la clínica se crean automáticamente. En PATCH, null elimina todos los orígenes.
Ejemplo: ["Google","Derivación"]
legal_guardian_namestring | nullNombre y apellidos del responsable legal del menor.
legal_guardian_identity_document_typestring | nullTipo de documento del responsable legal.
Valores: dni, nie, null
legal_guardian_identity_numberstring | nullNúmero de documento del responsable legal.
billing_info_enabledbooleanActiva el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales.
billing_namestring | nullNombre del responsable de facturación.
billing_last_namestring | nullApellidos del responsable de facturación.
billing_tax_idstring | nullNIF del responsable de facturación.
billing_addressstring | nullDirección del responsable de facturación.
review_opt_outbooleanExcluye al cliente de las solicitudes de valoración.
Respuestas
200Cliente actualizadoobjectdataobjectobligatorioFicha completa de la pestaña Datos. GET /clients/{client_number} añade treatment_status y has_account como contexto de solo lectura.
26 campos dentro de data
idstring (uuid)obligatorioclient_numberstringobligatorioEjemplo: 00006
createdstring (date) | nullEjemplo: 2026-09-18
namestringobligatorioEjemplo: María
last_namestringobligatorioEjemplo: López
phonestring | nullEjemplo: +34600111222
emailstring (email) | nullEjemplo: maria@example.com
dnistring | nullEjemplo: 12345678Z
is_guestfalseobligatoriogenderstring | nullSexo del cliente.
Valores: hombre, mujer, null
birth_datestring (date) | nullFecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.
Ejemplo: 1990-05-12
addressstring | nullDirección.
occupationstring | nullOcupación.
sportstring | nullActividad física.
originsarray<string>Etiquetas de origen del catálogo de la clínica.
Ejemplo: ["Google"]
legal_guardian_namestring | nullNombre y apellidos del responsable legal del menor.
legal_guardian_identity_document_typestring | nullTipo de documento del responsable legal.
Valores: dni, nie, null
legal_guardian_identity_numberstring | nullNúmero de documento del responsable legal.
billing_info_enabledbooleanActiva el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales.
billing_namestring | nullNombre del responsable de facturación.
billing_last_namestring | nullApellidos del responsable de facturación.
billing_tax_idstring | nullNIF del responsable de facturación.
billing_addressstring | nullDirección del responsable de facturación.
review_opt_outbooleanExcluye al cliente de las solicitudes de valoración.
treatment_statusstring | nullValores: en_tratamiento, alta_parcial, alta, null
has_accountbooleanTrue si el cliente tiene cuenta de usuario; en ese caso el email no se puede editar.
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación404Cliente no encontrado409DNI duplicado, email bloqueado por cuenta de usuario o conflicto de idempotencia429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
Reservas (flujo de agenda)
13 endpointsPOST/ booking/ appointments
Crear cita pendiente y sin cobrar
curl -X POST "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/appointments" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2" \
-H "Idempotency-Key: call-20260822-appointment-1" \
-H "Content-Type: application/json" \
-d '{
"client_id": "CLIENT_ID",
"service_id": "SERVICE_ID",
"professional_id": "PROFESSIONAL_ID",
"starts_at": "2026-09-01T10:00:00+02:00"
}'Parámetros
Idempotency-KeystringcabeceraobligatorioIdentificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.
De 8 a 200 caracteres · Ejemplo: call-20260822-appointment-1
Cuerpo (JSON, obligatorio)
client_idstring (uuid)obligatorioservice_idstring (uuid)obligatorioprofessional_idstring (uuid)obligatoriolocation_idstring (uuid) | nullstarts_atstring (date-time)obligatorionotestringNota del cliente para el equipo (p. ej. «llegaré unos minutos antes»). La ve solo el personal, como la nota de la reserva online.
Máximo 2000 caracteres
Respuestas
201Cita creadaobjectdataobjectobligatorio13 campos dentro de data
idstring (uuid)obligatorioclient_idstring (uuid)starts_atstring (date-time)obligatorioEjemplo: 2026-09-01T10:00:00+02:00
ends_atstring (date-time)obligatorioEjemplo: 2026-09-01T11:00:00+02:00
statusstringobligatorioEjemplo: pendiente
service_idstring (uuid) | nullservice_namestring | nullprofessional_idstring (uuid) | nullprofessional_namestring | nulllocation_idstring (uuid) | nulllocation_namestring | nullmodifiablebooleanrestriction_codestring | nullEjemplo: null
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación409Hueco ocupado o conflicto de idempotencia422Combinación no reservable429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
PATCH/ booking/ appointments/ {appointment_id}
Mover una cita conservando cliente, servicio, profesional y ubicación
curl -X PATCH "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/appointments/APPOINTMENT_ID" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2" \
-H "Idempotency-Key: call-20260822-appointment-1" \
-H "Content-Type: application/json" \
-d '{
"client_id": "CLIENT_ID",
"starts_at": "2026-09-01T10:00:00+02:00"
}'Parámetros
appointment_idstring (uuid)en la rutaobligatorioIdempotency-KeystringcabeceraobligatorioIdentificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.
De 8 a 200 caracteres · Ejemplo: call-20260822-appointment-1
Cuerpo (JSON, obligatorio)
client_idstring (uuid)obligatoriostarts_atstring (date-time)obligatorio
Respuestas
200Cita movidaobjectdataobjectobligatorio13 campos dentro de data
idstring (uuid)obligatorioclient_idstring (uuid)starts_atstring (date-time)obligatorioEjemplo: 2026-09-01T10:00:00+02:00
ends_atstring (date-time)obligatorioEjemplo: 2026-09-01T11:00:00+02:00
statusstringobligatorioEjemplo: pendiente
service_idstring (uuid) | nullservice_namestring | nullprofessional_idstring (uuid) | nullprofessional_namestring | nulllocation_idstring (uuid) | nulllocation_namestring | nullmodifiablebooleanrestriction_codestring | nullEjemplo: null
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación409Hueco ocupado o conflicto de idempotencia422La cita requiere recepción429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
POST/ booking/ appointments/ {appointment_id}/ cancel
Cancelar y retirar una cita
curl -X POST "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/appointments/APPOINTMENT_ID/cancel" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2" \
-H "Idempotency-Key: call-20260822-appointment-1" \
-H "Content-Type: application/json" \
-d '{
"client_id": "CLIENT_ID"
}'Parámetros
appointment_idstring (uuid)en la rutaobligatorioIdempotency-KeystringcabeceraobligatorioIdentificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.
De 8 a 200 caracteres · Ejemplo: call-20260822-appointment-1
Cuerpo (JSON, obligatorio)
client_idstring (uuid)obligatorioreasonstringMáximo 500 caracteres
Respuestas
200Cita cancelada (o eliminada, según la clínica)objectdataobjectobligatorio5 campos dentro de data
idstring (uuid)obligatorioclient_idstring (uuid)obligatoriostatus"cancelada"obligatoriodeletedbooleanobligatoriofalse: la cita queda en la agenda con estado «cancelada». true: la clínica elimina las citas al cancelarlas (la cancelación se conserva en la ficha del cliente) y el hueco queda libre.
already_cancelledbooleanLa cita ya estaba cancelada: no se repite ningún aviso.
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación422La cita requiere recepción429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
POST/ booking/ appointments/ {appointment_id}/ note
Añadir una nota del cliente a su cita
Requiere calendar:write. Añade el texto en una línea nueva de la nota de la reserva, que ve solo el personal. La cita debe ser del cliente y no estar cancelada. El cliente no recibe ningún aviso.
curl -X POST "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/appointments/APPOINTMENT_ID/note" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2" \
-H "Idempotency-Key: call-20260822-appointment-1" \
-H "Content-Type: application/json" \
-d '{
"client_id": "CLIENT_ID",
"note": "NOTE"
}'Parámetros
appointment_idstring (uuid)en la rutaobligatorioIdempotency-KeystringcabeceraobligatorioIdentificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.
De 8 a 200 caracteres · Ejemplo: call-20260822-appointment-1
Cuerpo (JSON, obligatorio)
client_idstring (uuid)obligatorionotestringobligatorioDe 1 a 2000 caracteres
Respuestas
200Nota añadidaobjectdataobject3 campos dentro de data
idstring (uuid)client_idstring (uuid)notedtrue
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación409Cita cancelada o conflicto de idempotencia429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
GET/ booking/ availability
Huecos disponibles
Huecos reservables con su hora, profesional y sede. Si la clínica no deja elegir profesional en su reserva online, devuelve un solo hueco por hora y sede, con uno de los profesionales libres, y no admite professional_id.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/availability?service_id=SERVICE_ID&from=2026-09-01&to=2026-09-01" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
service_idstring (uuid)en la consultaobligatoriofromstring (date)en la consultaobligatoriotostring (date)en la consultaobligatorioprofessional_idstring (uuid)en la consultaSolo huecos de ese profesional. Si la clínica no deja elegir profesional en su reserva online, responde 422 PROFESSIONAL_CHOICE_DISABLED.
appointment_idstring (uuid)en la consultaPara mover una cita: solo huecos de su profesional y su sede, que el cambio conserva, sin contar como ocupada la propia cita. Se admite aunque la clínica no deje elegir profesional; no se combina con professional_id ni location_id (400 AVAILABILITY_FILTER_CONFLICT). Si su profesional no se ofrece en la reserva online (o está en exclude_professional_id), responde 422 APPOINTMENT_REQUIRES_RECEPTION.
location_idstring (uuid)en la consulta
Respuestas
200Huecos concretosobjectdataarray<object>obligatorio6 campos dentro de data
starts_atstring (date-time)obligatorioEjemplo: 2026-09-01T10:00:00+02:00
ends_atstring (date-time)obligatorioEjemplo: 2026-09-01T11:00:00+02:00
professional_idstring (uuid)obligatorioprofessional_namestringobligatorioEjemplo: Ana García
location_idstring (uuid) | nullobligatoriolocation_namestring | nullEjemplo: Clínica Centro
min_notice_hoursintegerobligatorioAntelación mínima de reserva de la clínica, en horas. No se devuelven huecos que empiecen antes de ahora más esta antelación: un día sin huecos puede deberse a ella y no a una agenda llena.
Mínimo: 0
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
GET/ booking/ availability/ summary
Huecos disponibles resumidos
Pensado para agentes de voz y chat. Mismos filtros, antelación y regla de elegir profesional que /availability, con el rango recortado a from + 89 días. Devuelve todas las horas libres por día en hora local (cada una con su índice tras #) y el detalle reservable de una página de huecos desde offset. Para ver el detalle de una hora fuera de la página, repite con los mismos parámetros y offset igual a su índice, y comprueba que local_date y local_time siguen siendo los elegidos antes de reservar: el índice cambia si entre medias se ocupa o caduca un hueco. location_name solo aparece si los huecos son de más de una sede. Si la consulta llega al límite de huecos, truncated=true y la lista es completa hasta complete_through: pide un rango más corto o, si la clínica deja elegir profesional, filtra por profesional.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/availability/summary?service_id=SERVICE_ID&from=2026-09-01&to=2026-09-01" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
service_idstring (uuid)en la consultaobligatoriofromstring (date)en la consultaobligatoriotostring (date)en la consultaobligatorioprofessional_idstring (uuid)en la consultaSolo huecos de ese profesional. Si la clínica no deja elegir profesional en su reserva online, responde 422 PROFESSIONAL_CHOICE_DISABLED.
appointment_idstring (uuid)en la consultaPara mover una cita: solo huecos de su profesional y su sede, que el cambio conserva, sin contar como ocupada la propia cita. Se admite aunque la clínica no deje elegir profesional; no se combina con professional_id ni location_id (400 AVAILABILITY_FILTER_CONFLICT). Si su profesional no se ofrece en la reserva online (o está en exclude_professional_id), responde 422 APPOINTMENT_REQUIRES_RECEPTION.
location_idstring (uuid)en la consultatimezonestringen la consultaZona de local_date, local_time y bookable_from. Por defecto, la de la clínica: Europe/Madrid o, en Canarias, Atlantic/Canary.
Ejemplo: Europe/Madrid
langstringen la consultaValores: es, en · Por defecto: es
offsetintegeren la consultaPor defecto: 0 · Mínimo: 0
exclude_professional_idstringen la consultaIds de profesionales que este canal no debe ofrecer, separados por comas (como mucho 20). Pensado para fijarlo en la configuración del agente, no para que lo elija el modelo.
limitintegeren la consultaPor defecto: 16 · Mínimo: 1 · Máximo: 50
Respuestas
200Horas por día y página de huecos reservablesobjecttime_zonestringobligatoriomin_notice_hoursintegerobligatorioMínimo: 0
bookable_fromobjectPrimera fecha y hora local reservable por la antelación mínima; solo si es mayor que cero.
3 campos dentro de bookable_from
local_datestringweekdaystringlocal_timestring
total_slotsintegerobligatoriotruncatedbooleancomplete_throughstring (date) | nullÚltimo día local con la lista completa cuando truncated=true.
daysarray<object>obligatorio3 campos dentro de days
datestring (date)weekdaystringtimesstringHoras locales «HH:MM#índice» separadas por espacios.
offsetintegerobligatoriohas_morebooleanobligatorionext_offsetinteger | nullobligatorioslotsarray<object>obligatorio9 campos dentro de slots
indexintegerlocal_datestringweekdaystringlocal_timestringstarts_at_for_bookingstring (date-time)Valor literal para starts_at al reservar o cambiar la cita.
professional_idstring (uuid)professional_namestring | nulllocation_idstring (uuid) | nulllocation_namestring | null
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
POST/ booking/ clients
Crear invitado
Permite compartir teléfono con otros clientes. Un DNI repetido en la clínica devuelve CLIENT_ALREADY_EXISTS (409). Usa una misma Idempotency-Key para reintentar y una distinta para cada persona.
curl -X POST "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/clients" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2" \
-H "Idempotency-Key: call-20260822-appointment-1" \
-H "Content-Type: application/json" \
-d '{
"name": "María",
"last_name": "López",
"phone": "+34600111222",
"email": "maria@example.com",
"gender": "mujer",
"birth_date": "1990-05-12",
"origins": [
"Google"
]
}'Parámetros
Idempotency-KeystringcabeceraobligatorioIdentificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.
De 8 a 200 caracteres · Ejemplo: call-20260822-appointment-1
Cuerpo (JSON, obligatorio)
Ejemplo: {"name":"María","last_name":"López","phone":"+34600111222","email":"maria@example.com","gender":"mujer","birth_date":"1990-05-12","origins":["Google"]}
namestringobligatoriolast_namestringobligatoriophonestringobligatorioNúmero de teléfono válido, con o sin prefijo internacional. Ejemplo: +34600111222.
emailstring (email) | nulldnistring | nullgenderstring | nullSexo del cliente.
Valores: hombre, mujer, null
birth_datestring (date) | nullFecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.
Ejemplo: 1990-05-12
addressstring | nullDirección.
occupationstring | nullOcupación.
sportstring | nullActividad física.
originsarray<string> | nullOrígenes del cliente como etiquetas de texto. Las que no existan en el catálogo de la clínica se crean automáticamente. En PATCH, null elimina todos los orígenes.
Ejemplo: ["Google","Derivación"]
legal_guardian_namestring | nullNombre y apellidos del responsable legal del menor.
legal_guardian_identity_document_typestring | nullTipo de documento del responsable legal.
Valores: dni, nie, null
legal_guardian_identity_numberstring | nullNúmero de documento del responsable legal.
billing_info_enabledbooleanActiva el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales.
billing_namestring | nullNombre del responsable de facturación.
billing_last_namestring | nullApellidos del responsable de facturación.
billing_tax_idstring | nullNIF del responsable de facturación.
billing_addressstring | nullDirección del responsable de facturación.
review_opt_outbooleanExcluye al cliente de las solicitudes de valoración.
Respuestas
201Cliente creadoobjectdataobjectobligatorio4 campos dentro de data
idstring (uuid)obligatorionamestringobligatorioEjemplo: María
last_namestringobligatorioEjemplo: López
is_guesttrueobligatorio
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación409Cliente duplicado o conflicto de idempotencia429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
GET/ booking/ clients/ {client_id}/ appointments
Próximas citas del cliente
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/clients/CLIENT_ID/appointments" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
client_idstring (uuid)en la rutaobligatoriofromstring (date-time)en la consultatostring (date-time)en la consulta
Respuestas
200Citas de los próximos 90 díasobjectdataarray<object>obligatorio13 campos dentro de data
idstring (uuid)obligatorioclient_idstring (uuid)starts_atstring (date-time)obligatorioEjemplo: 2026-09-01T10:00:00+02:00
ends_atstring (date-time)obligatorioEjemplo: 2026-09-01T11:00:00+02:00
statusstringobligatorioEjemplo: pendiente
service_idstring (uuid) | nullservice_namestring | nullprofessional_idstring (uuid) | nullprofessional_namestring | nulllocation_idstring (uuid) | nulllocation_namestring | nullmodifiablebooleanrestriction_codestring | nullEjemplo: null
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
POST/ booking/ clients/ search
Buscar clientes
Devuelve como máximo diez candidatos; teléfono y DNI se ocultan parcialmente. Por nombre solo se busca con nombre y apellido juntos (al menos 2 letras cada uno): un nombre o un apellido sueltos no devuelven candidatos. Un teléfono puede pertenecer a varias personas. exact_match indica coincidencia del contacto o DNI, no identidad única. Confirma la persona antes de usar su id; no selecciones automáticamente el primer candidato, incluso si solo hay uno.
curl -X POST "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/clients/search" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2" \
-H "Content-Type: application/json" \
-d '{
"phone": "+34 600 111 222"
}'Cuerpo (JSON, obligatorio)
Al menos 1 campo · Ejemplo: {"phone":"+34 600 111 222"}
namestringlast_namestringphonestringdnistring
Respuestas
200Candidatos mínimosobjectdataarray<object>obligatorioMáximo 10 elementos
6 campos dentro de data
idstring (uuid)obligatorionamestringobligatorioEjemplo: María
last_namestringobligatorioEjemplo: López
masked_phonestring | nullEjemplo: ******123
masked_dnistring | nullEjemplo: *****123
exact_matchbooleanobligatorio
ambiguousbooleanobligatorio
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
GET/ booking/ locations
Ubicaciones compatibles
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/locations?service_id=SERVICE_ID" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
service_idstring (uuid)en la consultaobligatorioprofessional_idstring (uuid)en la consulta
Respuestas
200Ubicacionesobjectdataarray<object>obligatorio2 campos dentro de data
idstring (uuid)obligatorionamestringobligatorioEjemplo: Clínica Centro
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
GET/ booking/ professionals
Profesionales compatibles
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/professionals?service_id=SERVICE_ID" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
service_idstring (uuid)en la consultaobligatorio
Respuestas
200Profesionalesobjectdataarray<object>obligatorio2 campos dentro de data
idstring (uuid)obligatorionamestringobligatorioEjemplo: Ana García
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
POST/ booking/ reception-followup
Avisar a recepción sobre una llamada no resuelta
Requiere calendar:write. Notifica solo a administradores y coordinadores de la clínica asociada al token. La misma call_id no duplica avisos. El push y la campana muestran solo el motivo y el teléfono; caller_name, client_id, note y callback_preference se ven al abrir el aviso en Tactivo. Son opcionales y nunca impiden el aviso: los textos largos se recortan y un client_id que no sea de un cliente de la clínica se descarta.
curl -X POST "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/reception-followup" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2" \
-H "Content-Type: application/json" \
-d '{
"call_id": "CALL_ID",
"reason": "booking_help"
}'Cuerpo (JSON, obligatorio)
call_idstringobligatorioDe 8 a 120 caracteres
callback_phonestringMáximo 30 caracteres
reasonstringobligatorioValores: booking_help, change_help, question, other
caller_namestringNombre de quien llama, si lo ha dado.
Máximo 120 caracteres
client_idstring (uuid)Ficha de cliente identificada en la llamada; debe ser de la misma clínica.
notestringQué necesita, en una o dos frases.
Máximo 500 caracteres
callback_preferencestringCuándo prefiere que le llamen, por ejemplo «por la tarde».
Máximo 120 caracteres
Respuestas
200Aviso creado o llamada ya notificadaobjectdataobject1 campo dentro de data
notifiedinteger
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
GET/ booking/ services
Servicios reservables
Servicios de cita que este token puede reservar: por defecto, los que la clínica ofrece en su reserva online; a petición de la clínica, Tactivo puede habilitar todos sus servicios de cita para una integración concreta.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/services" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Respuestas
200Catálogoobjectdataarray<object>obligatorio3 campos dentro de data
idstring (uuid)obligatorionamestringobligatorioEjemplo: Fisioterapia
duration_minutesintegerobligatorioMínimo: 1 · Ejemplo: 60
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permisos para esta operación429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
Agenda
1 endpointGET/ events
Citas, clases y bloqueos de agenda de la clínica. Los campos de cobro (paid, paid_at, payment_amount, payment_method, cost, service_snapshot_vat_percentage, bonus_assignment_id) y el filtro paid requieren finance:read. service_snapshot_vat_percentage es el IVA del servicio al crear la cita; al facturarla se aplica el IVA que tenga el servicio en ese momento.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/events" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de evento.
typestringen la consultaFiltra por tipo appointment/class/block.
statusstringen la consultaFiltra por appointment_status.
paidbooleanen la consultaFiltra por pagado true/false. Requiere finance:read.
client_idstringen la consultaFiltra por cliente contenido en el array client.
professional_idstringen la consultaFiltra por profesional contenido en el array professional.
service_idstringen la consultaFiltra por ID de servicio.
location_idstringen la consultaFiltra por ID de ubicación.
room_idstringen la consultaFiltra por ID de sala.
fromstringen la consultaFecha/hora ISO mínima de datetime.
tostringen la consultaFecha/hora ISO máxima de datetime.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
Catálogo
11 endpointsGET/ company-schedules
Horario general de la clínica.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/company-schedules" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ locations
Ubicaciones de la clínica.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/locations" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de ubicación.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ professional-locations
Relación entre profesionales y ubicaciones.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/professional-locations" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
professional_idstringen la consultaFiltra por profesional.
location_idstringen la consultaFiltra por ubicación.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ professional-schedules
Horarios por profesional.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/professional-schedules" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
professional_idstringen la consultaFiltra por profesional.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ professional-services
Relación entre profesionales y servicios.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/professional-services" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
professional_idstringen la consultaFiltra por profesional.
service_idstringen la consultaFiltra por servicio.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ rooms
Salas de la clínica.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/rooms" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de sala.
location_idstringen la consultaFiltra por ubicación.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ service-locations
Relación entre servicios y ubicaciones.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/service-locations" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
service_idstringen la consultaFiltra por servicio.
location_idstringen la consultaFiltra por ubicación.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ services
Catálogo de servicios de la clínica.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/services" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de servicio.
service_typestringen la consultaFiltra por tipo de servicio.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ staff
Miembros de staff: admin, coordinator y professional.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/staff" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de profesional.
qstringen la consultaBusca por nombre, apellidos, email o teléfono.
rolestringen la consultaFiltra por rol staff.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ subscription-plan-services
Servicios de clase incluidos en cada plan de suscripción del catálogo.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/subscription-plan-services" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
plan_idstringen la consultaFiltra por ID de plan.
service_idstringen la consultaFiltra por ID de servicio.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ subscription-plans
Catálogo de planes de suscripción de clase. No incluye altas de clientes ni cobros.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/subscription-plans" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de plan.
statusstringen la consultaFiltra por estado del plan.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
Bonos
4 endpointsGET/ bonus-assignments
Asignaciones y ventas de bonos de la clínica. Los campos de cobro (amount_paid, paid_in_full, payment_method, invoice_id, purchase_reference) y el filtro invoice_id requieren finance:read. vat_percentage es el IVA del bono al venderlo; al facturarlo se aplica el IVA que tenga el bono en ese momento. amount_paid es lo pagado por cualquier vía (también lo que paga una entidad o se trajo del programa anterior); los pagos uno a uno, con su fecha y forma, están en GET /cash-movements.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/bonus-assignments" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de asignación.
bonus_idstringen la consultaFiltra por ID de bono.
client_idstringen la consultaFiltra por ID de cliente.
invoice_idstringen la consultaFiltra por ID de factura. Requiere finance:read.
statusstringen la consultaFiltra por estado.
fromstringen la consultaFecha/hora ISO mínima de assigned_at.
tostringen la consultaFecha/hora ISO máxima de assigned_at.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
POST/ bonus-assignments
Asignar bono pendiente de cobro
Asigna a un cliente un bono del catálogo de la clínica. Conserva el precio, los créditos y la caducidad vigentes del catálogo, pero no registra ningún cobro ni movimiento de Caja: la asignación queda pendiente por el precio completo. La clínica debe registrar posteriormente el cobro en Tactivo. La asignación puede consumir inmediatamente créditos para regularizar citas o clases compatibles que estuvieran pendientes.
curl -X POST "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/bonus-assignments" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2" \
-H "Idempotency-Key: crm-bonus-sale-123" \
-H "Content-Type: application/json" \
-d '{
"client_number": "00006",
"bonus_id": "11111111-2222-4333-8444-555555555555",
"starts_on": "2026-09-22"
}'Parámetros
Idempotency-KeystringcabeceraobligatorioIdentificador único del intento. Debe reutilizarse al reintentar exactamente la misma operación.
De 8 a 200 caracteres · Ejemplo: crm-bonus-sale-123
Cuerpo (JSON, obligatorio)
Ejemplo: {"client_number":"00006","bonus_id":"11111111-2222-4333-8444-555555555555","starts_on":"2026-09-22"}
client_numberstringobligatorioNúmero visible del cliente dentro de la clínica.
Formato: ^[A-Za-z0-9]+$ · Ejemplo: 00006
bonus_idstring (uuid)obligatorioIdentificador devuelto por GET /bonuses.
starts_onstring (date) | nullPrimer día de vigencia en formato YYYY-MM-DD. Si se omite, se usa la fecha actual de Europe/Madrid.
Respuestas
201Bono asignado y pendiente de cobroobjectdataobjectobligatorio17 campos dentro de data
idstring (uuid)obligatorioclient_idstring (uuid)obligatorioclient_numberstringobligatoriobonus_idstring (uuid)obligatoriobonus_namestringobligatoriostatusstringobligatorioValores: active
assigned_atstring (date-time)starts_onstring (date)expires_onstring (date) | nullpricenumberobligatorioamount_paid0obligatoriopaid_in_fullbooleanobligatoriopayment_methodnullinitial_creditsintegerobligatorioremaining_creditsintegerobligatorioregularized_class_creditsintegerregularized_appointmentsinteger
400Petición inválida401Token ausente, inválido, revocado o caducado403Token sin permiso para asignar bonos404Cliente o bono no encontrado409Conflicto de idempotencia422El bono no tiene créditos de servicio configurados429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
GET/ bonus-service-credits
Detalle de créditos por servicio dentro de cada bono.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/bonus-service-credits" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
bonus_idstringen la consultaFiltra por ID de bono.
service_idstringen la consultaFiltra por ID de servicio.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ bonuses
Catálogo de bonos de la clínica.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/bonuses" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de bono.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
Facturación, ventas y gastos
8 endpointsGET/ cash-movements
Movimientos de Caja: cada cobro, devolución o corrección con su fecha (occurred_at), importe, forma de pago y origen, incluidos los cobros a entidades (que la app muestra aparte, en Caja › Entidades). amount es positivo si entra dinero y negativo si sale; una devolución o corrección es un movimiento nuevo y nunca modifica uno anterior. source_type indica el origen y qué identificador lo enlaza: appointment (source_event_id, una cita de GET /events), bonus_assignment (source_bonus_assignment_id, de GET /bonus-assignments), class_subscription (source_class_subscription_charge_id, cuota mensual de una suscripción), inventory_sale (source_inventory_sale_id), free_invoice (source_invoice_id) o entity_receivable (cobro a una entidad: entity_receivable trae la entidad, la cita, bono, cuota o venta que paga, el importe y la retención de IRPF). La suma de amount de un origen es lo cobrado neto al cliente; lo que paga una entidad está en sus movimientos entity_receivable. Las sesiones consumidas con un bono no generan movimiento: su cobro es el del bono. Si el origen se borra después del cobro, el movimiento se conserva, aunque su identificador puede quedar vacío o dejar de aparecer en los otros listados. La fecha de un movimiento puede ser anterior a su registro (un cobro con fecha atrasada) o corregirse después: created_from devuelve lo registrado desde una fecha.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/cash-movements" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de movimiento.
source_typestringen la consultaFiltra por origen: appointment, bonus_assignment, class_subscription, inventory_sale, free_invoice, entity_receivable.
payment_methodstringen la consultaFiltra por forma de pago (Efectivo, TPV, Bizum...).
event_idstringen la consultaFiltra por ID de cita.
bonus_assignment_idstringen la consultaFiltra por ID de bono vendido.
fromstringen la consultaFecha/hora ISO mínima de occurred_at.
tostringen la consultaFecha/hora ISO máxima de occurred_at.
created_fromstringen la consultaFecha/hora ISO mínima de created_at (cuándo se registró en Tactivo).
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ entities
Entidades de la clínica (mutuas, aseguradoras, federaciones, clubes...) con los clientes cuya ficha las tiene como responsable de facturación (clients: client_number, name, last_name). irpf_retention_percentage es la retención que practica la entidad; external_billing indica que la entidad se factura fuera de Tactivo.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/entities" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de entidad.
qstringen la consultaBusca por nombre o NIF.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ event-bonus-usages
Consumos de bonos aplicados a eventos.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/event-bonus-usages" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
event_idstringen la consultaFiltra por ID de evento.
client_idstringen la consultaFiltra por ID de cliente.
assignment_idstringen la consultaFiltra por ID de asignación de bono.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ expenses
Gastos de la clínica sin adjuntos ni notas libres.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/expenses" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de gasto.
typestringen la consultaFiltra por tipo puntual/recurrente.
categorystringen la consultaFiltra por categoría.
fromstringen la consultaFecha/hora ISO mínima de occurred_at.
tostringen la consultaFecha/hora ISO máxima de occurred_at.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ inventory-sale-lines
Líneas de detalle de ventas de inventario.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/inventory-sale-lines" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
sale_idstringen la consultaFiltra por ID de venta.
product_idstringen la consultaFiltra por ID de producto.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ inventory-sales
Ventas de inventario de la clínica.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/inventory-sales" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de venta.
client_idstringen la consultaFiltra por ID de cliente.
invoice_idstringen la consultaFiltra por ID de factura.
statusstringen la consultaFiltra por estado.
fromstringen la consultaFecha/hora ISO mínima de sold_at.
tostringen la consultaFecha/hora ISO máxima de sold_at.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ invoices
Facturas emitidas de la clínica. recipient_nif_country es el país (ISO 3166-1 alfa-2) del pasaporte o documento extranjero del destinatario; null si recipient_nif es un NIF español. is_annulled indica una anulación fiscal efectiva: su cobro no aplica aunque status siga en pendiente o cobrada. Una rectificativa con rectification_type S (por sustitución) lleva los importes completos correctos y sustituye rectified_base_amount, rectified_vat_amount y rectified_surcharge_amount; una con I (por diferencias) lleva solo el ajuste. indirect_tax es el impuesto con el que se emitió: iva o igic (clínica canaria); vat_percentage y el de cada línea son tipos de ese impuesto.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/invoices" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de factura.
recipient_idstringen la consultaFiltra por ID de destinatario.
statusstringen la consultaFiltra por estado.
fromstringen la consultaFecha mínima YYYY-MM-DD de issue_date.
tostringen la consultaFecha máxima YYYY-MM-DD de issue_date.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
GET/ subscription-charges
Cuotas mensuales de las suscripciones de clase de los clientes: mes (period_month, primer día del mes), plan, importe con IVA incluido (amount; full_month_amount es la cuota entera y prorated indica que se prorrateó), IVA, lo pagado (amount_paid) y su estado. paid_at es cuándo quedó pagada del todo en Tactivo, no la fecha de cada pago. Con payment_method Entidad, status paid y amount_paid significan que la cuota corre a cargo de la entidad desde que se crea, no que la entidad la haya pagado. Los pagos reales, con fecha y forma, están en GET /cash-movements: source_type class_subscription con source_class_subscription_charge_id, o entity_receivable con entity_receivable.source_class_subscription_charge_id.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/subscription-charges" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID de cuota.
client_idstringen la consultaFiltra por ID de cliente.
statusstringen la consultaFiltra por estado.
fromstringen la consultaMes mínimo YYYY-MM-DD de period_month.
tostringen la consultaMes máximo YYYY-MM-DD de period_month.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
Registro de jornada
1 endpointGET/ work-logs
Registros de fichaje sin notas libres.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/work-logs" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
limitintegeren la consultaNúmero máximo de filas por página. Por defecto 50, máximo 200.
Por defecto: 50 · Mínimo: 1 · Máximo: 200
offsetintegeren la consultaDesplazamiento de página para paginación por offset.
Por defecto: 0 · Mínimo: 0
idstringen la consultaFiltra por ID del registro.
professional_idstringen la consultaFiltra por profesional.
fromstringen la consultaFecha mínima YYYY-MM-DD de work_date.
tostringen la consultaFecha máxima YYYY-MM-DD de work_date.
Respuestas
200Listado paginado.objectdataarray<object>obligatoriopaginationobjectobligatorio3 campos dentro de pagination
limitintegerobligatorioMínimo: 1 · Máximo: 200
offsetintegerobligatorioMínimo: 0
next_offsetinteger | nullobligatorioMínimo: 0
400Parámetro inválido.401Token inválido o expirado.403Token sin permiso para este recurso.429Límite de peticiones superado.
Qué hacer ante cada error: Idempotencia y errores.
Métricas
1 endpointGET/ occupancy
Ocupación por profesional
Ocupación de cada profesional en un periodo, con las mismas cifras que el Dashboard y el Analista de Tactivo. Por cada profesional con horario devuelve los minutos de horario (semanal, semana A/B u horario especial de cada día), bloqueados (solo lo que los bloqueos tapan del horario), disponibles (horario menos bloqueos), ocupados (citas y clases no canceladas dentro de lo disponible; las no presentadas cuentan) y libres (disponibles menos ocupados). occupancy_pct es ocupados ÷ disponibles × 100 con un decimal, calculado con las sumas de cada fila y nunca promediando días; es null si todo el horario estaba bloqueado. Cuenta el personal con agenda (sin archivar y sin recepción). Fechas en Europe/Madrid, ambas incluidas; los días futuros cuentan lo ya programado. Los horarios semanales no se versionan: un periodo pasado se calcula con el horario vigente y los horarios especiales de cada fecha.
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/occupancy?from=2026-10-01&to=2026-10-31" \
-H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"Parámetros
fromstring (date)en la consultaobligatorioPrimer día del periodo (YYYY-MM-DD, entre 2000 y 2100).
Ejemplo: 2026-10-01
tostring (date)en la consultaobligatorioÚltimo día del periodo (YYYY-MM-DD). Como mucho 366 días; con group_by=day, 92.
Ejemplo: 2026-10-31
group_bystringen la consultaprofessional: una fila por profesional para todo el periodo; day, week (lunes a domingo) o month: una fila por profesional y tramo, recortada al periodo pedido.
Valores: professional, day, week, month · Por defecto: professional
professional_idstring (uuid)en la consultaSolo este profesional (identificador de GET /staff).
Respuestas
200Ocupación del periodoobjectfromstring (date)obligatoriotostring (date)obligatoriogroup_bystringobligatorioValores: professional, day, week, month
dataarray<object>obligatorio11 campos dentro de data
professional_idstring (uuid)obligatorioprofessional_namestringobligatorioperiod_startstring (date)obligatorioperiod_endstring (date)obligatorioworking_daysintegerobligatorioDías con horario de cada profesional que suma la fila.
scheduled_minutesnumberobligatorioblocked_minutesnumberobligatorioavailable_minutesnumberobligatoriooccupied_minutesnumberobligatoriofree_minutesnumberobligatoriooccupancy_pctnumber | nullobligatorio
totalsobjectobligatorioTodo el equipo considerado en el periodo.
7 campos dentro de totals
working_daysintegerobligatorioDías con horario de cada profesional que suma la fila.
scheduled_minutesnumberobligatorioblocked_minutesnumberobligatorioavailable_minutesnumberobligatoriooccupied_minutesnumberobligatoriofree_minutesnumberobligatoriooccupancy_pctnumber | nullobligatorio
400Petición inválida: INVALID_FROM_DATE, INVALID_TO_DATE, INVALID_DATE_RANGE, DATE_RANGE_TOO_LONG, INVALID_GROUP_BY o INVALID_PROFESSIONAL_ID401Token ausente, inválido, revocado o caducado403Token sin permiso metrics:read404PROFESSIONAL_NOT_FOUND: el profesional no tiene agenda en la clínica429Límite de 120 peticiones por minuto y token superado
Qué hacer ante cada error: Idempotencia y errores.
Novedades
Cada cambio de la API se anota aquí el día que se publica.
En las clínicas de Canarias, las horas de citas y huecos de
/bookingy eldatetimede GET /events son el instante real de la cita (antes salían una hora antes) y lo que se envía (starts_at,from,to) se interpreta igual. GET /booking/availability/summary da por defecto las horas locales en la zona de la clínica (Atlantic/Canaryen Canarias). En el resto de clínicas no cambia nada.Las clínicas canarias facturan con IGIC (tipos 0, 3 y 7 en los mismos campos
vat_*). GET /invoices añadeindirect_tax: el impuesto con el que se emitió cada factura,ivaoigic.La disponibilidad (GET /booking/availability y GET /booking/availability/summary) respeta el ajuste de la clínica de no dejar elegir profesional en su reserva online: con él,
professional_idresponde422 PROFESSIONAL_CHOICE_DISABLEDy sale un solo hueco por hora y sede, con uno de los profesionales libres. Nuevo filtroappointment_idpara mover una cita: da los huecos de su profesional y su sede, también en esas clínicas, y la propia cita no cuenta como ocupada (moverla media hora sale como hueco).Lo cobrado de cada bono en GET /bonus-assignments (
amount_paid,paid_in_full,payment_method,invoice_idypurchase_reference) y el filtroinvoice_idrequierenfinance:read, como el resto de cobros de la API. Con solobonuses:readel listado no trae esos campos y filtrar porinvoice_idresponde403. Precio, IVA y créditos no cambian.La nota de la reserva de una cita no pasa de 8.000 caracteres en total: POST /booking/appointments/{appointment_id}/note responde
400 NOTE_TOO_LONGsi la línea nueva no cabe.Notas del cliente en sus citas: POST /booking/appointments admite
note(opcional, hasta 2.000 caracteres) y el nuevo POST /booking/appointments/{appointment_id}/note (permisocalendar:write, conIdempotency-Key) la añade después en una línea nueva. Es la nota de la reserva que ve solo el personal de la clínica.POST /booking/reception-followup admite
caller_name,client_id,noteycallback_preference, opcionales. Se ven al abrir el aviso en Tactivo, no en el push.Nuevo GET /booking/availability/summary (permiso
calendar:read) para agentes de voz y chat: las horas libres por día en hora local y una página de huecos reservables, con zona horaria e idioma (es,en) a elegir yexclude_professional_idpara no ofrecer a ciertos profesionales por ese canal.GET /booking/availability añade
min_notice_hours, la antelación mínima de reserva de la clínica en horas. No se devuelven huecos que empiecen antes de ahora más esa antelación, así que un día sin huecos puede deberse a ella y no a una agenda llena.Al facturar una cita o un bono se aplica el IVA vigente de su servicio o bono en el catálogo (GET /services, GET /bonuses);
service_snapshot_vat_percentagede GET /events yvat_percentagede GET /bonus-assignments siguen siendo el IVA de cuando se crearon. Lo ya facturado no cambia.POST /booking/clients/search por nombre exige nombre y apellido juntos (al menos 2 letras cada uno); un nombre o un apellido sueltos devuelven una lista vacía. Teléfono y DNI no cambian.
Nuevo GET /subscription-charges (permiso
finance:read): cuotas mensuales de suscripción de los clientes con importe, IVA, lo cobrado y su estado. GET /clients incluye elidde cada ficha (el que usan citas, bonos y cuotas) y filtra por él. GET /events (confinance:read) y GET /bonus-assignments añaden el IVA aplicado a cada cita y bono vendido.Nuevo GET /cash-movements (permiso
finance:read): movimientos de Caja con fecha, importe, forma de pago y origen (cita, bono, cuota, venta, factura o entidad), incluidos los pagos parciales de un bono y las devoluciones. GET /services añadevat_percentage.Tope de 2.000 escrituras nuevas cada 24 horas por clave (altas y cambios de clientes, citas y bonos). Por encima responde
429 DAILY_WRITE_LIMIT; repetir una petición con la mismaIdempotency-Keyno cuenta.Nuevo GET /entities (permiso
finance:read): entidades de la clínica (mutuas, aseguradoras, federaciones, clubes…) con sus datos fiscales, la retención de IRPF que practican y los clientes que las tienen como responsable de facturación.