Tactivo

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.

Descargar openapi.jsonOpenAPI 3.1 · 46 endpoints · JSON sobre HTTPS

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_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2

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

Petición
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. 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. 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. 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.

PermisoDa 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:59Z

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

  • amount es 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, -40 con TPV y +40 con Efectivo).
  • source_type dice de dónde viene el dinero y qué identificador lo enlaza:
source_typeOrigenIdentificador
appointmentCitasource_event_id (GET /events)
bonus_assignmentVenta de un bonosource_bonus_assignment_id (GET /bonus-assignments)
class_subscriptionCuota mensual de una suscripciónsource_class_subscription_charge_id (GET /subscription-charges)
inventory_saleVenta de productossource_inventory_sale_id (GET /inventory-sales)
free_invoiceFactura libresource_invoice_id (GET /invoices)
entity_receivablePago 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ónContenido
GET /bonusesCatá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ónContenido
GET /subscription-plansPlanes: nombre, precio mensual y límite semanal.
GET /subscription-plan-servicesServicios 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=month
  • from y to son obligatorios (Europe/Madrid, ambos incluidos): hasta 366 días, o 92 con group_by=day.
  • group_by: professional (por defecto, una fila por profesional), day, week (lunes a domingo) o month; professional_id limita 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_pct es ocupado ÷ disponible × 100, con un decimal, y es null si todo el horario estaba bloqueado (vacaciones). totals suma 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_id que 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 (from y to de 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" }
HTTPActuación recomendada
400Corregir parámetros o cuerpo
401Revisar la credencial o contactar con soporte
403Solicitar permiso para esa área
409Resolver duplicado, idempotencia o consultar otro hueco
422Derivar la operación a recepción
429Reintentar con espera exponencial
5xxReintentar 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 endpoints

GET
/health

Estado de la API

Público: no necesita token.
Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/health"
Respuestas
  • 200Estado básico de la API
  • 4XXPetición no admitida por el gateway

Qué hacer ante cada error: Idempotencia y errores.

GET
/openapi.json

Contrato OpenAPI 3.1

Público: no necesita token.
Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/openapi.json"
Respuestas
  • 200Contrato público vigente
  • 4XXPetición no admitida por el gateway

Qué hacer ante cada error: Idempotencia y errores.

Clínica

1 endpoint

GET
/company

Datos de la clínica

Permiso:
company:read

Devuelve la configuración principal de la clínica asociada al token.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/company" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Respuestas
  • 200Clínica encontrada.object
    • dataobjectobligatorio
  • 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 endpoints

GET
/clients

Permiso:
clients:read

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.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/clients" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de cliente.

  • client_numberstringen la consulta

    Filtra por número de cliente.

  • created_datestringen la consulta

    Filtra clientes creados en una fecha YYYY-MM-DD.

  • qstringen la consulta

    Busca por nombre, apellidos, email o teléfono.

  • is_guestbooleanen la consulta

    Filtra por invitado true/false.

  • treatment_statusstringen la consulta

    Filtra por estado de tratamiento.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
clients:write

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.

Petición de ejemplo (entorno de pruebas)
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-Keystringcabeceraobligatorio

    Identificador ú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"]}

  • namestringobligatorio
  • last_namestringobligatorio
  • phonestringobligatorio

    Número de teléfono válido, con o sin prefijo internacional. Ejemplo: +34600111222.

  • emailstring (email) | null
  • dnistring | null
  • genderstring | null

    Sexo del cliente.

    Valores: hombre, mujer, null

  • birth_datestring (date) | null

    Fecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.

    Ejemplo: 1990-05-12

  • addressstring | null

    Dirección.

  • occupationstring | null

    Ocupación.

  • sportstring | null

    Actividad física.

  • originsarray<string> | null

    Orí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 | null

    Nombre y apellidos del responsable legal del menor.

  • legal_guardian_identity_document_typestring | null

    Tipo de documento del responsable legal.

    Valores: dni, nie, null

  • legal_guardian_identity_numberstring | null

    Número de documento del responsable legal.

  • billing_info_enabledboolean

    Activa el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales.

  • billing_namestring | null

    Nombre del responsable de facturación.

  • billing_last_namestring | null

    Apellidos del responsable de facturación.

  • billing_tax_idstring | null

    NIF del responsable de facturación.

  • billing_addressstring | null

    Dirección del responsable de facturación.

  • review_opt_outboolean

    Excluye al cliente de las solicitudes de valoración.

Respuestas
  • 201Cliente creadoobject
    • dataobjectobligatorio

      Ficha 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)obligatorio
      • client_numberstringobligatorio

        Ejemplo: 00006

      • createdstring (date) | null

        Ejemplo: 2026-09-18

      • namestringobligatorio

        Ejemplo: María

      • last_namestringobligatorio

        Ejemplo: López

      • phonestring | null

        Ejemplo: +34600111222

      • emailstring (email) | null

        Ejemplo: maria@example.com

      • dnistring | null

        Ejemplo: 12345678Z

      • is_guestfalseobligatorio
      • genderstring | null

        Sexo del cliente.

        Valores: hombre, mujer, null

      • birth_datestring (date) | null

        Fecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.

        Ejemplo: 1990-05-12

      • addressstring | null

        Dirección.

      • occupationstring | null

        Ocupación.

      • sportstring | null

        Actividad física.

      • originsarray<string>

        Etiquetas de origen del catálogo de la clínica.

        Ejemplo: ["Google"]

      • legal_guardian_namestring | null

        Nombre y apellidos del responsable legal del menor.

      • legal_guardian_identity_document_typestring | null

        Tipo de documento del responsable legal.

        Valores: dni, nie, null

      • legal_guardian_identity_numberstring | null

        Número de documento del responsable legal.

      • billing_info_enabledboolean

        Activa el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales.

      • billing_namestring | null

        Nombre del responsable de facturación.

      • billing_last_namestring | null

        Apellidos del responsable de facturación.

      • billing_tax_idstring | null

        NIF del responsable de facturación.

      • billing_addressstring | null

        Dirección del responsable de facturación.

      • review_opt_outboolean

        Excluye al cliente de las solicitudes de valoración.

      • treatment_statusstring | null

        Valores: en_tratamiento, alta_parcial, alta, null

      • has_accountboolean

        True si el cliente tiene cuenta de usuario; en ese caso el email no se puede editar.

  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 409Cliente duplicado o conflicto de idempotencia
  • 429Lí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

