Facturación

Esta página cubre Facturas y Facturación electrónica (DIAN). Además de lo que se lista acá, cualquiera de estos endpoints puede devolver los errores comunes. Los que tienen un ID en la ruta también responden 404 record_not_found si el ID no es un UUID, y 404 environment_key_mismatch si el recurso es del otro ambiente. Endpoints: Listar facturas · Detalle · Crear · Actualizar · Eliminar · Eliminar en bloque · Previsualizar · Timbrar · Nota crédito · Resoluciones Todas las rutas de /invoices responden 403 sin código si tu plan no incluye facturación («Tu plan actual no incluye esta funcionalidad. Mejora tu plan para activarla.») o tiene un pago pendiente. Mira Estado de tu empresa.

Los errores propios de la facturación electrónica usan otro formato: code es un texto y no hay code_name.

{
  "code": "invoice_not_stampable",
  "message": "La factura 9d1cd37a-a6bc-472d-b4e6-c913769d005a tiene stamp_policy `none` y no se puede timbrar a mano: ..."
}

En las tablas aparecen con el texto de code. Algunos traen además errors por campo.

Facturas

Listar facturas

GET /invoices · Referencia · Facturas electrónicas

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
Sin código	400	Requested filter(s) `…` are not allowed. Allowed filter(s) are `id, status, reference, provider_id, paid_provider_method_type`.	Enviaste un filtro que no existe.	Usa solo los filtros de la lista.	Sí, tras corregir
Sin código	400	Requested sort(s) `…` is not allowed. Allowed sort(s) are `created_at`.	Enviaste un orden que no existe.	Ordena por `created_at`.	Sí, tras corregir

Detalle de una factura

GET /invoices/{invoice_id} · Referencia · Factura electrónica

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, Invoice no existe	La factura no existe, se eliminó o es de otra empresa.	Revisa el `invoice_id`.	No

Crear una factura

POST /invoices · Referencia · Factura electrónica

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `validation_error`	422	El campo nombre es obligatorio.	Sin `items`: faltan `provider_id`, `reference`, `provider`, `amount` o `name`, o el monto está fuera de COP 1.000 a 100.000.000. Con `items`: falta `customer_id` o no es un cliente tuyo del mismo ambiente.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`10001` `validation_error`	422	The partial payment feature is not enabled for this company.	Enviaste `partial_payment` y tu empresa no tiene pagos parciales.	Quita `partial_payment` o pídele a soporte activarlo.	No
`customer_not_invoiceable`	422	No se puede facturar: al cliente le faltan datos que exige la DIAN (…).	Factura electrónica que se emite al crearla o al pagarla, y al cliente le faltan datos fiscales (correo, nombre, documento, dirección, DV o responsabilidades). `errors` trae cada campo.	Completa los datos del cliente, o crea la factura con `stamp_policy` `manual` o `none`.	Sí, tras corregir
`invalid_invoice_line`	422	La línea N referencia el precio …, que no existe en esta empresa.	Un `items[].price_id` no existe en tu empresa o es del otro ambiente.	Usa un `price_id` de tu catálogo en el mismo ambiente.	Sí, tras corregir
`invalid_invoice_line`	422	El total de la factura (… centavos) está fuera del rango cobrable (10000 a 10000000000 centavos).	El total de las líneas queda por debajo de COP 100 o por encima de COP 100.000.000.	Ajusta cantidades o montos.	Sí, tras corregir

Si la factura ya existe (mismo proveedor y referencia), la respuesta es 201 con la factura existente: no es un error.

Actualizar una factura

