Eliminar facturas masivamente

Elimina en bloque las facturas de la empresa, o las marca como pagadas por fuera de OnePay, según el motivo.

DELETE /invoices

Eliminar facturas masivamente

cURL

curl --request DELETE \
  --url https://api.onepay.la/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>",
  "provider_payment_id": "<string>",
  "payment_method": "<string>"
}
'

202

{}

Con DELETE_FROM_PROVIDER, el valor por defecto, la acción es irreversible: se eliminan las facturas de la empresa junto con sus cobros. Solo se salvan las que estén en PAID o CONCILIATED, las emitidas o en trámite ante la DIAN y las que tengan un cobro en curso o ya pagado en OnePay. Con PAID_FROM_PROVIDER las facturas no se borran: quedan en estado PAID_FROM_PROVIDER. Úsalo con precaución.

El proceso es asíncrono: el endpoint responde 202 Accepted de inmediato y las facturas se procesan en segundo plano. Toma todas las facturas de la empresa en el entorno de la llave (sk_test_ o sk_live_), excepto las que estén en PAID o CONCILIATED y las que ya tengan el estado del reason. Según el motivo:

• DELETE_FROM_PROVIDER: cada factura se elimina y su cobro se cancela. Las emitidas o en trámite ante la DIAN y las que tienen un cobro en curso o ya pagado en OnePay se saltan en silencio: quedan intactas y la respuesta no las reporta.
• PAID_FROM_PROVIDER: cada factura queda en estado PAID_FROM_PROVIDER y su cobro se cancela. Aquí no se salta ninguna por la DIAN ni por el cobro.

Reintentar no duplica el trabajo: mientras un borrado masivo de la empresa en ese entorno siga en cola, una nueva llamada responde 202 sin encolar otro, aunque traiga otro reason.

Body

reason · string · default: "DELETE_FROM_PROVIDER"

Motivo del retiro. Valores permitidos:

• DELETE_FROM_PROVIDER — Las facturas fueron anuladas o eliminadas en tu sistema. Por cada una, tu webhook recibe invoice.canceled (sin el objeto payment) y, si tenía cobro, también payment.deleted. Al cliente no se le envía nada, ni correo ni WhatsApp.
• PAID_FROM_PROVIDER — Las facturas fueron pagadas fuera de OnePay. Sus cobros se cancelan sin disparar eventos, así que no sale payment.deleted; por cada factura sale invoice.canceled con el objeto payment. Al cliente solo se le avisa si envías provider_payment_id.

Cualquier otro valor responde 422.

provider_payment_id · string

Referencia del pago en tu sistema, de hasta 255 caracteres. Solo aplica cuando reason es PAID_FROM_PROVIDER.

En el borrado masivo es el requisito para avisarle al cliente. Si lo envías, OnePay le manda por WhatsApp a cada cliente la confirmación de que su factura quedó registrada como pagada: un mensaje de texto, no un recibo en PDF. Sale solo cuando hay teléfono (el del cobro o, si no tiene, el del cliente). Si no lo envías, las facturas quedan igual en PAID_FROM_PROVIDER, pero no se le envía confirmación a nadie.

No se guarda en las facturas: el paid_provider_id de cada una queda como estaba.

payment_method · string

Medio con el que los clientes pagaron por fuera de OnePay. Solo se registra cuando reason es PAID_FROM_PROVIDER; con cualquier otro motivo se ignora.

Es texto libre de hasta 60 caracteres (Efectivo, Nequi, Consignación Bancolombia, Tarjeta) y se aplica a todas las facturas del lote, así que úsalo solo cuando el medio sea el mismo para todas. Queda disponible en el detalle de cada factura como paid_provider_method.

A diferencia de provider_payment_id —que identifica un pago puntual y por eso no se guarda en cada factura del lote—, el medio de pago sí se persiste en todas.

Ejemplos de uso

curl

curl https://api.onepay.la/v1/invoices \
  -X DELETE \
  -H "Authorization: Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "PAID_FROM_PROVIDER",
    "provider_payment_id": "EXT-REF-001",
    "payment_method": "Efectivo"
  }'

JavaScript

const response = await fetch('https://api.onepay.la/v1/invoices', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    reason: 'PAID_FROM_PROVIDER',
    provider_payment_id: 'EXT-REF-001',
    payment_method: 'Efectivo',
  }),
});
// 202 Accepted — las facturas se procesan en segundo plano

Python

import requests

response = requests.delete(
    'https://api.onepay.la/v1/invoices',
    headers={'Authorization': 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi'},
    json={
        'reason': 'PAID_FROM_PROVIDER',
        'provider_payment_id': 'EXT-REF-001',
        'payment_method': 'Efectivo',
    },
)
# 202 Accepted — las facturas se procesan en segundo plano
print(response.status_code)

Response

Responde 202 con un objeto vacío en cuanto encola el trabajo. Responde 422 si reason no es uno de los dos valores permitidos, payment_method pasa de 60 caracteres o provider_payment_id pasa de 255.

202

{}