API · stats

GET /control/summary

Panel de control - snapshot con filtros (owner y manager; staff y viewer 403)

Snapshot de solo lectura del proyecto (F3-234), calculado en el servidor en una transacción con el tenant de la credencial, con una única vista temporal REPEATABLE READ para todos los bloques. Filtros (service_id, resource_id, from, to; días locales incluidos, por defecto hoy, máximo el mismo tope que /team/overview, 422 invalid_stats_range) para todos los bloques: servicio y persona limitan las tareas, los montos, los pagos en revisión y la saturación; las fechas, lo que tiene fecha. Atención ahora (es «ahora», sin fechas) - conversaciones que esperan respuesta (misma regla que «Necesita atención» del Inbox; no pertenecen a un servicio ni a una persona, no se filtran) y las derivadas por el bot (bot_handoff/bot_fallback), tareas por motivo con los mismos filtros de GET /work-items que usa Hoy (pueden solaparse: no se suman) y cobros electrónicos pending. En curso - tareas del período en pending_payment, confirmed o checked_in, por etapa nativa de cada servicio (service_id identifica la clave), según el estado real de la tarea. Números del período - agendadas, completadas y, con finance:analyze, vendido por fecha de trabajo y cobrado por fecha del pago (incluye tareas trabajadas fuera del período). Pagos en revisión sin fechas. (sin filtro, GET /payments/finance/summary; con servicio o persona, atribuidos a esas tareas) y por cobrar (saldo de cuentas al momento; null con filtro de servicio o persona), en unidad menor de currency. Saturación - ocupación (minutos reservados sobre disponibles del horario, como /resources/{id}/stats) por día de la semana y hora local, sumando los recursos activos con horario o el recurso filtrado. Permisos por bloque - sesión, control:read y la matriz por rol; API key, bookings:read, el bloque de conversaciones exige messages:read y el de dinero finance:analyze (sin ellos llegan null). Sin PII.

• Autenticación: Clave de API o sesión del panel
• Scopes: bookings:read, control:read, messages:read

Parámetros

Respuestas

GET /products/{id}/performance

Rendimiento de un producto en unidades y tareas por día, semana o mes, con el período anterior

F3-328. Rendimiento de un producto en CANTIDADES (nunca dinero: vive en Financiero). Panel: permiso performance:read (owner, manager y colaborador; no es de dinero; el colaborador solo sobre lo suyo: scope: own, las tareas asignadas a los recursos enlazados a su usuario, nunca los totales del negocio); API key: scope bookings:read (totales del negocio). Líneas del pedido de tareas completadas, no de prueba, con el criterio de GET /products/stats: units (por defecto, Σ qty) y tasks. Período anterior y tramos como en GET /services/{id}/performance. Máximo 366 días; una consulta agrupada.

• Autenticación: Clave de API o sesión del panel
• Scopes: performance:read, bookings:read

Parámetros

Respuestas

GET /resources/{id}/stats

Estadísticas de un recurso (owner, manager, staff solo el suyo; viewer 403)

Ocupación por día y, con granularity=hour, matriz día de la semana × hora local (mapa de calor); cantidad de agendas por estado y tasas de ausencia y cancelación; mezcla de servicios; y facturación (suma de price_cents de servicios completados, seña cobrada y pendiente, moneda del negocio). revenue es null para el rol staff. Las reservas is_test se excluyen. Otro tenant o, para staff, un recurso ajeno: 404. Mismas reglas de rango y ocupación que /team/overview.

• Autenticación: Clave de API o sesión del panel
• Scopes: bookings:read

Parámetros

Respuestas

GET /services/{id}/performance

Rendimiento de un servicio en cantidades por día, semana o mes, con el período anterior

