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

# Servicios públicos

> Errores al consultar y pagar facturas de servicios públicos, crear links de pago y gestionar domiciliaciones.

Esta página cubre los endpoints de [Servicios públicos](/client/utilities/providers). Además de lo que se lista acá, cualquiera de ellos puede devolver los [errores comunes](/client/base/errors/common): llave inválida, falta de `x-idempotency`, validación o límite de peticiones.

Todas las rutas de `/utilities` responden `403` con `{"message": "Company does not have this feature."}` si tu empresa tiene apagado el módulo de servicios públicos. Viene activo por defecto; si lo ves, pídele a soporte que lo active.

<Note>
  **El pago es asíncrono.** `POST /utilities` responde `200` cuando OnePay pudo consultar la deuda y
  tu saldo alcanza; el pago al proveedor ocurre después, en segundo plano. Si el proveedor falla en
  ese paso, no recibes un error HTTP: lo ves en el `status` al [consultar el
  pago](#consultar-un-pago). Mira [Estados del pago después del
  200](#estados-del-pago-después-del-200).
</Note>

**Endpoints:** [Listar proveedores](#listar-proveedores) · [Consultar deuda](#consultar-deuda) · [Realizar pago](#realizar-pago) · [Consultar un pago](#consultar-un-pago) · [Crear link de pago](#crear-link-de-pago) · [Crear link de domiciliación](#crear-link-de-domiciliación) · [Listar domiciliaciones](#listar-domiciliaciones) · [Listar pagos de domiciliaciones](#listar-pagos-de-domiciliaciones) · [Eliminar domiciliación por referencia y teléfono](#eliminar-domiciliación-por-referencia-y-teléfono) · [Eliminar domiciliación por ID](#eliminar-domiciliación-por-id)

## Errores del proveedor de la factura

Para consultar o pagar una factura, OnePay le pregunta la deuda al proveedor del convenio. Si ese proveedor responde con un error, te llega uno de estos códigos. Salen tanto en [consultar deuda](#consultar-deuda) como en [realizar pago](#realizar-pago), porque el pago siempre consulta la deuda antes de crearse.

Si el convenio tiene más de un proveedor habilitado, OnePay los intenta en orden y te devuelve el error del último.

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `22000`<br />`bill_already_paid` | 418 | La factura ya ha sido pagada recientemente | El proveedor reporta que esa factura ya se pagó. | Confirma con tu cliente; no la vuelvas a cobrar. | No |
| `22001`<br />`bill_cannot_be_paid` | 400 | La factura no puede ser pagada error interno | El proveedor rechazó la consulta o tiene problemas con el servicio de recaudo. | Intenta más tarde. Si sigue, escribe a soporte con la referencia. | Sí, más tarde |
| `22002`<br />`bill_does_not_exist` | 404 | La factura no existe, o no se encuentra disponible en este momento | La referencia no existe en ese convenio, o el proveedor no respondió (caída, tiempo de espera, respuesta inesperada). | Revisa la referencia y el convenio. Si estás seguro de que son correctos, reintenta más tarde. | Sí, tras revisar la referencia |
| `22003`<br />`bill_does_not_have_debt` | 400 | La factura no tiene deuda pendiente para pagar | La factura existe pero no tiene saldo por pagar. | No hay nada que cobrar hasta que el convenio emita una nueva factura. | No |
| `22004`<br />`bill_does_not_have_provider` | 404 | La factura no tiene proveedor asignado | El convenio no tiene un proveedor habilitado para recaudar. | Escribe a soporte con el `provider_id`. | No |
| `22005`<br />`bill_expired` | 400 | La factura ha expirado | El proveedor reporta la factura vencida, o respondió con un error que no tiene un código propio. | Confirma con tu cliente la fecha de vencimiento. Si no está vencida, escribe a soporte. | No |
| `22006`<br />`bill_in_progress` | 400 | La factura ya se encuentra en proceso de pago | Hay un pago de esa factura en curso en el proveedor. | Vuelve a consultar la deuda en unos minutos. Antes de enviar otro `POST /utilities`, confirma el estado del pago anterior para no duplicarlo. | Solo la consulta |
| `22010`<br />`not_founds` | 404 | No se encontraron resultados | El recaudador de OnePay no tiene cupo disponible en este momento. No es un problema de la factura. | Reintenta más tarde. Si persiste, escribe a soporte. | Sí, más tarde |
| `22012`<br />`bill_try_latter` | 400 | Intente más tarde | El proveedor no está disponible temporalmente. | Reintenta con espera creciente (por ejemplo 1, 5 y 15 minutos). | Sí, con espera |
| `22013`<br />`bill_unknown_error` | 400 | Error desconocido en la factura | El proveedor respondió con un código que OnePay no reconoce. | Reintenta más tarde. Si persiste, escribe a soporte con la referencia. | Sí, más tarde |
| `220016`<br />`bill_amount_is_high` | 400 | El monto de la factura es mayor a 1.000.000 y no se puede pagar | La deuda es de COP 1.000.000 o más, el tope de este canal para el convenio. | Esta factura no se puede pagar por la API; tu cliente debe pagarla por otro canal. | No |

<Tip>
  Para decidir qué hacer, usa `code_name` y no el texto de `message`: el texto puede cambiar, el
  `code_name` no.
</Tip>

## Listar proveedores

`GET /utilities/providers` · [Referencia](/client/utilities/providers)

Este endpoint no tiene errores propios. Solo aplican los [errores comunes](/client/base/errors/common).

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| Sin código | 403 | Company does not have this feature. | Tu empresa tiene apagado servicios públicos. | Pídele a soporte que lo active. | No |

## Consultar deuda

`GET /utilities/providers/{provider}/{reference}` · [Referencia](/client/utilities/query)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, BillService no existe | El `provider` no existe, está deshabilitado o fue retirado. | Vuelve a [listar proveedores](/client/utilities/providers) y usa un `id` vigente. | No |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado | El `provider` no es un UUID. | Envía el `id` tal como lo devuelve el listado. | No |
| Sin código | 422 | La referencia no puede ser menor a 3 caracteres | La referencia tiene menos de 3 caracteres. | Corrige la referencia. | Sí, tras corregir |
| Sin código | 422 | La referencia no puede ser mayor a 50 caracteres | La referencia tiene más de 50 caracteres. | Corrige la referencia. | Sí, tras corregir |
| `220xx` | 400, 404, 418 | Ver tabla | El proveedor de la factura respondió con un error. | Ver [Errores del proveedor de la factura](#errores-del-proveedor-de-la-factura). | Según el código |

Una deuda consultada con éxito queda guardada una hora: si consultas la misma referencia dentro de esa hora, recibes el mismo resultado sin volver a preguntarle al proveedor. Los errores no se guardan.

## Realizar pago

`POST /utilities` · [Referencia](/client/utilities/payment)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10003`<br />`idempotency_error` | 409 | No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency | Falta el header `x-idempotency`. | Envía un valor único por pago en `x-idempotency`. | Sí, con el header |
| `10001`<br />`validation_error` | 422 | El campo provider id es obligatorio. | Falta `provider_id`, no es un UUID, o falta `reference`. | Revisa `errors` y corrige el cuerpo. | Sí, tras corregir |
| `10001`<br />`validation_error` | 422 | El provider id seleccionado es inválido. | El convenio no existe, está deshabilitado o fue retirado. | Vuelve a [listar proveedores](/client/utilities/providers). | Sí, tras corregir |
| `10001`<br />`validation_error` | 422 | El campo external id no debe ser mayor que 255 caracteres. | `external_id` tiene más de 255 caracteres. | Acorta tu identificador. | Sí, tras corregir |
| `10803`<br />`company_amount_limit` | 422 | La compañía no tiene fondos suficientes para realizar la operación | El saldo de tu empresa en OnePay es menor que la deuda de la factura. | Recarga tu saldo y vuelve a enviar el pago. | Sí, tras recargar |
| `220xx` | 400, 404, 418 | Ver tabla | El proveedor respondió con un error al consultar la deuda. El pago no se crea. | Ver [Errores del proveedor de la factura](#errores-del-proveedor-de-la-factura). | Según el código |

<Warning>
  Un `200` no significa que la factura quedó pagada: significa que el pago quedó en cola. Antes de
  reintentar un pago que creíste fallido, [consúltalo](#consultar-un-pago). Enviar otro `POST` con
  un `x-idempotency` nuevo crea un pago nuevo.
</Warning>

### Estados del pago después del 200

El pago al proveedor corre en segundo plano. Consulta su `status` con [`GET /utilities/{payment_id}`](/client/utilities/view).

| `status` | Qué significa | Qué hacer |
| - | - | - |
| `created`, `pending` | El pago está en cola para enviarse al proveedor. | Espera y vuelve a consultar. |
| `approved`, `confirmed` | El proveedor aceptó el pago. `paid_at` trae la fecha. | Nada: la factura quedó pagada. |
| `failed` | El último intento falló en el proveedor (rechazo, error del servicio). OnePay lo reintenta solo cada 14 minutos, hasta 50 veces. | No lo pagues de nuevo mientras siga en `failed`: puede pasar a `approved` en un reintento. Si sigue así después de un día, escribe a soporte con el `id`. |
| `expired` | El pago se cerró sin pagarse: la factura ya estaba pagada por otro registro, se retiró o venció. | Consulta la deuda de nuevo antes de crear otro pago. |

Mientras el proveedor esté fuera de horario, la factura no aparezca o no tenga deuda, el pago se queda en su estado actual y OnePay lo sigue reintentando en el mismo ciclo.

## Consultar un pago

`GET /utilities/{payment_id}` · [Referencia](/client/utilities/view)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, BillPayment no existe | El `payment_id` no existe. | Usa el `id` que devolvió `POST /utilities`. | No |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado | El pago es de otra empresa, o el `payment_id` no es un UUID. | Usa un `id` de tu empresa, tal como lo devolvió la API. | No |

## Crear link de pago

`POST /utilities/links` · [Referencia](/client/utilities/session-link)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10003`<br />`idempotency_error` | 409 | No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency | Falta el header `x-idempotency`. | Envía un valor único por link. | Sí, con el header |
| `10001`<br />`validation_error` | 422 | El campo reference es obligatorio. | Falta `reference`, `amount` o `redirect_url`, el monto está por debajo del mínimo de la moneda, o `redirect_url` no es una URL. | Revisa `errors` y corrige el cuerpo. | Sí, tras corregir |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, BillService no existe | Tu empresa no tiene un convenio propio configurado en OnePay. Este endpoint es para empresas que recaudan sus propias facturas. | Escribe a soporte para configurar tu convenio. | No |

## Crear link de domiciliación

`POST /utilities/direct-debits/link` · [Referencia](/client/utilities/auto-debit-link)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10003`<br />`idempotency_error` | 409 | No se puede generar la operación, genera un token de idempotencia y envíelo en los headers como x-idempotency | Falta el header `x-idempotency`. | Envía un valor único por link. | Sí, con el header |
| `10001`<br />`validation_error` | 422 | El campo reference es obligatorio. | Falta `reference` o tiene más de 60 caracteres, `phone` no es un teléfono válido, `approx_amount` es negativo, o `expiration_minutes` está fuera de 60 a 43.200. | Revisa `errors` y corrige el cuerpo. | Sí, tras corregir |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, BillService no existe | Tu empresa no tiene un convenio propio habilitado. | Escribe a soporte para configurar tu convenio. | No |

## Listar domiciliaciones

`GET /utilities/direct-debits` · [Referencia](/client/utilities/auto-debit-list)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, BillService no existe | Tu empresa no tiene un convenio propio configurado. | Escribe a soporte para configurar tu convenio. | No |
| Sin código | 400 | Requested filter(s) \`...\` are not allowed. Allowed filter(s) are \`document\_number, payment\_method\_type, reference, status\`. | Enviaste un `filter[...]` 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 \`payment\_method\_type, created\_at, updated\_at, reference, phone, email, status\`. | Enviaste un `sort` que no existe. | Usa solo los campos de la lista. | Sí, tras corregir |

## Listar pagos de domiciliaciones

`GET /utilities/direct-debits/payments` · [Referencia](/client/utilities/direct-debit-payments)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, BillService no existe | Tu empresa no tiene un convenio propio configurado. | Escribe a soporte para configurar tu convenio. | No |
| Sin código | 400 | Requested filter(s) \`...\` are not allowed. Allowed filter(s) are \`reference, status, bill\_id, amount\_in\_cents, paid\_at\`. | Enviaste un `filter[...]` 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 \`amount\_in\_cents, status, created\_at, paid\_at\`. | Enviaste un `sort` que no existe. | Usa solo los campos de la lista. | Sí, tras corregir |
| Sin código | 500 | Server Error | `filter[paid_at]` no es una fecha que se pueda leer. | Envía la fecha en formato `AAAA-MM-DD`. | Sí, tras corregir |

## Eliminar domiciliación por referencia y teléfono

`DELETE /utilities/direct-debits` · [Referencia](/client/utilities/auto-debit-delete-ref)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10001`<br />`validation_error` | 422 | El campo reference es obligatorio. (y 1 error más) | Falta `reference` o `phone`, o `phone` no es un teléfono válido. | Revisa `errors` y corrige el cuerpo. | Sí, tras corregir |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, BillService no existe | Tu empresa no tiene un convenio propio configurado. | Escribe a soporte para configurar tu convenio. | No |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, Bill no existe | No hay una domiciliación activa con esa referencia y ese teléfono en tu convenio, o ya se eliminó. | Revisa la referencia y el teléfono con [listar domiciliaciones](/client/utilities/auto-debit-list). | No |

## Eliminar domiciliación por ID

`DELETE /utilities/direct-debits/{bill_id}` · [Referencia](/client/utilities/auto-debit-delete)

| Código | HTTP | Mensaje | Causa probable | Qué hacer | ¿Reintentar? |
| - | - | - | - | - | - |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado, Bill no existe | El `bill_id` no existe o la domiciliación ya se eliminó. | Usa un `id` de [listar domiciliaciones](/client/utilities/auto-debit-list). | No |
| `10002`<br />`record_not_found` | 404 | Registro no encontrado | La domiciliación es de un convenio de otra empresa, o el `bill_id` no es un UUID. | Usa un `id` de tu convenio. | No |


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