Introducción

Esta funcionalidad está en habilitación. Para activarla en tu empresa, escríbenos por el chat del panel de administración: el proceso incluye cargar tu resolución de la DIAN y completar la habilitación de tu empresa como facturador electrónico.

Qué hace

OnePay emite la factura electrónica a nombre de tu empresa ante la DIAN, con tu resolución y tu numeración, y le entrega el documento a tu cliente. Es el mismo endpoint que Facturas — POST /v1/invoices — y el mismo recurso. Lo que cambia es si mandas items:

	Sin `items`	Con `items`
Origen	Ya existe en tu sistema (Wispro, Siigo, SAEplus…)	Nace en OnePay
Qué hace OnePay	La cobra	La emite ante la DIAN y la cobra
Documento legal	El de tu sistema	El XML que OnePay timbra
Campos que mandas	`provider`, `provider_id`, `reference`, `amount`	`customer_id`, `items`

En los dos casos la factura obtiene su cobro asociado, aparece en el mismo listado y se consulta por la misma URL.

Si ya facturas en otro sistema y solo necesitas recaudar, no cambia nada para ti: seguí mandando el mismo payload de siempre. items es aditivo.

Cuándo se timbra

El parámetro más importante de la integración es stamp_policy, porque decide en qué momento el documento existe ante la DIAN.

Política	Emite	Para qué
`none` (por defecto)	Nunca	Facturas por otro sistema, o todavía no estás habilitado ante la DIAN
`on_payment`	Cuando el pago se aprueba	Venta de contado
`on_issue`	Al crear la factura	Venta a crédito, cobro anticipado
`manual`	Cuando llamas a `/stamp`	Necesitas revisar antes de emitir

none no es lo mismo que manual. Con manual la intención es emitir más tarde; con none no se emite nunca. La diferencia importa: una factura “pendiente de emitir” que en realidad nunca se va a emitir es indistinguible de una que alguien olvidó.Con none la factura existe igual, con sus líneas y su cobro — simplemente no hay documento fiscal. Y como no lo va a haber, no se te exigen los datos fiscales del cliente: dirección, dígito de verificación ni responsabilidades fiscales.

none es el valor por defecto. Si no mandas stamp_policy, la factura NO se emite ante la DIAN.Es deliberado: emitir un documento con efectos tributarios tiene que ser una decisión explícita. Si se te olvida el parámetro, el resultado es una factura sin emitir —que puedes emitir después con /stamp— y no un documento ante la DIAN que haya que anular con una nota crédito.

Con on_issue el documento se emite antes de saber si te van a pagar. Si el cobro falla o lo reembolsas, tienes una factura viva ante la DIAN por una venta que no ocurrió, y la única salida legal es una nota crédito.OnePay la emite automáticamente al reembolsar, pero si tu operación no necesita facturar por anticipado, on_payment te evita el problema entero.

Datos que exige el receptor

La DIAN no acepta una factura con el receptor incompleto. Lo que se exige depende del tipo de documento:

Campo	Siempre	Solo si NIT o RUT
Correo electrónico	✅
Nombre o razón social	✅
Tipo y número de documento	✅
Dirección	✅
Dígito de verificación		✅
Responsabilidades fiscales		✅

Si falta algo, la API responde 422 con todos los campos faltantes de una vez, no con el primero:

{
  "code": "customer_not_invoiceable",
  "message": "No se puede facturar: al cliente le faltan datos que exige la DIAN (dirección, dígito de verificación).",
  "errors": {
    "customer.address": ["required"],
    "customer.document_verification": ["required"]
  }
}

Flujo

El timbrado es asíncrono. La DIAN puede tardar segundos o minutos, así que POST /v1/invoices responde de inmediato con fiscal_status: null y el resultado te llega por webhook. No hagas polling contra el endpoint de detalle esperando el CUFE.

Ejemplo completo de implementación

Un ISP que cobra internet mensual y quiere que OnePay emita sus facturas.

Paso 1 — Carga tu resolución de la DIAN

Una sola vez, con los datos que aparecen en tu resolución del portal MUISCA.

curl -X POST https://api.onepay.la/v1/fiscal-resolutions \
  -H "Authorization: Bearer $ONEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "18760000001",
    "prefix": "FE",
    "document_type": "invoice",
    "from": 1,
    "to": 5000,
    "valid_from": "2026-01-15",
    "valid_until": "2027-01-15",
    "technical_key": "fc8eac4227b2b1e8..."
  }'