Permiso:
clients:read

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.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/clients/CLIENT_NUMBER" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • client_numberstringen la rutaobligatorio

    Número de cliente visible en la clínica (ej. 00006).

    Formato: ^[A-Za-z0-9]+$

Respuestas
  • 200Cliente encontrado.object
    • dataobjectobligatorio
  • 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

Permiso:
clients:write

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.

Petición de ejemplo (entorno de pruebas)
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 rutaobligatorio

    Número de cliente visible en la clínica (ej. 00006).

    Formato: ^[A-Za-z0-9]+$

  • Idempotency-Keystringcabeceraobligatorio

    Identificador ú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 | null
  • last_namestring | null
  • phonestring | null

    Número válido, o null para vaciarlo. Un valor incompleto devuelve CLIENT_PHONE_INVALID.

  • emailstring (email) | null
  • dnistring | null
  • genderstring | null

    Sexo del cliente.

    Valores: hombre, mujer, null

  • birth_datestring (date) | null

    Fecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.

    Ejemplo: 1990-05-12

  • addressstring | null

    Dirección.

  • occupationstring | null

    Ocupación.

  • sportstring | null

    Actividad física.

  • originsarray<string> | null

    Orí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 | null

    Nombre y apellidos del responsable legal del menor.

  • legal_guardian_identity_document_typestring | null

    Tipo de documento del responsable legal.

    Valores: dni, nie, null

  • legal_guardian_identity_numberstring | null

    Número de documento del responsable legal.

  • billing_info_enabledboolean

    Activa el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales.

  • billing_namestring | null

    Nombre del responsable de facturación.

  • billing_last_namestring | null

    Apellidos del responsable de facturación.

  • billing_tax_idstring | null

    NIF del responsable de facturación.

  • billing_addressstring | null

    Dirección del responsable de facturación.

  • review_opt_outboolean

    Excluye al cliente de las solicitudes de valoración.

