Facturas (bills)

Las facturas se generan automáticamente a partir de las suscripciones — en la mayoría de las integraciones no necesitas crear facturas manualmente. Este endpoint existe para cobros puntuales fuera del ciclo (un cargo extraordinario, un ajuste, etc.).

Depende de: cliente; opcionalmente suscripción.

Crear una factura manual


POST /bill/company

Scope requerido: bill.create

Cuerpo

Campo	Tipo	Requerido	Descripción
`companyUserId`	número	Sí	Cliente al que se le factura. Debe pertenecer a tu empresa.
`amount`	número	Sí*	Monto en USD. Obligatorio si no envías `subscriptionId`.
`subscriptionId`	número	No	Suscripción asociada. Si la envías sin `amount`, se usa el monto del plan.
`description`	string	No	Descripción visible para el cliente en los recordatorios y el flujo de pago.
`billingDate`	fecha ISO	No	Fecha de vencimiento de la factura.
`status`	string	No	Estado inicial. Default: `TO_BE_PAID`.

Estados de una factura

Estado	Significado
`TO_BE_PAID`	Pendiente de pago (estado inicial).
`TO_BE_CONFIRMED`	El cliente reportó un pago manual; falta confirmación del comercio.
`PAID`	Pagada por completo. Dispara el webhook `bill.paid`.

Ejemplo


curl -X POST https://api.qa.pagosripei.com/bill/company \
  -H "Authorization: Bearer $RIPEI_TOKEN" \
  -H "company: 42" \
  -H "Content-Type: application/json" \
  -d '{
    "companyUserId": 4275,
    "amount": 25,
    "description": "Cargo por inscripción",
    "billingDate": "2026-08-15T00:00:00Z"
  }'

Respuesta `201`


{
  "id": 9902,
  "companyUserId": 4275,
  "amount": 25,
  "status": "TO_BE_PAID",
  "description": "Cargo por inscripción",
  "billingDate": "2026-08-15T00:00:00.000Z"
}

Cuando el cliente pague (por cualquiera de los métodos de tu empresa: tarjeta, pago móvil, transferencia…), recibirás las notificaciones por webhook: cada pago emite payment.received y el cierre completo de la factura emite bill.paid.

Errores

Código	Causa
`RIPEI-BILL-001`	Cliente no encontrado (o de otra empresa).
`RIPEI-BILL-002`	Suscripción no encontrada (o de otra empresa).
`RIPEI-BILL-003`	Falta `amount` (y no hay suscripción de la cual derivarlo).