Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.onepay.la/llms.txt

Use this file to discover all available pages before exploring further.

​
¿Qué es una Factura?

Una factura es un registro de cobro que genera automáticamente un Payment asociado. Al crear una factura, OnePay crea un cobro vinculado, lo envía al cliente y gestiona todo el ciclo de vida hasta el pago y la conciliación.
Si solo necesitas cobrar un monto sin vincular a un sistema de gestión externo, usa directamente Payments.

​
¿Cuándo usar Facturas?

EscenarioSolución
Cobro desde un sistema de gestión externo (SAEplus, Wispro, Siigo, etc.)Usa Facturas
Cobro con detalle de items y datos de facturaciónUsa Facturas
Dividir el pago entre múltiples destinatariosUsa Facturas con splits
Cobro en múltiples abonosUsa Facturas con partial_payment

​
Flujo de integración

El flujo completo para integrar facturas tiene estos pasos clave:
Para homologar la integración de facturas, tu sistema debe implementar las siguientes capacidades:
  1. Crear facturas — POST /invoices para sincronizar facturas desde tu sistema de gestión hacia OnePay.
  2. Recibir confirmación de pago — Webhook invoice.paid para saber cuándo una factura fue pagada a través de OnePay.
  3. Actualizar facturas — PUT /invoices/{invoice} para reflejar cambios de valor o datos de la factura.
  4. Eliminar facturas — DELETE /invoices/{invoice} para cancelar facturas o marcarlas como pagadas por otro medio distinto a OnePay.

​
Crear factura

Al llamar a POST /invoices, OnePay:
  • Crea un registro de factura con estado CREATED
  • Genera un Payment asociado con source = INVOICE
  • Si ya existe una factura con el mismo company + provider + reference en estado CREATED, retorna la existente (idempotencia implícita)
  • Retorna la factura con los datos del payment y su payment_link
Al crear una factura, la respuesta incluye el campo id — este es el identificador único de la factura en OnePay. Guárdalo en tu sistema ya que lo necesitarás para actualizar o eliminar la factura posteriormente.Recomendación: Almacena este valor como external_id (o equivalente) en tu sistema de gestión para asociar fácilmente tus registros con OnePay.

​
Webhooks

OnePay notifica automáticamente los cambios de estado de cada factura. Configura los eventos de facturas en tu webhook para recibirlos. Para ver la estructura completa del payload que recibirás, consulta los ejemplos de webhooks de facturas.

​
Actualizar factura

Al llamar a PUT /invoices/{invoice}:
  • Si el payment aún no se pagó: OnePay cancela el payment anterior y crea uno nuevo con los datos actualizados. Se envía un nuevo cobro al cliente.
  • Si el payment ya se pagó: Solo se actualizan los campos informativos (nombre, monto, referencia), sin generar un nuevo cobro.
  • El campo provider no se puede modificar.

​
Eliminar factura

Al llamar a DELETE /invoices/{invoice}:
  • No se puede eliminar una factura con estado PAID o CONCILIATED (retorna HTTP 409)
  • OnePay cancela el payment asociado
  • La factura se marca según el reason: PAID_FROM_PROVIDER (pagada externamente) o DELETE_FROM_PROVIDER (eliminada)
  • Se detiene todo seguimiento y recordatorios de cobranza

​
Estados de una factura

EstadoDescripción
CREATEDFactura creada, cobro enviado al cliente
PAIDPagada en OnePay, pendiente conciliación con el proveedor
CONCILIATEDPagada y conciliada exitosamente con el sistema de gestión
PAID_FROM_PROVIDERMarcada como pagada desde el sistema externo
DELETE_FROM_PROVIDEREliminada desde el sistema externo
FAILEDFallo en la creación o procesamiento

​
Endpoints

MétodoEndpointDescripción
POST/invoicesCrear factura
GET/invoicesListar facturas
GET/invoices/Detalle de una factura
PUT/invoices/Actualizar factura
DELETE/invoices/Eliminar factura
DELETE/invoicesEliminar facturas masivamente