Respuestas
  • 200Cliente actualizadoobject
    • dataobjectobligatorio

      Ficha 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)obligatorio
      • client_numberstringobligatorio

        Ejemplo: 00006

      • createdstring (date) | null

        Ejemplo: 2026-09-18

      • namestringobligatorio

        Ejemplo: María

      • last_namestringobligatorio

        Ejemplo: López

      • phonestring | null

        Ejemplo: +34600111222

      • emailstring (email) | null

        Ejemplo: maria@example.com

      • dnistring | null

        Ejemplo: 12345678Z

      • is_guestfalseobligatorio
      • genderstring | null

        Sexo del cliente.

        Valores: hombre, mujer, null

      • birth_datestring (date) | null

        Fecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.

        Ejemplo: 1990-05-12

      • addressstring | null

        Dirección.

      • occupationstring | null

        Ocupación.

      • sportstring | null

        Actividad física.

      • originsarray<string>

        Etiquetas de origen del catálogo de la clínica.

        Ejemplo: ["Google"]

      • legal_guardian_namestring | null

        Nombre y apellidos del responsable legal del menor.

      • legal_guardian_identity_document_typestring | null

        Tipo de documento del responsable legal.

        Valores: dni, nie, null

      • legal_guardian_identity_numberstring | null

        Número de documento del responsable legal.

      • billing_info_enabledboolean

        Activa el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales.

      • billing_namestring | null

        Nombre del responsable de facturación.

      • billing_last_namestring | null

        Apellidos del responsable de facturación.

      • billing_tax_idstring | null

        NIF del responsable de facturación.

      • billing_addressstring | null

        Dirección del responsable de facturación.

      • review_opt_outboolean

        Excluye al cliente de las solicitudes de valoración.

      • treatment_statusstring | null

        Valores: en_tratamiento, alta_parcial, alta, null

      • has_accountboolean

        True si el cliente tiene cuenta de usuario; en ese caso el email no se puede editar.

  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 404Cliente no encontrado
  • 409DNI duplicado, email bloqueado por cuenta de usuario o conflicto de idempotencia
  • 429Límite de 120 peticiones por minuto y token superado

Qué hacer ante cada error: Idempotencia y errores.

Reservas (flujo de agenda)

13 endpoints

POST
/booking/appointments

Crear cita pendiente y sin cobrar

Permiso:
calendar:write
Petición de ejemplo (entorno de pruebas)
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-Keystringcabeceraobligatorio

    Identificador ú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)obligatorio
  • service_idstring (uuid)obligatorio
  • professional_idstring (uuid)obligatorio
  • location_idstring (uuid) | null
  • starts_atstring (date-time)obligatorio
  • notestring

    Nota 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 creadaobject
    • dataobjectobligatorio
      13 campos dentro de data
      • idstring (uuid)obligatorio
      • client_idstring (uuid)
      • starts_atstring (date-time)obligatorio

        Ejemplo: 2026-09-01T10:00:00+02:00

      • ends_atstring (date-time)obligatorio

        Ejemplo: 2026-09-01T11:00:00+02:00

      • statusstringobligatorio

        Ejemplo: pendiente

      • service_idstring (uuid) | null
      • service_namestring | null
      • professional_idstring (uuid) | null
      • professional_namestring | null
      • location_idstring (uuid) | null
      • location_namestring | null
      • modifiableboolean
      • restriction_codestring | null

        Ejemplo: null

  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 409Hueco ocupado o conflicto de idempotencia
  • 422Combinación no reservable
  • 429Lí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

Permiso:
calendar:write
Petición de ejemplo (entorno de pruebas)
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 rutaobligatorio
  • Idempotency-Keystringcabeceraobligatorio

    Identificador ú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)obligatorio
  • starts_atstring (date-time)obligatorio
Respuestas
  • 200Cita movidaobject
    • dataobjectobligatorio
      13 campos dentro de data
      • idstring (uuid)obligatorio
      • client_idstring (uuid)
      • starts_atstring (date-time)obligatorio

        Ejemplo: 2026-09-01T10:00:00+02:00

      • ends_atstring (date-time)obligatorio

        Ejemplo: 2026-09-01T11:00:00+02:00

      • statusstringobligatorio

        Ejemplo: pendiente

      • service_idstring (uuid) | null
      • service_namestring | null
      • professional_idstring (uuid) | null
      • professional_namestring | null
      • location_idstring (uuid) | null
      • location_namestring | null
      • modifiableboolean
      • restriction_codestring | null

        Ejemplo: null

  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 409Hueco ocupado o conflicto de idempotencia
  • 422La cita requiere recepción
  • 429Lí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

Permiso:
calendar:write
Petición de ejemplo (entorno de pruebas)
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 rutaobligatorio
  • Idempotency-Keystringcabeceraobligatorio

    Identificador ú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)obligatorio
  • reasonstring

    Máximo 500 caracteres

Respuestas
  • 200Cita cancelada (o eliminada, según la clínica)object
    • dataobjectobligatorio
      5 campos dentro de data
      • idstring (uuid)obligatorio
      • client_idstring (uuid)obligatorio
      • status"cancelada"obligatorio
      • deletedbooleanobligatorio

        false: 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_cancelledboolean

        La cita ya estaba cancelada: no se repite ningún aviso.

  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 422La cita requiere recepción
  • 429Lí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

Permiso:
calendar:write

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.

