> ## 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.

# Facturación

> Errores de facturas y de facturación electrónica ante la DIAN.

Esta página cubre [Facturas](/client/invoices/index) y [Facturación electrónica (DIAN)](/client/electronic-invoices/index). Además de lo que se lista acá, cualquiera de estos endpoints puede devolver los [errores comunes](/client/base/errors/common). 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](#listar-facturas) · [Detalle](#detalle-de-una-factura) · [Crear](#crear-una-factura) · [Actualizar](#actualizar-una-factura) · [Eliminar](#eliminar-una-factura) · [Eliminar en bloque](#eliminar-facturas-en-bloque) · [Previsualizar](#previsualizar-una-factura-electrónica) · [Timbrar](#timbrar-una-factura) · [Nota crédito](#emitir-una-nota-crédito) · [Resoluciones](#resoluciones-de-facturación)

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](/client/base/errors/common#estado-de-tu-empresa).

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

  ```json theme={null}
  {
    "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.
</Note>

## Facturas

### Listar facturas

`GET /invoices` · [Referencia](/client/invoices/list) · [Facturas electrónicas](/client/electronic-invoices/list)

| 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](/client/invoices/get) · [Factura electrónica](/client/electronic-invoices/get)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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](/client/invoices/create) · [Factura electrónica](/client/electronic-invoices/create)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`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`<br />`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](/client/invoices/update)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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`<br />`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`<br />`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`<br />`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`<br />`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](#emitir-una-nota-crédito). | No |

### Eliminar una factura

`DELETE /invoices/{invoice_id}` · [Referencia](/client/invoices/delete)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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`<br />`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](/client/invoices/bulk-delete)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`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](/client/electronic-invoices/preview)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`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](/client/electronic-invoices/stamp)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`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](/client/electronic-invoices/credit-notes)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`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`<br />`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](/client/electronic-invoices/resolutions)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`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`<br />`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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.