PUT /invoices/{invoice_id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, Invoice no existe	La factura no existe, se eliminó o es de otra empresa.	Revisa el `invoice_id`.	No
`10001` `validation_error`	422	El campo nombre es obligatorio.	Falta `reference`, `amount` o `name`, el monto está fuera de rango, o `phone`/`email` no son válidos. El cuerpo se valida completo.	Revisa `errors` y envía el cuerpo completo.	Sí, tras corregir
`15004` `payment_charge_in_progress`	422	Este pago tiene una transacción activa en proceso. Por favor espera a que expire e intenta nuevamente.	El cobro de la factura tiene un intento de pago en curso.	Espera a que termine o venza.	Sí, con espera
`15004` `payment_cancelled`	422	El pago fue cancelado	El cobro de la factura ya está cancelado o vencido.	Escribe a soporte: hoy no se puede actualizar por API una factura con el cobro cancelado.	No
`15003` `payment_already_paid`	422	Este pago ya fue pagado.	El cobro se terminó de pagar mientras actualizabas.	Consulta la factura: ya está pagada.	No
Sin código	500	Server Error	La factura es electrónica y ya está timbrada ante la DIAN.	No edites facturas timbradas: corrígelas con una nota crédito.	No

Eliminar una factura

DELETE /invoices/{invoice_id} · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, Invoice no existe	La factura no existe, ya se eliminó o es de otra empresa.	Revisa el `invoice_id`.	No
`10001` `validation_error`	422	El reason seleccionado no es válido.	`reason` no es `PAID_FROM_PROVIDER` ni `DELETE_FROM_PROVIDER`, o `provider_payment_id` o `payment_method` son muy largos.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
Sin código	409	No se puede eliminar una factura que ya fue pagada o conciliada.	La factura ya se pagó en OnePay.	Trátala como estado final.	No
Sin código	409	No se puede eliminar una factura emitida o en trámite ante la DIAN. Si ya fue aceptada, se anula con una nota crédito.	La factura electrónica está timbrada o en trámite.	Anúlala con una nota crédito, o usa `PAID_FROM_PROVIDER` si se pagó por fuera.	No
Sin código	409	No se puede eliminar una factura con un cobro en curso o ya pagado en OnePay.	El cobro de la factura está en curso o pagado.	Espera a que el cobro termine; si se pagó, no la elimines.	Sí, si estaba en curso
Sin código	409	No se puede cerrar una factura con un cobro en curso en OnePay. Reintente cuando el cobro termine.	El cobro tiene un intento de pago en curso.	Reintenta cuando el cobro se resuelva.	Sí, con espera

Eliminar facturas en bloque

DELETE /invoices · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `validation_error`	422	El reason seleccionado no es válido.	`reason` no es `PAID_FROM_PROVIDER` ni `DELETE_FROM_PROVIDER`, o `provider_payment_id` o `payment_method` son muy largos.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir

Facturación electrónica

Previsualizar una factura electrónica

POST /invoices/preview · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `validation_error`	422	El campo items es obligatorio.	Faltan `items`, hay más de 200 líneas, una línea no trae `price_id` ni `description` y `unit_amount`, o el impuesto no es válido.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`invalid_invoice_line`	422	La línea N referencia el precio …, que no existe en esta empresa.	Un `price_id` no existe en tu empresa o es del otro ambiente.	Usa un `price_id` de tu catálogo en el mismo ambiente.	Sí, tras corregir

La previsualización no aplica el rango cobrable de COP 100 a 100.000.000: puede mostrar un total que la creación rechaza.

Timbrar una factura

POST /invoices/{invoice_id}/stamp · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10002` `record_not_found`	404	Registro no encontrado, Invoice no existe	La factura no existe, se eliminó o es de otra empresa.	Revisa el `invoice_id`.	No
`invoice_not_stampable`	422	La factura … fue importada de … y no se timbra por OnePay.	La factura vino de tu sistema de gestión, no se creó con `items`.	Solo se timbran facturas creadas con `items`.	No
`invoice_not_stampable`	422	La factura … tiene stamp_policy `…` y no se puede timbrar a mano: con `on_payment` la emisión la dispara el pago, y con `none` no se emite. Para forzarla, cambia la política a `manual`.	La factura tiene `stamp_policy` `on_payment` o `none`.	Cambia la política a `manual` antes de timbrar.	No

Emitir una nota crédito

POST /invoices/{invoice_id}/credit-notes · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `validation_error`	422	El campo cantidad debe ser un número entero.	`amount` no es un entero mayor que 0, o `reason` tiene más de 500 caracteres.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`10002` `record_not_found`	404	Registro no encontrado, Invoice no existe	La factura no existe, se eliminó o es de otra empresa.	Revisa el `invoice_id`.	No
`credit_note_not_issuable`	422	La factura … no tiene ningún timbrado aceptado por la DIAN, así que no hay nada que corregir con una nota crédito.	La factura no está timbrada o su timbrado no fue aceptado.	Timbra la factura primero, o elimínala.	No
`credit_note_not_issuable`	422	La nota crédito por … excede lo que queda por devolver de la factura: total …, ya devuelto …, disponible …	`amount` supera lo que falta por acreditar.	Envía un `amount` menor o igual al disponible.	Sí, tras corregir
`credit_note_not_issuable`	422	El monto de la nota crédito debe ser mayor a cero (llegó …).	No enviaste `amount` (anulación total) y ya no queda saldo por acreditar.	Consulta las notas crédito de la factura antes de emitir otra.	No
`invoice_not_stampable`	422	La factura … fue importada de … y no se timbra por OnePay.	La factura no se emitió por OnePay.	Las notas crédito solo aplican a facturas emitidas por OnePay.	No
`invoice_not_stampable`	422	La factura … está marcada para no facturarse electrónicamente (stamp_policy: none).	La factura tiene `stamp_policy` `none`.	Cambia la política de la factura.	No
`invoice_not_stampable`	422	El receptor tiene el mismo NIT del emisor (…): un contribuyente no se factura a sí mismo y la DIAN rechaza el documento.	El cliente facturado tiene el mismo NIT que tu empresa.	Corrige el documento del cliente.	No
`invoice_not_stampable`	422	La empresa no tiene su identificador de emisor cargado para este entorno, así que el documento saldría a nombre de OnePay. …	Tu empresa no está registrada como emisor en este ambiente.	Escribe a soporte para registrar el emisor.	No
`invoice_not_stampable`	422	El timbrado ante la DIAN está desactivado.	OnePay desactivó temporalmente el timbrado.	Reintenta más tarde.	Sí, más tarde
`customer_not_invoiceable`	422	No se puede facturar: al cliente le faltan datos que exige la DIAN (…).	Al cliente le faltan datos fiscales. `errors` trae cada campo.	Completa los datos del cliente.	Sí, tras corregir
Sin código	500	Server Error	Tu empresa no tiene una resolución activa de notas crédito (o la que tiene venció o se agotó).	Carga y activa una resolución con `document_type` `credit_note`.	Sí, tras activarla
Sin código	500	Server Error	El proveedor de timbrado no respondió al enviar la nota.	No reintentes a ciegas: consulta la factura y escribe a soporte con el `x-request-id`.	No, sin verificar

Resoluciones de facturación

GET /fiscal-resolutions, POST /fiscal-resolutions y POST /fiscal-resolutions/{resolution_id}/activate · Referencia

Código	HTTP	Mensaje	Causa probable	Qué hacer	¿Reintentar?
`10001` `validation_error`	422	El campo número es obligatorio.	Al crear: falta `number`, `document_type`, `from` o `to`; `document_type` no es `invoice`, `credit_note` ni `debit_note`; `to` es menor que `from`; o `valid_until` no es posterior a `valid_from`.	Revisa `errors` y corrige el cuerpo.	Sí, tras corregir
`10002` `record_not_found`	404	Registro no encontrado, FiscalResolution no existe	Al activar: la resolución no existe, se eliminó o es de otra empresa.	Revisa el `resolution_id`.	No
`resolution_not_activatable`	422	La resolución … venció el … y no se puede activar.	La resolución ya venció.	Solicita una resolución nueva a la DIAN y cárgala.	No
`resolution_not_activatable`	422	La resolución … ya consumió todo su rango (…) y no se puede activar.	A la resolución no le quedan números.	Solicita una resolución nueva a la DIAN.	No
`resolution_not_activatable`	422	El rango … se solapa con el de la resolución … (…), que ya existe para el mismo tipo de documento. Dos resoluciones que comparten números emiten documentos legales duplicados.	El rango se cruza con otra resolución tuya del mismo tipo, en cualquier estado.	Crea una resolución nueva con el rango correcto.	No

API

Empresas

Métodos de pago

Recaudo

Productos

Balances

Webhooks

Fintech as a service

Facturación

Facturas

Listar facturas

Detalle de una factura

Crear una factura

Actualizar una factura

Eliminar una factura

Eliminar facturas en bloque

Facturación electrónica

Previsualizar una factura electrónica

Timbrar una factura

Emitir una nota crédito

Resoluciones de facturación

​Facturas

​Listar facturas

​Detalle de una factura

​Crear una factura

​Actualizar una factura

​Eliminar una factura

​Eliminar facturas en bloque

​Facturación electrónica

​Previsualizar una factura electrónica

​Timbrar una factura

​Emitir una nota crédito

​Resoluciones de facturación

Facturas

Listar facturas

Detalle de una factura

Crear una factura

Actualizar una factura

Eliminar una factura

Eliminar facturas en bloque

Facturación electrónica

Previsualizar una factura electrónica

Timbrar una factura

Emitir una nota crédito

Resoluciones de facturación