Petición de ejemplo (entorno de pruebas)
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 rutaobligatorio
  • Idempotency-Keystringcabeceraobligatorio

    Identificador ú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)obligatorio
  • notestringobligatorio

    De 1 a 2000 caracteres

Respuestas
  • 200Nota añadidaobject
    • dataobject
      3 campos dentro de data
      • idstring (uuid)
      • client_idstring (uuid)
      • notedtrue
  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 409Cita cancelada o conflicto de idempotencia
  • 429Límite de 120 peticiones por minuto y token superado

Qué hacer ante cada error: Idempotencia y errores.

GET
/booking/availability

Huecos disponibles

Permiso:
calendar:read

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.

Petición de ejemplo (entorno de pruebas)
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 consultaobligatorio
  • fromstring (date)en la consultaobligatorio
  • tostring (date)en la consultaobligatorio
  • professional_idstring (uuid)en la consulta

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

    Para 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 concretosobject
    • dataarray<object>obligatorio
      6 campos dentro de data
      • starts_atstring (date-time)obligatorio

        Ejemplo: 2026-09-01T10:00:00+02:00

      • ends_atstring (date-time)obligatorio

        Ejemplo: 2026-09-01T11:00:00+02:00

      • professional_idstring (uuid)obligatorio
      • professional_namestringobligatorio

        Ejemplo: Ana García

      • location_idstring (uuid) | nullobligatorio
      • location_namestring | null

        Ejemplo: Clínica Centro

    • min_notice_hoursintegerobligatorio

      Antelació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álida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 429Límite de 120 peticiones por minuto y token superado

Qué hacer ante cada error: Idempotencia y errores.

GET
/booking/availability/summary

Huecos disponibles resumidos

Permiso:
calendar:read

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.

Petición de ejemplo (entorno de pruebas)
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 consultaobligatorio
  • fromstring (date)en la consultaobligatorio
  • tostring (date)en la consultaobligatorio
  • professional_idstring (uuid)en la consulta

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

    Para 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
  • timezonestringen la consulta

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

    Valores: es, en · Por defecto: es

  • offsetintegeren la consulta

    Por defecto: 0 · Mínimo: 0

  • exclude_professional_idstringen la consulta

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

    Por defecto: 16 · Mínimo: 1 · Máximo: 50

Respuestas
  • 200Horas por día y página de huecos reservablesobject
    • time_zonestringobligatorio
    • min_notice_hoursintegerobligatorio

      Mínimo: 0

    • bookable_fromobject

      Primera fecha y hora local reservable por la antelación mínima; solo si es mayor que cero.

      3 campos dentro de bookable_from
      • local_datestring
      • weekdaystring
      • local_timestring
    • total_slotsintegerobligatorio
    • truncatedboolean
    • complete_throughstring (date) | null

      Último día local con la lista completa cuando truncated=true.

    • daysarray<object>obligatorio
      3 campos dentro de days
      • datestring (date)
      • weekdaystring
      • timesstring

        Horas locales «HH:MM#índice» separadas por espacios.

    • offsetintegerobligatorio
    • has_morebooleanobligatorio
    • next_offsetinteger | nullobligatorio
    • slotsarray<object>obligatorio
      9 campos dentro de slots
      • indexinteger
      • local_datestring
      • weekdaystring
      • local_timestring
      • starts_at_for_bookingstring (date-time)

        Valor literal para starts_at al reservar o cambiar la cita.

      • professional_idstring (uuid)
      • professional_namestring | null
      • location_idstring (uuid) | null
      • location_namestring | null
  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 429Límite de 120 peticiones por minuto y token superado

Qué hacer ante cada error: Idempotencia y errores.

POST
/booking/clients

Crear invitado

Permiso:
clients:write

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.

Petición de ejemplo (entorno de pruebas)
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-Keystringcabeceraobligatorio

    Identificador ú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"]}

  • namestringobligatorio
  • last_namestringobligatorio
  • phonestringobligatorio

    Número de teléfono válido, con o sin prefijo internacional. Ejemplo: +34600111222.

  • emailstring (email) | null
  • dnistring | null
  • genderstring | null

    Sexo del cliente.

    Valores: hombre, mujer, null

  • birth_datestring (date) | null

    Fecha de nacimiento en formato YYYY-MM-DD. No se aceptan fechas futuras.

    Ejemplo: 1990-05-12

  • addressstring | null

    Dirección.

  • occupationstring | null

    Ocupación.

  • sportstring | null

    Actividad física.

  • originsarray<string> | null

    Orí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 | null

    Nombre y apellidos del responsable legal del menor.

  • legal_guardian_identity_document_typestring | null

    Tipo de documento del responsable legal.

    Valores: dni, nie, null

  • legal_guardian_identity_numberstring | null

    Número de documento del responsable legal.

  • billing_info_enabledboolean

    Activa el responsable de facturación en modo manual. Al desactivarlo se borran los datos manuales.

  • billing_namestring | null

    Nombre del responsable de facturación.

  • billing_last_namestring | null

    Apellidos del responsable de facturación.

  • billing_tax_idstring | null

    NIF del responsable de facturación.

  • billing_addressstring | null

    Dirección del responsable de facturación.

  • review_opt_outboolean

    Excluye al cliente de las solicitudes de valoración.

