Facturar a clientes el uso de agentes

Si un agente trabaja para tus clientes, tarde o temprano hay que pasarles el consumo. AI Tasker no emite facturas ni gestiona tu margen, pero sí deja el rastro necesario para calcularlo: consumo por workspace, actividad por credencial y un libro de transacciones que no se borra. Esta guía es cómo leerlo sin inventarse nada y dónde está el límite de lo que la plataforma puede afirmar.

La unidad que se factura: el workspace

El workspace es la unidad de consumo, de cuota y de aislamiento. Si un cliente tiene su propio workspace, tienes el dato separado sin construir nada: no hace falta etiquetar cada operación con un cliente, porque el workspace ya lo es. La recomendación práctica es asignar un workspace por cliente y dejar los proyectos para la organización interna de ese cliente.

Dos clientes en un mismo workspace no se pueden separar después: el consumo se agrega a nivel de workspace y la actividad por clave no dice a qué cliente pertenece un proyecto. Repartir en workspaces desde el principio es mucho más barato que reconstruir el reparto a fin de mes.

Lectura 1: el consumo del periodo

GET /api/usage?period=YYYY-MM devuelve, por workspace, el plan aplicado, el cupo y lo consumido, más el desglose por credencial. Es la lectura que se usa para la línea "uso" de la factura.

Consumo de un periodo concreto.

curl -s "https://api.ai-tasker.theboomer.dev/api/usage?period=2026-10" \
  -H "x-api-key: atkr_tu_clave"

# {
#   "workspaceId": "...",
#   "plan": "free",
#   "period": "2026-10",
#   "quota": {
#     "agent":     { "limit": 100, "used": 87, "remaining": 13, "paidWithCredits": 4 },
#     "hosted_ai": { "limit": 100, "used": 12, "remaining": 88 }
#   },
#   "byAgent": [ { "apiKeyId": "...", "used": { "agent": 61, "hosted_ai": 0 } } ]
# }

quota.agent.used cuenta operaciones de agente del periodo (lecturas y mutaciones, una unidad cada una).
quota.hosted_ai.used cuenta las operaciones de IA alojada (planificar sprint, generar tareas, desglosar).
quota.agent.paidWithCredits es el número que casi nadie mira y explica el resto: operaciones que pagó el saldo del owner en vez de la cuota del plan. Sin ese campo, un agente que trabaja por encima del plan parece que no consume.
byAgent[].used reparte el mismo consumo por API key, que es lo que permite decir "este cliente gastó esto con este agente".

Lectura 2: la actividad de una credencial

Cuando el cliente pregunta "¿por qué me has cobrado esto?", la respuesta no está en el agregado sino en los eventos: qué método y qué ruta se llamó, y en qué franja.

Actividad de una clave en las últimas 168 horas.

curl -s "https://api.ai-tasker.theboomer.dev/api/apikeys/ID_DE_LA_CLAVE/usage?hours=168" \
  -H "x-api-key: atkr_tu_clave"

# { "total": 412, "buckets": [ { "bucket": "2026-10-26T10:00:00.000Z", "count": 37 } ], "events": [...] }

El rango de hours va de 1 a 720 (30 días). Los cubos son por hora hasta 48 horas y por día a partir de ahí, que es justo lo que hace falta para detectar un bucle de polling sin tener que abrir los eventos uno a uno.

Lectura 3: el rastro contable

El historial de créditos es la parte que sirve como prueba: cada compra, cada consumo y cada reembolso quedan registrados. Y hay una garantía que conviene saber: archivar o purgar un workspace por inactividad no toca el libro de transacciones, así que el histórico de un cliente sigue ahí aunque su workspace ya no exista.

Tipos de movimiento tal como aparecen en GET /api/credits/history.
Movimiento	Qué significa para la factura
Compra de pack	Ingreso de créditos del cliente; base de lo que puedes repercutir
`AGENT_OPERATION`	Consumo que pagó el saldo del owner porque la cuota del plan estaba agotada
`AGENT_OPERATION_REFUND`	Devolución de una operación fallida: no se factura
AutoRefill	Suscripción mensual que recarga; sube un 20 % al mes hasta el mes 12

Un reparto honesto en tres columnas

AI Tasker te da el consumo; el precio que pones encima es tuyo.
Concepto	Origen del dato	Se factura al cliente
Asientos (2,00 €/mes por unidad)	Facturación de AI Tasker: miembros, API keys y workspaces aprobados	Lo que decidas: es coste tuyo o repercutible
Operaciones de agente	`quota.agent.used` + `paidWithCredits`	Depende de tu modelo: por operación, por tramo o incluido
Operaciones de IA alojada	`quota.hosted_ai.used`	El coste real más alto; conviene facturarlo aparte
Créditos prepagados	`GET /api/credits/history`	Consumo ya cobrado por AI Tasker a ti (o al cliente, si tiene su cuenta)

Lo que AI Tasker no hace

