Eliminar factura

Cancela el Payment asociado y marca la factura según el motivo.

DELETE /invoices/{invoice_id}

Eliminar factura

cURL

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

204

no content

Path params

invoice_id · string · required

ID de la factura a eliminar. Crear factura.

Body

reason · string · default: "DELETE_FROM_PROVIDER"

Motivo de la eliminación. Valores permitidos:

• DELETE_FROM_PROVIDER — La factura fue anulada o eliminada en tu sistema. La factura se elimina y su cobro se cancela. Al cliente no se le envía nada, ni correo ni WhatsApp. Tu webhook recibe invoice.canceled (sin el objeto payment) y, si la factura tenía cobro, también payment.deleted.
• PAID_FROM_PROVIDER — La factura fue pagada fuera de OnePay. La factura no se elimina: sobrevive en estado PAID_FROM_PROVIDER. El cobro asociado se cancela sin disparar sus eventos, así que no sale payment.deleted; el webhook invoice.canceled sí se emite, con el objeto payment incluido. Si hay teléfono, al cliente le llega una confirmación por WhatsApp.

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.

OnePay la guarda en la factura y la devuelve en el detalle como paid_provider_id. Si no la envías, usa como referencia el provider_id de la factura.

Este campo es opcional y no condiciona la confirmación por WhatsApp: con PAID_FROM_PROVIDER el mensaje sale igual, lo envíes o no. En el borrado masivo sí es requisito.

payment_method · string

Medio con el que el cliente pagó por fuera de OnePay (en la caja del proveedor, por transferencia, etc.). Solo se registra cuando reason es PAID_FROM_PROVIDER; con cualquier otro motivo se ignora.

Es texto libre de hasta 60 caracteres: envía la etiqueta tal como la maneja tu sistema (Efectivo, Nequi, Consignación Bancolombia, Tarjeta). OnePay lo guarda sin normalizar y lo devuelve en el detalle de la factura como paid_provider_method.

Este campo es opcional y no cambia la confirmación por WhatsApp, que solo depende de que haya un teléfono.

Qué pasa según el motivo

	DELETE_FROM_PROVIDER	PAID_FROM_PROVIDER
Factura	Se elimina	Queda en estado PAID_FROM_PROVIDER
Cobro asociado	Se cancela	Se cancela
Webhooks	invoice.canceled sin payment, y payment.deleted si había cobro	invoice.canceled con payment. No sale payment.deleted
Cliente	No recibe nada	Confirmación por WhatsApp, si hay teléfono
Factura emitida o en trámite ante la DIAN	409	Se permite
Cobro en curso o ya pagado en OnePay	409	Se permite

Confirmación al cliente

Con PAID_FROM_PROVIDER, OnePay le avisa al cliente por WhatsApp que su factura quedó registrada como pagada. Es un mensaje de texto, no un recibo en PDF:

✅ ¡Tu factura ya quedó registrada como pagada!

Vemos que pagaste Factura #12345 - Febrero 2024 por otro medio.

💡 La próxima vez puedes pagarla aquí mismo por WhatsApp en menos de 15 segundos, sin filas ni pasos extra.

El concepto es la description de la factura o, si no tiene, su name. El formato depende de la ventana de 24 horas de WhatsApp:

• Si el cliente escribió por WhatsApp en las últimas 24 horas, llega como mensaje interactivo con un botón «¡Gracias!».
• Si no, llega con la plantilla external_payment_confirmed, con el mismo texto.

Solo sale si hay un teléfono: el del cobro o, si el cobro no tiene, el del cliente. Una factura sin cobro asociado no genera mensaje.

Ejemplos de uso

curl

curl https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a \
  -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/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a', {
  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',
  }),
});
// 204 No Content

Python

import requests

response = requests.delete(
    'https://api.onepay.la/v1/invoices/2f2b1e5a-1a2b-4c33-8a18-5e9f3b9f4b1a',
    headers={'Authorization': 'Bearer sk_test_KjbE0Vobf5Lg1yNZ4HoKawDItDs3Rod9VXNBWrEYmGn06tkesPIi'},
    json={
        'reason': 'PAID_FROM_PROVIDER',
        'provider_payment_id': 'EXT-REF-001',
        'payment_method': 'Efectivo',
    },
)
# 204 No Content

Response

Responde 204 sin cuerpo. Los errores posibles:

• 404 — La factura no existe, es de otra compañía o es del otro entorno: una factura creada con sk_live_ no se encuentra con sk_test_, y al revés.
• 409 — La factura está en PAID o CONCILIATED. Con DELETE_FROM_PROVIDER también responde 409 si la factura fue emitida o está en trámite ante la DIAN (si ya fue aceptada, se anula con una nota crédito), o si su cobro está en curso o ya se pagó en OnePay; con PAID_FROM_PROVIDER esos dos casos no aplican.
• 422 — reason no es uno de los dos valores permitidos, payment_method pasa de 60 caracteres o provider_payment_id pasa de 255.

204

no content

Este endpoint forma parte de la homologación de la integración: los dos motivos se validan por separado, porque corresponden a situaciones distintas y no son intercambiables.