Respuestas
  • 201Cliente creadoobject
    • dataobjectobligatorio
      4 campos dentro de data
      • idstring (uuid)obligatorio
      • namestringobligatorio

        Ejemplo: María

      • last_namestringobligatorio

        Ejemplo: López

      • is_guesttrueobligatorio
  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 409Cliente duplicado o conflicto de idempotencia
  • 429Lí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

Permiso:
calendar:read
Petición de ejemplo (entorno de pruebas)
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 rutaobligatorio
  • fromstring (date-time)en la consulta
  • tostring (date-time)en la consulta
Respuestas
  • 200Citas de los próximos 90 díasobject
    • dataarray<object>obligatorio
      13 campos dentro de data
      • idstring (uuid)obligatorio
      • client_idstring (uuid)
      • starts_atstring (date-time)obligatorio

        Ejemplo: 2026-09-01T10:00:00+02:00

      • ends_atstring (date-time)obligatorio

        Ejemplo: 2026-09-01T11:00:00+02:00

      • statusstringobligatorio

        Ejemplo: pendiente

      • service_idstring (uuid) | null
      • service_namestring | null
      • professional_idstring (uuid) | null
      • professional_namestring | null
      • location_idstring (uuid) | null
      • location_namestring | null
      • modifiableboolean
      • restriction_codestring | null

        Ejemplo: null

  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 429Límite de 120 peticiones por minuto y token superado

Qué hacer ante cada error: Idempotencia y errores.

POST
/booking/clients/search

Buscar clientes

Permiso:
clients:read

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.

Petición de ejemplo (entorno de pruebas)
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"}

  • namestring
  • last_namestring
  • phonestring
  • dnistring
Respuestas
  • 200Candidatos mínimosobject
    • dataarray<object>obligatorio

      Máximo 10 elementos

      6 campos dentro de data
      • idstring (uuid)obligatorio
      • namestringobligatorio

        Ejemplo: María

      • last_namestringobligatorio

        Ejemplo: López

      • masked_phonestring | null

        Ejemplo: ******123

      • masked_dnistring | null

        Ejemplo: *****123

      • exact_matchbooleanobligatorio
    • ambiguousbooleanobligatorio
  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 429Límite de 120 peticiones por minuto y token superado

Qué hacer ante cada error: Idempotencia y errores.

GET
/booking/locations

Ubicaciones compatibles

Permiso:
catalog:read
Petición de ejemplo (entorno de pruebas)
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 consultaobligatorio
  • professional_idstring (uuid)en la consulta
Respuestas
  • 200Ubicacionesobject
    • dataarray<object>obligatorio
      2 campos dentro de data
      • idstring (uuid)obligatorio
      • namestringobligatorio

        Ejemplo: Clínica Centro

  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 429Límite de 120 peticiones por minuto y token superado

Qué hacer ante cada error: Idempotencia y errores.

GET
/booking/professionals

Profesionales compatibles

Permiso:
catalog:read
Petición de ejemplo (entorno de pruebas)
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
  • 200Profesionalesobject
    • dataarray<object>obligatorio
      2 campos dentro de data
      • idstring (uuid)obligatorio
      • namestringobligatorio

        Ejemplo: Ana García

  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 429Lí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

Permiso:
calendar:write

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.

Petición de ejemplo (entorno de pruebas)
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_idstringobligatorio

    De 8 a 120 caracteres

  • callback_phonestring

    Máximo 30 caracteres

  • reasonstringobligatorio

    Valores: booking_help, change_help, question, other

  • caller_namestring

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

  • notestring

    Qué necesita, en una o dos frases.

    Máximo 500 caracteres

  • callback_preferencestring

    Cuándo prefiere que le llamen, por ejemplo «por la tarde».

    Máximo 120 caracteres

Respuestas
  • 200Aviso creado o llamada ya notificadaobject
    • dataobject
      1 campo dentro de data
      • notifiedinteger
  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 429Límite de 120 peticiones por minuto y token superado

