API · prepaid

Paquetes y club con cupo (F3-261); el dinero vive en payments.

POST /prepaid/bookings/{booking_id}/release

Release Booking

Permiso/scope prepaid:sell (owner/manager). Quita el plan de una tarea cubierta: libera la unidad reservada y la tarea vuelve a su valor a cobrar normal; no se vuelve a cubrir sola. Una tarea cubierta no admite cambiar el cliente ni el servicio (PATCH /bookings/{id} da 409 booking_covered_by_plan) hasta quitarle el plan. Repetirlo es idempotente. Una unidad ya consumida da 409 prepaid.booking_consumed; una tarea sin plan, 409 prepaid.booking_not_covered. Audita prepaid.booking_removed con el motivo.

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

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: ReleaseBooking

Respuestas

GET /prepaid/customers/{customer_id}

Customer Plans

Permiso/scope prepaid:read. Paquetes, club y membresía del cliente con su período vigente: unidades totales, usadas, reservadas (tareas confirmadas que lo van a usar) y disponibles (units_left). F3-463: period.booking_id es la cuota del período (la tarea que se cobra), open_fees las cuotas por cobrar y next_due_at el vencimiento de la próxima; status active = al día y past_due = impago, y debt_minor suma las cuotas ya vencidas por cobrar (una que nació antes de vencer todavía no es deuda; con tarjeta: rechazadas por MP o sin cobrar a los 3 días). Staff solo de clientes con tareas en sus recursos; ajeno o inexistente da el mismo 403.

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

Parámetros

Respuestas

GET /prepaid/plans

List Plans

Tenant desde credencial. Permiso/scope prepaid:read (F3-261). Paquetes (N unidades de ciertos servicios con vencimiento en días), planes de club (N unidades por mes calendario local) y membresías (F3-536, precio fijo por mes, sin unidades; units y unit_minor null) del catálogo. active=true lista solo los vendibles. unit_minor = precio / unidades (redondeado hacia abajo), en unidad menor de la moneda. card_billing_available (F3-553) dice si el proyecto puede cobrar con tarjeta (MP Suscripciones), true solo con el cobro automático habilitado y una cuenta de Mercado Pago conectada; recién ahí se crean planes billing=card (club o membresía) y se venden con payer_email.

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

Parámetros

Respuestas

POST /prepaid/plans

Create Plan

Permiso/scope prepaid:manage (owner/manager). Crea un paquete (validity_days obligatorio), un club o una membresía (kind=membership, F3-536: precio fijo por mes sin unidades ni cupo; servicios opcionales, que quedan cubiertos en $0 sin descontar). El cobro con tarjeta (billing=card, MP Suscripciones; solo club y membresía) exige card_billing_available de GET /prepaid/plans (F3-553): sin el cobro automático habilitado da 409 prepaid.card_billing_disabled y sin cuenta de Mercado Pago conectada, 409 prepaid.card_account_required. quota: hasta 10 reglas de cupo por día local, opcionalmente en una franja start-end y en ciertos weekdays (0 = lunes); la reserva que no entra en el cupo queda sin cubrir y se cobra normal. Audita prepaid.plan_created.

• Autenticación: Clave de API o sesión del panel
• Scopes: prepaid:manage

Cuerpo de la solicitud (obligatorio)

• application/json: PlanInput

Respuestas

PATCH /prepaid/plans/{plan_id}

Update Plan

Permiso/scope prepaid:manage. Cambia nombre, servicios, cupo, precio, unidades, vencimiento, flujo del alta o primera cuota completa, o lo apaga (active=false). El precio rige para las cuotas que nacen desde ahora en todas las suscripciones vivas: las cuotas ya creadas conservan el suyo y al cliente no se le avisa (lo ve en su próxima cuota, F3-463); la respuesta trae live_subscriptions, cuántas lo verán. Unidades y vencimiento solo afectan ventas nuevas. Una membresía no acepta unidades, vigencia ni cupo (409 prepaid.membership_terms) y un paquete solo due_rule=signup (409 prepaid.package_terms). Audita prepaid.plan_updated (con el precio antes y después).

• Autenticación: Clave de API o sesión del panel
• Scopes: prepaid:manage

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: PlanUpdate

Respuestas

GET /prepaid/plans/{plan_id}/performance

Rendimiento de un plan en cantidades: vendidos por día, semana o mes y activos hoy

F3-328. Rendimiento de un plan (paquete o club) en CANTIDADES (nunca dinero: vive en Financiero). Panel: permisos performance:read y prepaid:stats (owner/manager); API key: scope prepaid:read. sold (por defecto): ventas nuevas por día de alta, sin pendientes de pago ni clientes de prueba, con el período anterior. active: clientes distintos con el plan activo hoy (previous null). Período anterior y tramos como en GET /services/{id}/performance. Máximo 366 días.

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

Parámetros

Respuestas

GET /prepaid/plans/stats

Rendimiento por plan: vendidos, activos, consumo y vencimientos

F3-315. Rendimiento de cada plan del catálogo (también los sin ventas), en una sola consulta agrupada. Panel: permiso prepaid:stats (owner/manager); API key: scope prepaid:read. Sin clientes de prueba. sold: ventas nuevas del período (sin pendientes de pago con tarjeta). active_subscriptions: con el plan activo hoy. units_used/units_total/usage_ratio: consumo de los períodos vigentes hoy de clientes con el plan. expiring_30d: paquetes vigentes que vencen en 30 días (null en club). sold_minor (ventas y renovaciones pagas del período, incluye reembolsadas como el resumen de Financiero) y currency solo con finance:analyze; si no, null. Máximo 366 días.

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

Parámetros

Respuestas

GET /prepaid/subscriptions

Listar suscripciones del proyecto