No emite facturas a tus clientes. No hay documentos fiscales, ni IVA, ni series de numeración: eso vive en tu sistema de facturación.
No reparte por proyecto con fines de facturación. El desglose fiable es por workspace y por credencial; por debajo de eso, la atribución la pones tú.
No bloquea al cliente final. Los muros (cuota, guarda diaria, saldo) los recibe tu agente; si quieres cortar el servicio a un cliente, cortas la credencial o desenlazas el workspace.
No calcula tu margen. El precio de reventa, los tramos y los descuentos son decisión tuya.

Cierre de mes en cinco pasos

Fija el periodo en UTC (YYYY-MM) y usa el mismo en todas las lecturas: mezclar meses es el error que descuadra la primera factura.
Saca GET /api/usage?period=YYYY-MM por cada workspace de cliente y guarda la respuesta como evidencia del mes.
Cruza quota.agent.paidWithCredits con el historial de créditos: son las operaciones que la cuota no cubrió.
Guarda GET /api/apikeys/:id/usage de las claves de cada cliente si necesitas defender una línea concreta.
Archiva la evidencia fuera de AI Tasker: el libro de transacciones no se borra, pero tu factura debe poder explicarse sin acceso a la plataforma.

Los datos de uso son del workspace, y una clave puede alcanzar varios workspaces enlazados. Si compartes una credencial entre dos clientes, pierdes la atribución: no hay forma de separar después qué operación fue de quién.

Repercutir a un cliente el uso de agentes en AI Tasker

Separar el consumo por cliente, leer cuota y actividad por credencial, y guardar la evidencia del periodo antes de facturar.

Separa por cliente
Un workspace por cliente; los proyectos dentro, para organización interna.
Una credencial por agente
Cada agente con su API key, enlazada solo a los workspaces que necesita.
Lee el consumo del periodo
GET /api/usage?period=YYYY-MM por workspace: cuota, usado, restante y operaciones pagadas con créditos.
Guarda la evidencia
Exporta la respuesta y, si hace falta defender una línea, la actividad de la clave con GET /api/apikeys/:id/usage.
Cruza con el historial
GET /api/credits/history para compras, consumos y reembolsos: es el rastro que no se borra.
Factura en tu sistema
AI Tasker no emite la factura del cliente final: exporta los números y factura con tus impuestos y numeración.

Preguntas frecuentes

¿AI Tasker emite facturas a mis clientes?

No. AI Tasker factura al titular de la cuenta (asientos y créditos). La facturación al cliente final, con sus impuestos y numeración, es tuya.

¿Puedo saber cuánto consumió cada cliente?

Sí, si cada cliente tiene su workspace: GET /api/usage?period=YYYY-MM devuelve cuota y consumo por workspace y el desglose por API key.

¿Qué significa `paidWithCredits`?

Operaciones que se pagaron con el saldo del owner porque la cuota del plan estaba agotada. Sin ese número, un agente que trabaja por encima del plan parece no consumir.

¿El historial se pierde si archivo el workspace?

No. Archivar y purgar por inactividad no tocan el libro de transacciones: el histórico contable permanece.

¿Puedo facturar por proyecto?

El dato fiable es por workspace y por credencial. Para facturar por proyecto, separa los proyectos en workspaces distintos: AI Tasker no agrega consumo por proyecto.

¿Cómo corto el servicio a un cliente que no paga?

Revoca su API key (DELETE /api/apikeys/:id) o desenlaza su workspace de la credencial compartida. El resto de clientes sigue operando.

Fuentes

Planes, límites y operaciones (GET /api/plans)
https://api.ai-tasker.theboomer.dev/api/plans
Contrato OpenAPI de la API
https://api.ai-tasker.theboomer.dev/api/openapi.json
Endpoints de uso y créditos en /docs
https://api.ai-tasker.theboomer.dev/docs

Cifras verificadas contra la API en vivo y las páginas oficiales de cada producto el 21 de octubre de 2026. Los precios de terceros pueden cambiar: contrasta con la página oficial antes de publicar.

Guías relacionadas

Todas las guías — Cómo elegir gestor de tareas, MCP y ciclo de vida para agentes de IA.
Presupuesto y cuotas por agente — Cómo repartir créditos y cuotas entre varios workspaces y agentes en AI Tasker: qué devuelve cada muro, cómo leer el consumo y cómo cortar el gasto.
Monedero de créditos: recarga y control de gasto — Cómo funciona el monedero de AI Tasker: qué operación consume cada crédito, cómo recargar con packs o AutoRefill, y qué pasa cuando el saldo llega a cero.
Cómo se cobra el uso de agentes — Cómo AI Tasker mide y cobra el uso de agentes: unidad facturable de 2 €, operaciones, packs y recarga automática. Sin sorpresas.
Seguridad y aislamiento por workspace — El modelo de seguridad de AI Tasker: aislamiento por workspace, cifrado de credenciales, rotación de claves, cuotas y feed de auditoría con doble redacción.
Precios — Precios reales: plan gratuito y unidad facturable de 2,00 €/mes.
Integración MCP — https://mcp.ai-tasker.theboomer.dev/mcp
/llms.txt — Contrato legible por máquina.

Esta guía existe para ser indexada y citada. No está en el menú a propósito.