Qué hacer ante cada error: Idempotencia y errores.

GET
/booking/services

Servicios reservables

Permiso:
catalog:read

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.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/booking/services" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Respuestas
  • 200Catálogoobject
    • dataarray<object>obligatorio
      3 campos dentro de data
      • idstring (uuid)obligatorio
      • namestringobligatorio

        Ejemplo: Fisioterapia

      • duration_minutesintegerobligatorio

        Mínimo: 1 · Ejemplo: 60

  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permisos para esta operación
  • 429Límite de 120 peticiones por minuto y token superado

Qué hacer ante cada error: Idempotencia y errores.

Agenda

1 endpoint

GET
/events

Permiso:
calendar:read

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.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/events" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de evento.

  • typestringen la consulta

    Filtra por tipo appointment/class/block.

  • statusstringen la consulta

    Filtra por appointment_status.

  • paidbooleanen la consulta

    Filtra por pagado true/false. Requiere finance:read.

  • client_idstringen la consulta

    Filtra por cliente contenido en el array client.

  • professional_idstringen la consulta

    Filtra por profesional contenido en el array professional.

  • service_idstringen la consulta

    Filtra por ID de servicio.

  • location_idstringen la consulta

    Filtra por ID de ubicación.

  • room_idstringen la consulta

    Filtra por ID de sala.

  • fromstringen la consulta

    Fecha/hora ISO mínima de datetime.

  • tostringen la consulta

    Fecha/hora ISO máxima de datetime.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

        Mí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 endpoints

GET
/company-schedules

Permiso:
catalog:read

Horario general de la clínica.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/company-schedules" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
catalog:read

Ubicaciones de la clínica.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/locations" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de ubicación.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
catalog:read

Relación entre profesionales y ubicaciones.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/professional-locations" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • professional_idstringen la consulta

    Filtra por profesional.

  • location_idstringen la consulta

    Filtra por ubicación.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
catalog:read

Horarios por profesional.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/professional-schedules" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • professional_idstringen la consulta

    Filtra por profesional.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
catalog:read

Relación entre profesionales y servicios.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/professional-services" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • professional_idstringen la consulta

    Filtra por profesional.

  • service_idstringen la consulta

    Filtra por servicio.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
catalog:read

Salas de la clínica.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/rooms" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de sala.

  • location_idstringen la consulta

    Filtra por ubicación.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
catalog:read

Relación entre servicios y ubicaciones.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/service-locations" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • service_idstringen la consulta

    Filtra por servicio.

  • location_idstringen la consulta

    Filtra por ubicación.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
catalog:read

Catálogo de servicios de la clínica.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/services" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de servicio.

  • service_typestringen la consulta

    Filtra por tipo de servicio.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
catalog:read

Miembros de staff: admin, coordinator y professional.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/staff" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de profesional.

  • qstringen la consulta

    Busca por nombre, apellidos, email o teléfono.

  • rolestringen la consulta

    Filtra por rol staff.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
catalog:read

Servicios de clase incluidos en cada plan de suscripción del catálogo.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/subscription-plan-services" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • plan_idstringen la consulta

    Filtra por ID de plan.

  • service_idstringen la consulta

    Filtra por ID de servicio.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
catalog:read

Catálogo de planes de suscripción de clase. No incluye altas de clientes ni cobros.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/subscription-plans" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de plan.

  • statusstringen la consulta

    Filtra por estado del plan.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

        Mí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 endpoints

GET
/bonus-assignments

Permiso:
bonuses:read

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.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/bonus-assignments" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de asignación.

  • bonus_idstringen la consulta

    Filtra por ID de bono.

  • client_idstringen la consulta

    Filtra por ID de cliente.

  • invoice_idstringen la consulta

    Filtra por ID de factura. Requiere finance:read.

  • statusstringen la consulta

    Filtra por estado.

  • fromstringen la consulta

    Fecha/hora ISO mínima de assigned_at.

  • tostringen la consulta

    Fecha/hora ISO máxima de assigned_at.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
bonuses:write

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.