Permiso/scope prepaid:benefits (owner/manager). Lista paginada de suscripciones con estado impago y pausa de beneficios; las membresías traen standing (al día, en gracia o bloqueada, F3-537). Con unpaid=true, solo las impagas (la alerta de Hoy y el filtro «Impagos» de Planes). Cada una trae months_due (meses adeudados) y la respuesta unpaid_count, el conteo del servidor de impagas del proyecto (F3-405). Tenant desde la credencial.

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

Parámetros

Respuestas

POST /prepaid/subscriptions

Sell Plan

Permiso/scope prepaid:sell (owner/manager) y además payments:record: vende un plan. Crea la suscripción, su período 1 y la cuota 1 (F3-463): una tarea sin servicio (subject.type = subscription), en cola y sin horario, que es también el alta (recorre el flujo del plan, flow_id, si tiene) y vence al venderse; su valor es el precio vigente del plan, o la parte proporcional hasta el próximo vencimiento según due_rule (salvo first_fee_full). Con payment registra un recibo purpose=plan sobre esa cuota (cualquier forma de pago manual, misma caja e idempotencia que POST /payments/manual) y nace pagada; sin payment queda Por cobrar (link de pago desde la tarea o recibo a mano) y es deuda desde ya. Cubre enseguida las tareas confirmadas del cliente dentro de la ventana. Si se vende dentro de los notice_days previos al próximo vencimiento, la cuota 2 nace en el acto. En un flujo de cuota la tarea solo pasa a Pagada con saldo cero: completarla con deuda o pago parcial da 409 prepaid_consumption_failed (reason: membership_unpaid), y anular su recibo o devolver el cobro la vuelve a Por cobrar. El cobro automático aparece en el historial de la tarea; devolverlo desde Fiuit da payment.refund_plan_unsupported (se devuelve en Mercado Pago). Con tarjeta (F3-553; plan billing=card, payer_email = email del cliente; basta prepaid:sell, no registra un recibo) la suscripción nace pending con checkout_url, el link de Mercado Pago donde el cliente autoriza la tarjeta (Fiuit no ve sus datos); al autorizar y cobrarse el primer mes pasa a active. Exige card_billing_available: si no, 409 prepaid.card_billing_disabled o prepaid.card_account_required. Una sola venta con tarjeta vigente por cliente y plan (F3-631): si el cliente ya tiene ese plan con tarjeta esperando autorización (pending), activo o con un cobro rechazado (past_due), responde 409 con code: prepaid_card_sale_exists, detail: prepaid.card_sale_exists y subscription_id (la venta vigente), sin tocar Mercado Pago; cancelada o vencida no bloquea. Idempotency-Key obligatoria (reintentar con la misma clave devuelve la misma venta): la misma clave con otros datos es 409. Las escrituras de dinero desde MCP exigen confirm=true.

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

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: SellPlan

Respuestas

PUT /prepaid/subscriptions/{subscription_id}/benefits

Pausar o reactivar beneficios

Permiso/scope prepaid:benefits (owner/manager). paused=true exige club past_due; paused=false reactiva un club activo o impago. No cambia deuda ni cobra. Idempotente por estado y auditado.

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

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: BenefitsUpdate

Respuestas

POST /prepaid/subscriptions/{subscription_id}/cancel

Cancel Plan

Permiso/scope prepaid:sell; con refund=true también payments:void y payments:record. Cancela con la regla única de ADR 0040 §5.5 (F3-463): no nacen más cuotas y las ya creadas no se tocan (una por cobrar sigue siendo deuda real; se perdona cerrándola sin completar); la respuesta las lista en open_fees. Libera las unidades reservadas por tareas futuras (vuelven a su valor normal). Con refund=true en un paquete o club cobrado en mano, anula los recibos de la cuota del período vigente (abierto y sin vencer) y deja su valor a cobrar en lo ya consumido, cobrado con un recibo nuevo del mismo medio; lo vencido se pierde y no se devuelve. Un recibo que también paga otras tareas da 409 prepaid.refund_shared_receipt y dinero electrónico 409 prepaid.refund_electronic_unsupported (se devuelve desde la tarea); efectivo de un día con caja cerrada, 409 prepaid.refund_cash_closed. Repetir con el mismo motivo es idempotente. Con tarjeta cancela también la suscripción en MP. Membresía con refund=true: 409 prepaid.membership_refund_on_task (lo cobrado se devuelve desde la tarea).

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

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: CancelPlan

Respuestas

POST /prepaid/subscriptions/{subscription_id}/extend

Extend Plan

Permiso/scope prepaid:sell (owner/manager). Extiende a mano el vencimiento del período vigente de un paquete o club (o del último período de un paquete ya vencido, que vuelve a quedar activo y cubre las tareas confirmadas dentro de la ventana). Al vencer, las unidades no usadas se pierden: no hay crédito ni reembolso del remanente; esta es la única forma de darle más tiempo. ends_at debe ser posterior al vencimiento actual y al momento presente (409 prepaid.extend_not_later); repetir el mismo ends_at no cambia nada. Se extiende el período ya empezado (una cuota siguiente que nació antes de vencer no). Una membresía o un plan cancelado da 409 prepaid.not_extendable. Audita prepaid.period_extended con antes, después y motivo.

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

Parámetros

Cuerpo de la solicitud (obligatorio)

• application/json: ExtendPlan

Respuestas

GET /prepaid/summary

Summary

Permiso/scope finance:analyze (owner/manager). Ingreso de paquetes y club, sin clientes de prueba: sold_minor (cobrado), consumed_minor (unidades usadas, ingreso reconocido), deferred_minor (unidades por usar de períodos vigentes), expired_minor (no usadas de períodos cerrados o cancelados), refunded_minor y debt_minor (meses de club sin cobrar).

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

Respuestas