F3-328. Rendimiento de un servicio en CANTIDADES (nunca dinero: vive en Financiero). Tenant desde la credencial, RLS. Panel: permiso performance:read (owner, manager y colaborador; no es de dinero). El colaborador lo tiene solo sobre lo suyo (scope: own: tareas asignadas a los recursos enlazados a su usuario; sin recurso propio, cero), nunca los totales del negocio, que son de owner y manager (scope: business); API key: scope bookings:read (totales del negocio). Tareas sin held/expired ni de prueba, atribuidas al día local de inicio/vencimiento. Métricas: completed (por defecto), tasks y cancelled (cancelada o no vino). previous: el mismo período corrido hacia atrás tantos tramos como abarca (día: N días; semana: N semanas; mes: N meses), así previous_series tiene los mismos tramos que series. Máximo 366 días; una consulta agrupada.

• Autenticación: Clave de API o sesión del panel
• Scopes: performance:read, bookings:read

Parámetros

Respuestas

GET /services/{id}/stats

Ventas y tendencia de un servicio

F3-90. Tenant desde credencial, RLS. Owner/manager o API key con bookings:read. Staff/viewer: 403. Fecha local de inicio/vencimiento; moneda del workspace. Dinero estimado con precio actual del catálogo y señas retenidas (F2-44/45), no charges. Máximo 366 días. Excluye datos de prueba, held y expired. units_sold informa un único campo con x-fiuit-unit; null si hay varios campos o ninguna unidad.

• Autenticación: Clave de API o sesión del panel
• Scopes: bookings:read

Parámetros

Respuestas

GET /services/stats

Resultados del período de todos los servicios

F3-90. Tenant desde credencial, RLS. Owner/manager o API key con bookings:read. Staff/viewer: 403. Fecha local de inicio/vencimiento; moneda del workspace. Dinero estimado con precio actual del catálogo y señas retenidas (F2-44/45), no charges. Máximo 366 días. Excluye datos de prueba, held y expired. units_sold informa un único campo con x-fiuit-unit; null si hay varios campos o ninguna unidad.

• Autenticación: Clave de API o sesión del panel
• Scopes: bookings:read

Parámetros

Respuestas

GET /team/overview

Resumen del equipo (owner, manager, staff solo lo suyo; viewer 403)

Una fila por recurso activo, con su persona si existe (solo los de tipo staff la tienen). Por defecto solo los de tipo staff (un negocio sin personas, con canchas o lugares, usa kind=all); kind=all devuelve todos los tipos activos y kind=<tipo> uno solo (Equipo y recursos). Staff solo ve sus recursos asignados. from/to son días locales del negocio, ambos incluidos (máximo 92 días, configurable; 422 invalid_stats_range si se pasa). occupancy = minutos reservados dentro del horario ÷ minutos disponibles (horario semanal con excepciones y bloqueos, en la zona horaria del negocio; los días de cambio de hora duran 23 o 25 h). Cuentan las reservas pending_payment, confirmed, checked_in y completed; no las canceladas, vencidas, ausencias, holds ni las de prueba. En recursos pooled son minutos-unidad (unidades × minutos ÷ capacidad × minutos disponibles). next_available_at: primer hueco libre de 15 min en los próximos 30 días (null si no hay horario); next_available_free_units dice cuántos lugares quedan ahí (un recurso pooled puede estar libre con tareas ya cargadas en esa hora). days: la ocupación de cada día del período. open_today: confirmadas o en curso que empiezan hoy. Sin facturación.

• Autenticación: Clave de API o sesión del panel
• Scopes: bookings:read

Parámetros

Respuestas

GET /work-items/outcomes

Cierres y cancelaciones por flujo y motivo

Cuenta entradas de historial en días locales del negocio (ambos incluidos), excluye pruebas. Agrupa claves estables por flujo y salida; etiquetas históricas, sin texto libre ni datos de clientes. Reintentar no duplica; reabrir y cerrar vuelve a contar. Owner/manager con finance:analyze; API key bookings:read.

• Autenticación: Clave de API o sesión del panel
• Scopes: bookings:read

Parámetros

Respuestas