Queda en draft. Actívala cuando la hayamos validado:

curl -X POST https://api.onepay.la/v1/fiscal-resolutions/{id}/activate \
  -H "Authorization: Bearer $ONEPAY_API_KEY"

Carga también una resolución con document_type: "credit_note" y su propio prefijo. Las notas crédito llevan numeración aparte, y sin ella no vas a poder anular ni devolver.

Paso 2 — Asegura que tu cliente tenga los datos fiscales

curl -X POST https://api.onepay.la/v1/customers \
  -H "Authorization: Bearer $ONEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Ana",
    "last_name": "Ramírez",
    "email": "ana@ejemplo.com",
    "phone": "+573001234567",
    "document_type": "CC",
    "document_number": "1020304050",
    "address": { "line": "Calle 45 # 12-30", "city_code": "17001" }
  }'

Paso 3 — Previsualiza los totales

Útil para mostrar el detalle en tu propia interfaz antes de emitir. No crea nada.

curl -X POST https://api.onepay.la/v1/invoices/preview \
  -H "Authorization: Bearer $ONEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "description": "Plan Fibra 200 Mbps - agosto", "unit_amount": 8990000, "tax": { "rate": 19 } }
    ]
  }'

{
  "data": {
    "items": [
      {
        "description": "Plan Fibra 200 Mbps - agosto",
        "quantity": 1,
        "unit_amount": 8990000,
        "subtotal": 8990000,
        "tax_rate": 19,
        "tax_amount": 1708100,
        "total": 10698100
      }
    ],
    "subtotal": 8990000,
    "tax_amount": 1708100,
    "total": 10698100
  }
}

Todos los montos van en centavos. 8990000 son $89.900 COP. Es el mismo criterio de entrada y de salida, y evita que un decimal mal redondeado haga que la DIAN rechace el documento.

Paso 4 — Crea la factura

curl -X POST https://api.onepay.la/v1/invoices \
  -H "Authorization: Bearer $ONEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-ea6c-4b3d-9c1a-2b7d3e5f9a01" \
  -d '{
    "customer_id": "cus_01J8XK2P9WQZ",
    "name": "Plan Fibra 200 Mbps - agosto 2026",
    "stamp_policy": "on_payment",
    "due_date": "2026-08-16",
    "reference": "1020304050",
    "items": [
      { "description": "Plan Fibra 200 Mbps - agosto", "unit_amount": 8990000, "tax": { "rate": 19 } },
      { "description": "Instalación", "unit_amount": 15000000, "tax": { "rate": 19 } }
    ],
    "metadata": { "contrato": "CT-88421" }
  }'

{
  "id": "inv_01J8XK9V4N",
  "status": "CREATED",
  "fiscal_status": null,
  "stamp_policy": "on_payment",
  "currency": "COP",
  "customer": { "id": "cus_01J8XK2P9WQZ", "name": "Ana Ramírez", "document_number": "1020304050" },
  "items": [ "..." ],
  "totals": { "subtotal": 23990000, "tax_amount": 4558100, "total": 28548100 },
  "amount": 285481,
  "payment_id": "pay_01J8XKC5D2",
  "stampings": []
}

El Idempotency-Key no es opcional en la práctica: sin él, un reintento de tu lado por un timeout de red crea dos facturas, que es IVA declarado dos veces y una nota crédito para arreglarlo.

Paso 5 — Escucha los webhooks

Con on_payment, cuando tu cliente pague, OnePay timbra y te avisa:

{
  "event": "invoice.stamped",
  "data": {
    "invoice_id": "inv_01J8XK9V4N",
    "stamping": {
      "type": "invoice",
      "status": "accepted",
      "number": "FE1",
      "cufe": "a3f5c8e2...",
      "xml_url": "https://...",
      "pdf_url": "https://...",
      "total": 28548100
    }
  }
}

Si la DIAN rechaza:

{
  "event": "invoice.stamp_rejected",
  "data": {
    "invoice_id": "inv_01J8XK9V4N",
    "stamping": {
      "status": "rejected",
      "number": "FE1",
      "rejection_reason": "Regla FAJ01: el receptor no tiene responsabilidades fiscales"
    }
  }
}

Guarda el cufe y el xml_url en tu sistema. El XML es el documento legal; el PDF es solo su representación gráfica.