Petición de ejemplo (entorno de pruebas)
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-Keystringcabeceraobligatorio

    Identificador ú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_numberstringobligatorio

    Número visible del cliente dentro de la clínica.

    Formato: ^[A-Za-z0-9]+$ · Ejemplo: 00006

  • bonus_idstring (uuid)obligatorio

    Identificador devuelto por GET /bonuses.

  • starts_onstring (date) | null

    Primer 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 cobroobject
    • dataobjectobligatorio
      17 campos dentro de data
      • idstring (uuid)obligatorio
      • client_idstring (uuid)obligatorio
      • client_numberstringobligatorio
      • bonus_idstring (uuid)obligatorio
      • bonus_namestringobligatorio
      • statusstringobligatorio

        Valores: active

      • assigned_atstring (date-time)
      • starts_onstring (date)
      • expires_onstring (date) | null
      • pricenumberobligatorio
      • amount_paid0obligatorio
      • paid_in_fullbooleanobligatorio
      • payment_methodnull
      • initial_creditsintegerobligatorio
      • remaining_creditsintegerobligatorio
      • regularized_class_creditsinteger
      • regularized_appointmentsinteger
  • 400Petición inválida
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permiso para asignar bonos
  • 404Cliente o bono no encontrado
  • 409Conflicto de idempotencia
  • 422El bono no tiene créditos de servicio configurados
  • 429Límite de 120 peticiones por minuto y token superado

Qué hacer ante cada error: Idempotencia y errores.

GET
/bonus-service-credits

Permiso:
bonuses:read

Detalle de créditos por servicio dentro de cada bono.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/bonus-service-credits" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • bonus_idstringen la consulta

    Filtra por ID de bono.

  • service_idstringen la consulta

    Filtra por ID de servicio.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
bonuses:read

Catálogo de bonos de la clínica.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/bonuses" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de bono.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

        Mí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 endpoints

GET
/cash-movements

Permiso:
finance:read

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.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/cash-movements" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de movimiento.

  • source_typestringen la consulta

    Filtra por origen: appointment, bonus_assignment, class_subscription, inventory_sale, free_invoice, entity_receivable.

  • payment_methodstringen la consulta

    Filtra por forma de pago (Efectivo, TPV, Bizum...).

  • event_idstringen la consulta

    Filtra por ID de cita.

  • bonus_assignment_idstringen la consulta

    Filtra por ID de bono vendido.

  • fromstringen la consulta

    Fecha/hora ISO mínima de occurred_at.

  • tostringen la consulta

    Fecha/hora ISO máxima de occurred_at.

  • created_fromstringen la consulta

    Fecha/hora ISO mínima de created_at (cuándo se registró en Tactivo).

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
finance:read

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.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/entities" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de entidad.

  • qstringen la consulta

    Busca por nombre o NIF.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
finance:read

Consumos de bonos aplicados a eventos.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/event-bonus-usages" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • event_idstringen la consulta

    Filtra por ID de evento.

  • client_idstringen la consulta

    Filtra por ID de cliente.

  • assignment_idstringen la consulta

    Filtra por ID de asignación de bono.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
finance:read

Gastos de la clínica sin adjuntos ni notas libres.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/expenses" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de gasto.

  • typestringen la consulta

    Filtra por tipo puntual/recurrente.

  • categorystringen la consulta

    Filtra por categoría.

  • fromstringen la consulta

    Fecha/hora ISO mínima de occurred_at.

  • tostringen la consulta

    Fecha/hora ISO máxima de occurred_at.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
finance:read

Líneas de detalle de ventas de inventario.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/inventory-sale-lines" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • sale_idstringen la consulta

    Filtra por ID de venta.

  • product_idstringen la consulta

    Filtra por ID de producto.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
finance:read

Ventas de inventario de la clínica.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/inventory-sales" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de venta.

  • client_idstringen la consulta

    Filtra por ID de cliente.

  • invoice_idstringen la consulta

    Filtra por ID de factura.

  • statusstringen la consulta

    Filtra por estado.

  • fromstringen la consulta

    Fecha/hora ISO mínima de sold_at.

  • tostringen la consulta

    Fecha/hora ISO máxima de sold_at.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
finance:read

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.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/invoices" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de factura.

  • recipient_idstringen la consulta

    Filtra por ID de destinatario.

  • statusstringen la consulta

    Filtra por estado.

  • fromstringen la consulta

    Fecha mínima YYYY-MM-DD de issue_date.

  • tostringen la consulta

    Fecha máxima YYYY-MM-DD de issue_date.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

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

Permiso:
finance:read

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.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/subscription-charges" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID de cuota.

  • client_idstringen la consulta

    Filtra por ID de cliente.

  • statusstringen la consulta

    Filtra por estado.

  • fromstringen la consulta

    Mes mínimo YYYY-MM-DD de period_month.

  • tostringen la consulta

    Mes máximo YYYY-MM-DD de period_month.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

        Mí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 endpoint

GET
/work-logs

Permiso:
worklogs:read

Registros de fichaje sin notas libres.

