Facturación
Plan, créditos, uso, movimientos de créditos y las operaciones de la suscripción del workspace.
Estas rutas dicen en qué plan está el workspace, cuántos créditos le quedan, cuánto uso de IA consumió y en qué se gastaron los créditos. Sirven para que una integración sepa, antes de lanzar una acción que consume créditos o uso, si el workspace tiene margen. Lo que cuesta cada acción y cómo se descuenta está en créditos y uso.
El uso de IA se informa siempre como una fracción de 0 a 1 (0.42 es el 42 %), nunca como un monto. Los créditos se informan en créditos.
Hay dos tipos de rutas:
- Lecturas. Algunas las puede hacer cualquier miembro (planes, paquetes de créditos, estado de uso); las que exponen datos de la cuenta (suscripción, saldo detallado, movimientos, método de pago, datos de facturación) son solo para OWNER: con la key de otro rol contestan
403 FORBIDDEN. - Operaciones de la cuenta. Contratar un plan, cambiarlo, cancelarlo, comprar créditos, abrir el portal de pagos o editar los datos de facturación son decisiones de una OWNER en persona, en la app. Por API contestan siempre
403 FORBIDDEN, aunque la key sea de una OWNER. Están al final de la página para que sepas qué esperar.
Estado de uso
GET /billing/usage-standing
/billing/usage-standingDónde está el workspace para la persona que llama: plan, uso consumido como fracción, cuándo se renueva y qué frenaría hoy cada tipo de acción. Lo puede leer cualquier miembro y es la lectura recomendada para decidir si lanzar una acción.
curl https://app.reclee.com/api/v1/billing/usage-standing \
-H "Authorization: Bearer rcl_..."{
"plan": "STARTER",
"position": "PAID",
"metered": true,
"trialUsed": true,
"trialEndsAt": null,
"periodEnd": "2026-11-03T00:00:00.000Z",
"maxSeats": 3,
"aiUsedPct": 0.42,
"teamUsedPct": 0.1,
"window": { "usedPct": 0.15, "endsAt": "2026-10-22T18:30:00.000Z" },
"teamWindow": { "usedPct": 0, "endsAt": null },
"assistBucket": "PLAN",
"assistBlock": null,
"aiBlock": null,
"scoreBlock": null,
"creditsLeft": 1840,
"revealCredits": { "EMAIL_WORK": 10, "EMAIL_PERSONAL": 10, "PHONE": 50 },
"spendingCredit": false,
"seats": 2,
"purchasedThisPeriod": null,
"seatHolders": null
}position:FREE,TRIAL,PAIDoCHURNED(volvió a FREE después de haber pagado).metered:falsesi el plan no mide uso; en ese caso nada se descuenta.aiUsedPct/teamUsedPct: uso del mes del plan y de la bolsa del equipo, de 0 a 1.window/teamWindow: la ventana de cinco horas;endsAtes cuándo devuelve el uso (nullsi no se usó nada en las últimas cinco horas).assistBlock,aiBlock,scoreBlock: el código que frenaría hoy, respectivamente, un pedido al asistente o una generación, una búsqueda o sourcing, y un match score;nullsi no hay freno. Valores posibles:USAGE_WINDOW,USAGE_EXHAUSTED,TEAM_USAGE_EXHAUSTED,TEAM_WINDOW,NO_CREDITS,SEAT_LIMIT.creditsLeft: créditos que todavía se pueden gastar en revelar contactos (los del plan más los comprados).revealCredits: cuántos créditos cuesta revelar cada tipo de contacto en este plan (los valores del ejemplo son ilustrativos).purchasedThisPeriodyseatHolderssolo vienen completos en casos puntuales (por ejemplo, cuando el mes del plan se agotó); si no,null.
Planes y paquetes
GET /billing/plans
/billing/plansLos planes pagos a la venta, del más barato al más caro, con el precio por asiento en cada intervalo. Cualquier miembro puede leerlos.
curl https://app.reclee.com/api/v1/billing/plans \
-H "Authorization: Bearer rcl_..."[
{
"plan": "STARTER",
"monthlyPerSeatUsd": 39,
"yearlyPerSeatUsd": 468,
"maxSeats": 3,
"trialDays": 14,
"aiUsagePerSeat": true,
"credits": 1000,
"creditsPerSeat": true
}
]yearlyPerSeatUsd es el precio del año entero por asiento, no un equivalente mensual. Los valores del ejemplo son ilustrativos: lee siempre la respuesta real. El catálogo público, sin key, está en GET /public/plans.
GET /billing/credits
/billing/creditsLos paquetes de créditos a la venta, de menor a mayor. Cualquier miembro puede leerlos.
curl https://app.reclee.com/api/v1/billing/credits \
-H "Authorization: Bearer rcl_..."[
{ "id": "6f1a3d8c-2e4b-4c9a-b7d5-0e8f2a1c3b49", "credits": 5000, "priceUsd": 50 }
]Comprar un paquete (POST /billing/credits) es una operación de la cuenta: ver más abajo.
Plan y saldo del workspace
Todas las rutas de esta sección son solo para OWNER.
GET /billing/entitlements
/billing/entitlementsEl plan del workspace, su estado, los asientos, las fechas del período y el saldo de créditos.
curl https://app.reclee.com/api/v1/billing/entitlements \
-H "Authorization: Bearer rcl_..."{
"plan": "PRO",
"status": "ACTIVE",
"metered": true,
"seats": 4,
"maxSeats": null,
"trialEndsAt": null,
"periodStart": "2026-10-03T00:00:00.000Z",
"periodEnd": "2026-11-03T00:00:00.000Z",
"position": "PAID",
"trialUsed": true,
"ai": { "usedPct": 0.42, "left": true },
"team": { "usedPct": 0.1, "left": true },
"planCredits": { "allowance": 8000, "used": 2150, "remaining": 5850 },
"purchasedCredits": 5000,
"purchasedHeld": 0,
"window": { "usedPct": 0.15, "spent": false, "endsAt": "2026-10-22T18:30:00.000Z" }
}El uso de IA se expresa siempre como fracción, nunca como monto: la respuesta no trae importes del consumo.
plan:FREE,STARTER,PRO,SCALEoINTERNAL.status:TRIALING,ACTIVE,PAST_DUEoCANCELED.planCredits: créditos que trae el plan en el período;remainingya descuenta las reservas abiertas.purchasedCredits: créditos comprados. No vencen, y pueden quedar en negativo después de un contracargo.purchasedHeldes la parte ya reservada por acciones en curso.ai/team: el uso del mes del plan y del cupo de equipo.usedPctva de 0 a 1;leftdice si queda algo, descontando las reservas abiertas.window: tu ventana de cinco horas.usedPctva de 0 a 1,spentestruecuando lo usado más lo reservado llegó al tope, yendsAtes cuándo se libera (nullsi no usaste nada en las últimas cinco horas).
GET /billing/subscription
/billing/subscriptionLo que la suscripción agrega a entitlements: el intervalo, el precio por asiento y una cancelación o un cambio de plan programados.
curl https://app.reclee.com/api/v1/billing/subscription \
-H "Authorization: Bearer rcl_..."{
"interval": "MONTH",
"monthlyPerSeatUsd": 79,
"cancelAtPeriodEnd": false,
"scheduledChange": {
"plan": "STARTER",
"interval": "MONTH",
"startsAt": "2026-11-03T00:00:00.000Z"
},
"scheduledChangeUnavailable": false,
"purchasedSpend": { "contacts": 1200, "ai": 300 },
"downgradeOffer": null
}monthlyPerSeatUsd: precio por asiento y por mes (en un plan anual, el año dividido por 12);nullsin plan pago.scheduledChange: un cambio a un plan menor programado para el fin del período;nullsi no hay. SischeduledChangeUnavailableestrue, no se pudo leer ynullno significa que no haya.purchasedSpend: créditos comprados gastados desde que existe el workspace, en contactos y en uso de IA.
GET /billing/credit-movements
/billing/credit-movementsLos movimientos de créditos del workspace, del más nuevo al más viejo. Pagina con page y pageSize, pero con su propio tamaño: hasta 100 por página, 20 por defecto. Ver paginación.
| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| page | integer | Opcional | Página, desde 1. Por defecto, 1. |
| pageSize | integer | Opcional | Filas por página, de 1 a 100. Por defecto, 20. |
curl "https://app.reclee.com/api/v1/billing/credit-movements?page=1&pageSize=20" \
-H "Authorization: Bearer rcl_..."{
"rows": [
{
"id": "b4d2f7a1-8c3e-4e6b-9f05-2a7c1d9e3b58",
"occurredAt": "2026-10-21T15:12:40.000Z",
"day": null,
"kind": "REVEAL",
"bucket": "PLAN",
"credits": -10,
"purchasedBalance": null,
"member": { "id": "7a2d9e4b-1c6f-4f3a-b8e5-0d9c2a6f1e48", "name": "Martín Ríos" },
"contactType": "EMAIL_WORK",
"person": "Sofía Herrera",
"events": null
}
],
"total": 148,
"page": 1,
"pageSize": 20
}kind:PURCHASE,REVEAL,GRANT,REFERRAL,REFUND,CHARGEBACK,CHARGEBACK_WONoAI_USAGE(un día de uso de IA pagado con créditos comprados).bucket:PLAN(créditos del plan) oPURCHASED(comprados).credits: con signo; un gasto es negativo. SoloAI_USAGEpuede tener decimales.purchasedBalance: saldo de créditos comprados después del movimiento;nullen una filaPLAN.member: quién gastó o compró;nullpara lo que hizo el sistema (un reembolso, un contracargo).dayyevents: enAI_USAGE, el día (YYYY-MM-DD) y cuántas llamadas suma.
GET /billing/seat-charge
/billing/seat-chargeLo que cobraría hoy sumar una persona más con asiento (OWNER o RECRUITER).
curl https://app.reclee.com/api/v1/billing/seat-charge \
-H "Authorization: Bearer rcl_..."{
"kind": "PRORATED",
"pricePerSeatUsd": 79,
"interval": "MONTH",
"renewsAt": "2026-11-03T00:00:00.000Z",
"card": { "brand": "visa", "last4": "4242", "expMonth": 8, "expYear": 2028 }
}kind puede ser:
PRORATED: un plan pago cobra hoy la parte proporcional del período.pricePerSeatUsdes el precio del intervalo completo; el monto exacto lo calcula el procesador de pagos al cobrar.PAID_IN_PERIOD: un asiento que se liberó en este período se reutiliza sin cargo.TRIAL: no se cobra nada hasta que termine la prueba (trialEndsAt).NONE: no se cobra nada (plan gratuito o sin medición).
GET /billing/payment-method
/billing/payment-methodLa tarjeta guardada.
curl https://app.reclee.com/api/v1/billing/payment-method \
-H "Authorization: Bearer rcl_..."{
"hasCustomer": true,
"card": { "brand": "visa", "last4": "4242", "expMonth": 8, "expYear": 2028 },
"cardUnavailable": false
}hasCustomer es false si el workspace nunca pagó. cardUnavailable es true cuando la tarjeta no se pudo leer en ese momento (card viene en null y no significa que no haya).
GET /billing/profile
/billing/profileLos datos que salen en las facturas, o null si nunca se cargaron.
curl https://app.reclee.com/api/v1/billing/profile \
-H "Authorization: Bearer rcl_..."{
"legalName": "Talento Andino S.A.S.",
"billingEmail": "facturas@talentoandino.com",
"taxIdType": "co_nit",
"taxId": "900123456-7",
"country": "CO",
"addressLine1": "Calle 93 # 11-26",
"addressLine2": null,
"city": "Bogotá",
"region": "Cundinamarca",
"postalCode": "110221",
"note": null
}GET /billing/profile/recipient
/billing/profile/recipientA quién se dirige la factura mientras no hay datos de facturación cargados.
curl https://app.reclee.com/api/v1/billing/profile/recipient \
-H "Authorization: Bearer rcl_..."{ "workspaceName": "Talento Andino", "email": "laura.mendez@talentoandino.com" }Operaciones de la cuenta
Las rutas de esta sección existen en la API para que el contrato sea el mismo que el de la app, pero todas exigen a una OWNER en persona: por API key contestan siempre 403 FORBIDDEN. Se hacen desde Configuración → Facturación en la app. Lo que devuelven en la app:
| Ruta | Qué hace | Qué devuelve en la app |
|---|---|---|
POST /billing/checkout | Inicia el primer pago de un plan. Body: plan (STARTER o PRO), interval (MONTH o YEAR). | { "clientSecret": "..." } del checkout embebido de Stripe; no es una URL. |
POST /billing/checkout/settle | Confirma un checkout al volver de él. Body: sessionId (empieza con cs_). | { "settled": boolean, "entitlements": { ... } } |
POST /billing/trial | Empieza 14 días de STARTER sin tarjeta; uno por workspace, persona y email. | Los entitlements actualizados. |
GET /billing/plan/preview | Cotiza un cambio de plan. Query: plan, interval. | kind (UPGRADE o DOWNGRADE), precio por asiento, asientos, total, lo que se cobra hoy y prorationDate. |
PUT /billing/plan | Cambia de plan. Body: plan, interval y opcionalmente prorationDate de la cotización. Subir se cobra hoy; bajar espera al fin del período. | Los entitlements actualizados. |
DELETE /billing/plan | Anula una bajada de plan que todavía no ocurrió. | Los entitlements actualizados. |
PUT /billing/cancellation | Cancela la suscripción al fin del período (o en el acto si hay un cobro vencido). Body: reason (obligatorio) y comment. | { "mode", "entitlements" }, con mode en PERIOD_END o NOW |
DELETE /billing/cancellation | Deshace la cancelación antes de que termine el período. | Los entitlements actualizados. |
POST /billing/credits | Compra un paquete de créditos. Body: packId y purchaseId (un id por intención de compra). Acepta Idempotency-Key. | { "status": "PAID" } si se cobró a la tarjeta guardada, o { "status": "CHECKOUT", "declined": boolean, "clientSecret": "..." } para completar el pago en un checkout. |
POST /billing/portal | Abre el portal de pagos para la tarjeta y las facturas. | { "url": "https://..." }, un link temporal. |
PUT /billing/profile | Guarda los datos de facturación. | El perfil guardado, como GET /billing/profile. |
Errores que estas operaciones devuelven en la app y que puedes ver referenciados en errores: NOT_BILLABLE, ALREADY_SUBSCRIBED, NOT_SUBSCRIBED, TRIAL_USED, SEAT_LIMIT, PAYMENT_FAILED, PAYMENT_PENDING, PURCHASE_IN_PROGRESS, PURCHASE_FAILED, PACK_UNAVAILABLE.