Planes

Un plan define las reglas de facturación: el monto y cada cuánto se factura. Las suscripciones unen un cliente a un plan.

Depende de: configuración de cuotas (solo si el plan es por cuotas — se crea ANTES del plan). Lo necesitan: suscripciones.

Crear un plan


POST /plan/company

Scope requerido: plan.create

Cuerpo

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del plan (ej. “Plan mensual escolar”). No puede ser vacío.
`amount`	número	Sí	Monto en USD por ciclo. No puede ser `0`.
`frequency`	string	No	`DAILY`, `WEEKLY`, `BIWEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY`, `YEARLY`. Determina cada cuánto se genera la factura.
`enforceCustomRate`	boolean	No	`true` para aplicar la tasa de cambio personalizada de tu empresa en lugar de la tasa BCV del día.
`allowedPaymentCurrency`	string	No	`USD`, `VES` o `EUR`. Limita el plan a métodos de pago de esa moneda. Omitirlo o enviar `null` = sin restricción.
`planSettingsId`	número	No	ID de la configuración de cuotas. Solo para planes por cuotas.

Si envías planSettingsId, la suma de las cuotas definidas en esa configuración debe coincidir exactamente con el amount del plan — si no, la API responde RIPEI-PLAN-005 indicando ambos montos.

Restringir con qué se puede pagar

allowedPaymentCurrency limita el plan a los métodos de pago de una sola moneda. Al cliente solo se le ofrecen esos métodos al pagar por WhatsApp, y si elige otro (por ejemplo, desde un mensaje viejo del chat) el pago se rechaza con una explicación.

La restricción aplica a lo que el cliente elige. Registrar un pago por este API no se bloquea: si alguien pagó por una vía distinta, puedes asentarlo igual.

Dos cosas a tener en cuenta:

Si tu empresa no tiene métodos de pago activos en esa moneda, el plan se crea igual pero nadie va a poder pagarlo por WhatsApp hasta que crees uno.
Los planes que ya existen quedan sin restricción; no cambia nada si no envías el campo.

Ejemplo


curl -X POST https://api.qa.pagosripei.com/plan/company \
  -H "Authorization: Bearer $RIPEI_TOKEN" \
  -H "company: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Plan mensual escolar",
    "amount": 50,
    "frequency": "MONTHLY"
  }'

Respuesta `201`


{
  "id": 88,
  "name": "Plan mensual escolar",
  "amount": 50,
  "frequency": "MONTHLY"
}

Editar un plan


PUT /plan/:planId/company

Scope requerido: plan.update

Acepta los mismos campos, todos opcionales — solo se actualizan los enviados.

Para quitar la restricción de moneda envía "allowedPaymentCurrency": null. Omitir el campo la deja como estaba.

Errores

Código	Causa
`RIPEI-PLAN-001`	`name` vacío.
`RIPEI-PLAN-002`	`amount` en cero.
`RIPEI-PLAN-003`	Plan no encontrado (o pertenece a otra empresa).
`RIPEI-PLAN-004`	`planSettingsId` no encontrado (o pertenece a otra empresa).
`RIPEI-PLAN-005`	La suma de cuotas no coincide con el monto del plan.