Petición de ejemplo (entorno de pruebas)
curl "https://hzztmtkdaofrwcwzotas.supabase.co/functions/v1/external-api/v1/work-logs" \
  -H "Authorization: Bearer ta_api_17692d0692e6538c4169a89fe8ac81df2a40e07c2f952ff2"
Parámetros
  • limitintegeren la consulta

    Nú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 consulta

    Desplazamiento de página para paginación por offset.

    Por defecto: 0 · Mínimo: 0

  • idstringen la consulta

    Filtra por ID del registro.

  • professional_idstringen la consulta

    Filtra por profesional.

  • fromstringen la consulta

    Fecha mínima YYYY-MM-DD de work_date.

  • tostringen la consulta

    Fecha máxima YYYY-MM-DD de work_date.

Respuestas
  • 200Listado paginado.object
    • dataarray<object>obligatorio
    • paginationobjectobligatorio
      3 campos dentro de pagination
      • limitintegerobligatorio

        Mínimo: 1 · Máximo: 200

      • offsetintegerobligatorio

        Mínimo: 0

      • next_offsetinteger | nullobligatorio

        Mí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 endpoint

GET
/occupancy

Ocupación por profesional

Permiso:
metrics:read

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.

Petición de ejemplo (entorno de pruebas)
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 consultaobligatorio

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

    professional: 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 consulta

    Solo este profesional (identificador de GET /staff).

Respuestas
  • 200Ocupación del periodoobject
    • fromstring (date)obligatorio
    • tostring (date)obligatorio
    • group_bystringobligatorio

      Valores: professional, day, week, month

    • dataarray<object>obligatorio
      11 campos dentro de data
      • professional_idstring (uuid)obligatorio
      • professional_namestringobligatorio
      • period_startstring (date)obligatorio
      • period_endstring (date)obligatorio
      • working_daysintegerobligatorio

        Días con horario de cada profesional que suma la fila.

      • scheduled_minutesnumberobligatorio
      • blocked_minutesnumberobligatorio
      • available_minutesnumberobligatorio
      • occupied_minutesnumberobligatorio
      • free_minutesnumberobligatorio
      • occupancy_pctnumber | nullobligatorio
    • totalsobjectobligatorio

      Todo el equipo considerado en el periodo.

      7 campos dentro de totals
      • working_daysintegerobligatorio

        Días con horario de cada profesional que suma la fila.

      • scheduled_minutesnumberobligatorio
      • blocked_minutesnumberobligatorio
      • available_minutesnumberobligatorio
      • occupied_minutesnumberobligatorio
      • free_minutesnumberobligatorio
      • occupancy_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_ID
  • 401Token ausente, inválido, revocado o caducado
  • 403Token sin permiso metrics:read
  • 404PROFESSIONAL_NOT_FOUND: el profesional no tiene agenda en la clínica
  • 429Lí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.

  1. En las clínicas de Canarias, las horas de citas y huecos de /booking y el datetime de 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/Canary en Canarias). En el resto de clínicas no cambia nada.

  2. Las clínicas canarias facturan con IGIC (tipos 0, 3 y 7 en los mismos campos vat_*). GET /invoices añade indirect_tax: el impuesto con el que se emitió cada factura, iva o igic.

  3. 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_id responde 422 PROFESSIONAL_CHOICE_DISABLED y sale un solo hueco por hora y sede, con uno de los profesionales libres. Nuevo filtro appointment_id para 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).

  4. Lo cobrado de cada bono en GET /bonus-assignments (amount_paid, paid_in_full, payment_method, invoice_id y purchase_reference) y el filtro invoice_id requieren finance:read, como el resto de cobros de la API. Con solo bonuses:read el listado no trae esos campos y filtrar por invoice_id responde 403. Precio, IVA y créditos no cambian.

  5. 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_LONG si la línea nueva no cabe.

  6. 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 (permiso calendar:write, con Idempotency-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.

  7. POST /booking/reception-followup admite caller_name, client_id, note y callback_preference, opcionales. Se ven al abrir el aviso en Tactivo, no en el push.

  8. 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 y exclude_professional_id para no ofrecer a ciertos profesionales por ese canal.

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

  10. 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_percentage de GET /events y vat_percentage de GET /bonus-assignments siguen siendo el IVA de cuando se crearon. Lo ya facturado no cambia.

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

  12. 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 el id de cada ficha (el que usan citas, bonos y cuotas) y filtra por él. GET /events (con finance:read) y GET /bonus-assignments añaden el IVA aplicado a cada cita y bono vendido.

  13. 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ñade vat_percentage.

  14. 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 misma Idempotency-Key no cuenta.

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