Fíjate en totals y en amount: los totales fiscales van en centavos y agrupados aparte, mientras que amount es el monto en pesos de siempre, el que ya leen tus integraciones. Están separados a propósito — mezclar las dos unidades en el mismo nivel es la forma más fácil de cobrar cien veces de más.

Paso 6 — Devoluciones

Si tienes que devolver dinero, emite una nota crédito. OnePay ya la emite sola cuando reembolsas un cobro, pero también puedes hacerlo directo:

curl -X POST https://api.onepay.la/v1/invoices/inv_01J8XK9V4N/credit-notes \
  -H "Authorization: Bearer $ONEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 15000000, "reason": "Instalación no realizada" }'

Omite amount para anular la factura completa. Puedes emitir varias notas parciales sobre la misma factura; OnePay no deja que la suma supere el total.

Errores

Todos traen un code estable sobre el que puedes ramificar sin leer el mensaje.

`code`	Qué pasó
`customer_not_invoiceable`	Al receptor le faltan datos que exige la DIAN
`invalid_invoice_line`	Una línea no se puede resolver (indica cuál con su índice), o el total queda fuera del rango cobrable
`credit_note_not_issuable`	La factura no está timbrada, o la nota excede lo que queda por devolver
`resolution_not_activatable`	La resolución está vencida o sin folios
`invoice_not_stampable`	La factura no se puede emitir: es importada de otro sistema, su `stamp_policy` no admite emisión manual, ya se timbró, o no tiene líneas

Preguntas frecuentes

¿Qué pasa si me quedo sin folios?

OnePay te avisa al 80% y al 95% del rango consumido, y 30 días antes de que venza la resolución. Carga la siguiente resolución con anticipación y actívala: puedes tener varias cargadas, pero solo una activa por prefijo y tipo de documento.Si te quedas sin folios, el timbrado falla con resolution_not_activatable y las facturas se siguen creando pero no se emiten.

¿Puedo facturar lo que ya cobro con /invoices?

No automáticamente. Las facturas que importas desde tu sistema de gestión no se timbran: OnePay asume que ya las emitiste tú. Si quieres migrar tu facturación a OnePay, escríbenos — hay que apagar la emisión en tu sistema anterior primero, o terminarías facturando dos veces la misma venta.

¿El precio de mis productos incluye IVA?

Puedes usar cualquiera de las dos formas. Con tax.behavior: "inclusive" el unit_amount ya trae el impuesto y OnePay lo desagrega; con "exclusive" (por defecto) el impuesto se suma encima.El XML de la DIAN siempre lleva base e impuesto por separado, así que la desagregación ocurre igual — la diferencia es solo cómo nos mandas el precio.

¿Puedo usar mi catálogo de productos?

Sí. En vez de description y unit_amount, manda price_id de un Precio y OnePay resuelve nombre, monto e impuesto. Puedes mezclar líneas del catálogo con líneas sueltas en la misma factura, y sobreescribir el impuesto de una línea puntual sin duplicar el producto.

¿Cómo pruebo sin emitir documentos reales?

Usa tu API key de pruebas. El entorno de pruebas tiene su propia resolución y su propia numeración, completamente separada de producción.

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Qué hace

Cuándo se timbra

Datos que exige el receptor

Flujo

Ejemplo completo de implementación

Paso 1 — Carga tu resolución de la DIAN

Paso 2 — Asegura que tu cliente tenga los datos fiscales

Paso 3 — Previsualiza los totales

Paso 4 — Crea la factura

Paso 5 — Escucha los webhooks

Paso 6 — Devoluciones

Errores

Preguntas frecuentes

​Qué hace

​Cuándo se timbra

​Datos que exige el receptor

​Flujo

​Ejemplo completo de implementación

​Paso 1 — Carga tu resolución de la DIAN

​Paso 2 — Asegura que tu cliente tenga los datos fiscales

​Paso 3 — Previsualiza los totales

​Paso 4 — Crea la factura

​Paso 5 — Escucha los webhooks

​Paso 6 — Devoluciones

​Errores

​Preguntas frecuentes

Qué hace

Cuándo se timbra

Datos que exige el receptor

Flujo

Ejemplo completo de implementación

Paso 1 — Carga tu resolución de la DIAN

Paso 2 — Asegura que tu cliente tenga los datos fiscales

Paso 3 — Previsualiza los totales

Paso 4 — Crea la factura

Paso 5 — Escucha los webhooks

Paso 6 — Devoluciones

Errores

Preguntas frecuentes