Reclee

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

GET/billing/usage-standing

Dó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, PAID o CHURNED (volvió a FREE después de haber pagado).
  • metered: false si 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; endsAt es cuándo devuelve el uso (null si 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; null si 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).
  • purchasedThisPeriod y seatHolders solo vienen completos en casos puntuales (por ejemplo, cuando el mes del plan se agotó); si no, null.

Planes y paquetes

GET /billing/plans

GET/billing/plans

Los 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

GET/billing/credits

Los 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

GET/billing/entitlements

El 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, SCALE o INTERNAL.
  • status: TRIALING, ACTIVE, PAST_DUE o CANCELED.
  • planCredits: créditos que trae el plan en el período; remaining ya descuenta las reservas abiertas.
  • purchasedCredits: créditos comprados. No vencen, y pueden quedar en negativo después de un contracargo. purchasedHeld es la parte ya reservada por acciones en curso.
  • ai / team: el uso del mes del plan y del cupo de equipo. usedPct va de 0 a 1; left dice si queda algo, descontando las reservas abiertas.
  • window: tu ventana de cinco horas. usedPct va de 0 a 1, spent es true cuando lo usado más lo reservado llegó al tope, y endsAt es cuándo se libera (null si no usaste nada en las últimas cinco horas).

GET /billing/subscription

GET/billing/subscription

Lo 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); null sin plan pago.
  • scheduledChange: un cambio a un plan menor programado para el fin del período; null si no hay. Si scheduledChangeUnavailable es true, no se pudo leer y null no 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

GET/billing/credit-movements

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

CampoTipoRequeridoDescripción
pageintegerOpcionalPágina, desde 1. Por defecto, 1.
pageSizeintegerOpcionalFilas 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_WON o AI_USAGE (un día de uso de IA pagado con créditos comprados).
  • bucket: PLAN (créditos del plan) o PURCHASED (comprados).
  • credits: con signo; un gasto es negativo. Solo AI_USAGE puede tener decimales.
  • purchasedBalance: saldo de créditos comprados después del movimiento; null en una fila PLAN.
  • member: quién gastó o compró; null para lo que hizo el sistema (un reembolso, un contracargo).
  • day y events: en AI_USAGE, el día (YYYY-MM-DD) y cuántas llamadas suma.

GET /billing/seat-charge

GET/billing/seat-charge

Lo 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. pricePerSeatUsd es 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

GET/billing/payment-method

La 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

GET/billing/profile

Los 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

GET/billing/profile/recipient

A 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:

RutaQué haceQué devuelve en la app
POST /billing/checkoutInicia 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/settleConfirma un checkout al volver de él. Body: sessionId (empieza con cs_).{ "settled": boolean, "entitlements": { ... } }
POST /billing/trialEmpieza 14 días de STARTER sin tarjeta; uno por workspace, persona y email.Los entitlements actualizados.
GET /billing/plan/previewCotiza 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/planCambia 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/planAnula una bajada de plan que todavía no ocurrió.Los entitlements actualizados.
PUT /billing/cancellationCancela 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/cancellationDeshace la cancelación antes de que termine el período.Los entitlements actualizados.
POST /billing/creditsCompra 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/portalAbre el portal de pagos para la tarjeta y las facturas.{ "url": "https://..." }, un link temporal.
PUT /billing/profileGuarda 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.

En esta página