Crear factura electrónica

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",
    "items": [
      { "description": "Plan Fibra 200 Mbps", "unit_amount": 8990000, "tax": { "rate": 19 } },
      { "price_id": "price_01J8XK7T2M", "quantity": 1 }
    ]
  }'

{
  "id": "inv_01J8XK9V4N",
  "status": "CREATED",
  "fiscal_status": null,
  "stamp_policy": "on_payment",
  "currency": "COP",
  "due_date": "2026-08-16",
  "customer": {
    "id": "cus_01J8XK2P9WQZ",
    "name": "Ana Ramírez",
    "email": "ana@ejemplo.com",
    "document_type": "CC",
    "document_number": "1020304050"
  },
  "items": [
    {
      "description": "Plan Fibra 200 Mbps",
      "quantity": 1,
      "unit_amount": 8990000,
      "subtotal": 8990000,
      "tax_type": "IVA",
      "tax_rate": 19,
      "tax_amount": 1708100,
      "total": 10698100,
      "unit_measure": "94",
      "price_id": null
    }
  ],
  "totals": { "subtotal": 8990000, "tax_amount": 1708100, "total": 10698100 },
  "amount": 106981,
  "payment_id": "pay_01J8XKC5D2",
  "stampings": [],
  "created_at": "2026-08-01T14:22:10+00:00"
}

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

{
  "code": "invalid_invoice_line",
  "message": "El total de la factura (0 centavos) está fuera del rango cobrable (10000 a 10000000000 centavos)."
}

POST

invoices

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",
    "items": [
      { "description": "Plan Fibra 200 Mbps", "unit_amount": 8990000, "tax": { "rate": 19 } },
      { "price_id": "price_01J8XK7T2M", "quantity": 1 }
    ]
  }'

{
  "id": "inv_01J8XK9V4N",
  "status": "CREATED",
  "fiscal_status": null,
  "stamp_policy": "on_payment",
  "currency": "COP",
  "due_date": "2026-08-16",
  "customer": {
    "id": "cus_01J8XK2P9WQZ",
    "name": "Ana Ramírez",
    "email": "ana@ejemplo.com",
    "document_type": "CC",
    "document_number": "1020304050"
  },
  "items": [
    {
      "description": "Plan Fibra 200 Mbps",
      "quantity": 1,
      "unit_amount": 8990000,
      "subtotal": 8990000,
      "tax_type": "IVA",
      "tax_rate": 19,
      "tax_amount": 1708100,
      "total": 10698100,
      "unit_measure": "94",
      "price_id": null
    }
  ],
  "totals": { "subtotal": 8990000, "tax_amount": 1708100, "total": 10698100 },
  "amount": 106981,
  "payment_id": "pay_01J8XKC5D2",
  "stampings": [],
  "created_at": "2026-08-01T14:22:10+00:00"
}

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

{
  "code": "invalid_invoice_line",
  "message": "El total de la factura (0 centavos) está fuera del rango cobrable (10000 a 10000000000 centavos)."
}

Es el mismo endpoint de crear factura. Mandar items es lo que hace que OnePay emita el documento ante la DIAN en vez de registrar uno externo; en ese caso provider, provider_id y amount los pone el sistema. Responde 201 sin esperar a la DIAN. El resultado del timbrado llega por el webhook invoice.stamped o invoice.stamp_rejected.

Headers

string

required

Token único para garantizar la idempotencia de la petición

Sin Idempotency-Key, un reintento por timeout de red crea dos facturas: dos documentos ante la DIAN, IVA declarado dos veces y una nota crédito para arreglarlo.

Body

string

required

Cliente al que se le factura. Debe tener completos los datos que exige la DIAN — ver datos del receptor. Si falta alguno, la respuesta es 422 con todos los campos faltantes.

array

required

Líneas de la factura. Mínimo 1, máximo 200. Cada línea puede venir del catálogo (price_id) o definirse suelta.

Show Campos de la línea

string

Precio del catálogo. OnePay resuelve descripción, monto e impuesto. Requerido si no mandas description y unit_amount.

string

Descripción de la línea, hasta 500 caracteres. Sobreescribe el nombre del precio si mandas ambos.

number

Cantidad. Admite decimales (por ejemplo 1.5 horas). Por defecto 1, máximo 100000.

integer

Valor unitario en centavos. 8990000 son

89.900 COP. Máximo `10000000000` (

100.000.000).

number

Tarifa del impuesto en porcentaje. 0 es una línea exenta o excluida. Si la omites, se hereda del precio y luego del producto.

string

Tipo de impuesto. Por defecto IVA.

string

exclusive (por defecto) suma el impuesto sobre unit_amount. inclusive significa que unit_amount ya lo trae y OnePay lo desagrega.

string

Código de unidad de medida (UNECE Rec 20) que exige el XML. Por defecto 94 (unidad).

string

Código del producto según el estándar que uses.

string

Estándar del código: 999 (interno), UNSPSC, GTIN.

string

Si se emite ante la DIAN y cuándo:

none (por defecto) — no se emite. La factura se crea y se cobra igual, sin documento fiscal y sin exigir los datos fiscales del cliente.
on_payment — al aprobarse el pago.
on_issue — al crear la factura, antes de cobrar.
manual — cuando llames a /stamp.

Ver cuándo se timbra antes de elegir on_issue.

string

Título del cobro que ve el cliente. Hasta 100 caracteres.

string

Descripción detallada. Hasta 2000 caracteres.

string

Referencia con la que el cliente consulta su deuda en el portal de pagos. Se recomienda el documento del titular.

date

Fecha de pago oportuno.

string

Moneda. Por defecto la de tu empresa.

object

Datos adicionales que quieras persistir en la factura.

El total de la factura tiene que ser cobrable. La suma de las líneas debe quedar entre 10000 (

100) y `10000000000` (

100.000.000), el mismo rango que acepta el flujo sin items.Fuera de ahí la respuesta es 422 con invalid_invoice_line. El caso que más sorprende es el total en cero: una factura gratis generaría un cobro que nadie puede pagar.

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",
    "items": [
      { "description": "Plan Fibra 200 Mbps", "unit_amount": 8990000, "tax": { "rate": 19 } },
      { "price_id": "price_01J8XK7T2M", "quantity": 1 }
    ]
  }'

{
  "id": "inv_01J8XK9V4N",
  "status": "CREATED",
  "fiscal_status": null,
  "stamp_policy": "on_payment",
  "currency": "COP",
  "due_date": "2026-08-16",
  "customer": {
    "id": "cus_01J8XK2P9WQZ",
    "name": "Ana Ramírez",
    "email": "ana@ejemplo.com",
    "document_type": "CC",
    "document_number": "1020304050"
  },
  "items": [
    {
      "description": "Plan Fibra 200 Mbps",
      "quantity": 1,
      "unit_amount": 8990000,
      "subtotal": 8990000,
      "tax_type": "IVA",
      "tax_rate": 19,
      "tax_amount": 1708100,
      "total": 10698100,
      "unit_measure": "94",
      "price_id": null
    }
  ],
  "totals": { "subtotal": 8990000, "tax_amount": 1708100, "total": 10698100 },
  "amount": 106981,
  "payment_id": "pay_01J8XKC5D2",
  "stampings": [],
  "created_at": "2026-08-01T14:22:10+00:00"
}

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

{
  "code": "invalid_invoice_line",
  "message": "El total de la factura (0 centavos) está fuera del rango cobrable (10000 a 10000000000 centavos)."
}

API

Empresas

Métodos de pago

Recaudo

Productos

Facturación

Balances

Webhooks

Fintech as a service

Headers

Body

​Headers

​Body

Headers

Body