Skip to navigation

Órdenes de compra

Una orden de compra es una venta a crédito a otro negocio: le mandas la orden con su factura, tu cliente la paga después con su link o por fuera de Recurrente (una transferencia, un cheque), y tú registras ese pago. Es lo mismo que el comercio hace en el panel desde Cobrar → Orden de compra y sigue en Finanzas → Por cobrar, ahora desde tu ERP, tu sistema de pedidos o un agente.

Si conoces las facturas de Stripe, el modelo es el mismo: un borrador que editas, lo finalizas para enviarlo, y luego se paga, se anula o se da por perdido.

Las órdenes de compra son para cuentas de negocio. Una cuenta personal recibe 403 con code: purchase_orders_not_available en todos sus endpoints.

Cuándo usarla

Usa una orden de compra cuando:

  • Le vendes a otra empresa y te paga a 15, 30, 60 o 90 días, o en una fecha.
  • Necesitas que la venta salga con su factura: si la cuenta emite facturas con Recurrente, la orden lleva una factura cambiaria, la factura de la SAT para ventas al crédito.
  • Tu cliente puede pagarte por fuera, todo o en abonos, y quieres que lo que te debe se mantenga al día.

Para cobrar en el momento, usa un checkout o un link de pago.

Ciclo de vida

EstadoQué significa
draftBorrador. No le ha llegado nada al comprador. Se edita y se elimina. También queda aquí una orden cuya factura no se certificó.
openEnviada y se debe. Ya no se edita, solo su metadata.
paidPagada, con su link o con pagos registrados por fuera.
voidAnulada: su factura se anuló ante la SAT y su link dejó de cobrar.
uncollectibleDada por perdida. Ya no cuenta en lo que te deben, pero su link sigue cobrando: si el comprador paga, pasa a paid.
draft ──finalization──▶ open ──▶ paid
│ │
└──DELETE (desaparece) ├──void──▶ void
└──uncollectible──▶ uncollectible ──▶ paid / void

Vencida no es un estado: una orden open con la fecha de vencimiento ya pasada lleva overdue: true.

El flujo típico

1. Crea la orden y envíala. Manda un monto (amount_in_cents, con description) o líneas (items), nunca los dos. Una línea es el price_id de un precio de pago único de tu tienda, o un name con su amount_in_cents que no aparece en tu catálogo. Identifica al comprador con customer_id, o con su correo y nombre para encontrarlo o crearlo. La orden guarda el nombre del comprador como se escribió (buyer_name, o el del cliente si no mandas uno): renombrar al cliente después no cambia una orden ya enviada. quantity es un entero mayor a 0: 1.9 o "2 cajas" se rechazan con 422. Usa un Idempotency-Key distinto por orden.

curl -X POST https://app.recurrente.com/api/purchase_orders \
-H "X-SECRET-KEY: sk_live_..." -H "Idempotency-Key: pedido-55120" \
-H "Content-Type: application/json" \
-d '{
"customer_id": "cus_3jfrywsf",
"items": [
{ "name": "Cajas de jabón líquido", "amount_in_cents": 4625, "quantity": 40 }
],
"net_days": 30,
"buyer_tax_id": "8812345",
"buyer_reference": "PO-889",
"external_reference": "SAP-55120",
"metadata": { "erp_id": "SO-55120" },
"send": true
}'

Sin send, la orden queda en draft y la envías después con POST /purchase_orders/{purchase_order_id}/finalization. Con send: true, en la misma llamada se certifica la factura, la orden pasa a open con su issued_on y su due_on, y le llega al comprador por correo (o por WhatsApp, o ambos, según delivery) con su link para pagar. Con delivery: link no se le envía nada: compartes tú checkout_url.

Si la factura no se certifica, la respuesta sigue siendo 201, pero la orden queda en draft con tax_invoice.status: failed y no se envía nada. Lee tax_invoice.error_code para saber qué hacer (ver Errores).

2. Registra lo que te pagan por fuera. Si tu cliente te transfirió a tu banco, regístralo. No mueve dinero; deja constancia y baja lo que debe. Puede ser un abono: la orden sigue open y su link cobra solo lo que falta. El pago que completa la deuda la deja paid.

curl -X POST https://app.recurrente.com/api/purchase_orders/oc_k3j9x2ab/payments \
-H "X-SECRET-KEY: sk_live_..." -H "Idempotency-Key: abono-48213" \
-H "Content-Type: application/json" \
-d '{ "amount_in_cents": 50000, "payment_method": "transfer", "reference": "TRX-48213" }'

Sin amount_in_cents registra todo lo que falta, con fecha de hoy. payment_method es transfer, deposit, cheque, cash u other (por defecto). La respuesta es la orden, con el pago en payments y lo que falta en amount_remaining_in_cents.

3. Escucha purchase_order.paid. Llega cuando la orden queda pagada, sea porque el comprador pagó con su link o porque tus pagos registrados completaron la deuda. Si pagó con su link, también recibes el webhook de ese cobro (intent.succeeded), como cualquier pago.

{
"event_type": "purchase_order.paid",
"api_version": "2024-04-24",
"id": "oc_k3j9x2ab",
"status": "paid",
"reference": "OC-1001",
"currency": "GTQ",
"total_in_cents": 185000,
"amount_paid_out_of_band_in_cents": 50000,
"amount_remaining_in_cents": 0,
"metadata": { "erp_id": "SO-55120" },
"paid_at": "2026-11-20T18:30:00Z"
}

El ejemplo muestra solo algunos campos: cada evento trae la orden completa, como la responde GET /purchase_orders/{id}. Usa metadata para encontrarla en tu sistema.

Evitar duplicados del ERP

Envía external_reference al crear la orden. Es opcional, de 1 a 255 caracteres, no puede contener solo espacios y distingue mayúsculas y minúsculas. Se compara exactamente como la envías, incluidos los espacios. Una vez asignada no cambia, ni en borrador; tampoco se puede agregar después con PATCH.

La referencia es única por cuenta y ambiente, sin vencimiento. Anular la orden o eliminar el borrador no la libera. Si SAP reenvía SAP-55120 un mes después, recibe 409 y no se crea ni envía otra orden:

{
"message": "Ya existe una orden con esta referencia externa.",
"code": "external_reference_exists",
"id": "oc_k3j9x2ab",
"status": "open",
"external_reference": "SAP-55120"
}

status es el estado actual de la orden original. Si fue eliminada, dice deleted. Consulta GET /purchase_orders/by_external_reference?external_reference=SAP-55120 para recuperar la orden completa; de una eliminada devuelve únicamente id, status y external_reference. Una referencia desconocida en esa cuenta y ambiente responde 404. Codifica la referencia como parámetro de query si tiene espacios, / u otros caracteres especiales.

Sigue usando Idempotency-Key para reintentos inmediatos: durante 24 horas puede reproducir la respuesta original; external_reference protege después de ese plazo y aunque cambie la llave de idempotencia. buyer_reference y metadata no son únicos. La referencia externa también viaja en los webhooks.

Todas las operaciones

OperaciónEndpointNotas
ListarGET /purchase_ordersFiltra por status, customer_id, overdue=true y from_time/until_time (fecha de creación). Paginada.
LeerGET /purchase_orders/{id}Con lo que se debe, los pagos registrados y la factura.
Buscar por referencia ERPGET /purchase_orders/by_external_reference?external_reference=SAP-55120Recupera la orden o su constancia de eliminación.
CrearPOST /purchase_ordersEn draft, salvo send: true.
EditarPATCH /purchase_orders/{id}Un borrador cambia lo que envíes y conserva lo demás (si solo mandas amount_in_cents, conserva su moneda), y recibe un checkout_url nuevo. Para cambiar la moneda de una orden con items, manda también sus items. Una orden enviada solo cambia su metadata; una llave en null se borra.
Eliminar un borradorDELETE /purchase_orders/{id}La orden desaparece: GET responde 404 y la lista ya no la incluye. Responde { "id": "oc_…", "status": "deleted" }.
EnviarPOST /purchase_orders/{purchase_order_id}/finalizationCertifica la factura y se la manda al comprador. Si la factura falla, llámalo otra vez para reintentar.
Registrar un pagoPOST /purchase_orders/{purchase_order_id}/paymentsPagos hechos por fuera, totales o abonos.
RecordarPOST /purchase_orders/{purchase_order_id}/reminderLe manda un recordatorio ahora, como «Recordar ahora» en Por cobrar. Uno por día.
Dar por perdidaPOST /purchase_orders/{purchase_order_id}/uncollectibleSolo una orden open. Detiene los recordatorios; la factura sigue vigente.
AnularPOST /purchase_orders/{purchase_order_id}/voidAnula la factura ante la SAT (o, pasado el plazo, emite una nota de crédito) y el link deja de cobrar. Acepta reason.

Una orden enviada no se corrige: anúlala y crea otra, como en el panel. Un borrador que no vas a enviar se elimina, no se anula. Lo mismo hace Descartar orden en el panel, y ambos emiten purchase_order.deleted.

Los recordatorios automáticos siguen la Política de cobro de la cuenta; send_reminders: false envía la orden con ellos en pausa.

Webhooks

Cada evento trae la orden como estaba en ese momento, con api_version.

EventoCuándo
purchase_order.createdSe creó un borrador, desde la API o desde Cobrar.
purchase_order.updatedSe editó con PATCH.
purchase_order.deletedSe eliminó un borrador (DELETE o «Descartar orden»). Trae la orden como estaba antes.
purchase_order.finalizedSe envió: la factura se certificó y la orden está open.
purchase_order.sentLe llegó al comprador por correo o WhatsApp. No se emite con delivery: link.
purchase_order.payment_recordedSe registró un pago hecho por fuera, total o abono.
purchase_order.paidQuedó pagada, con su link o con pagos registrados.
purchase_order.voidedSe anuló.
purchase_order.marked_uncollectibleSe dio por perdida.
purchase_order.will_be_dueLe faltan tres días o menos para vencer. Una vez por orden.
purchase_order.overduePasó su fecha de vencimiento sin pagarse. Una vez por orden, la mañana siguiente.

Las órdenes creadas en el panel emiten los mismos eventos. Para registrar tu endpoint y verificar las firmas, lee Webhooks.

Errores

Una transición que el estado de la orden no permite responde 422 con un code que puedes usar para decidir qué hacer:

codeDóndeQué significa
external_reference_immutableeditarLa referencia externa solo se asigna al crear y no se puede cambiar.
invalid_purchase_ordercrear, editarUn dato no es válido. errors dice qué campo y por qué, con los nombres de esta API.
not_drafteditar, eliminar, enviarLa orden ya se envió. Para corregirla, anúlala y crea otra.
fel_outcome_unknowneditar, eliminar, anularTodavía no sabemos si su factura se certificó. Llama a finalization para reintentar antes de cambiarla.
fel_issuedeliminarEl borrador ya tiene una factura certificada. Anúlalo.
fel_failedenviarLa factura no se certificó; la orden sigue en draft. Ver tax_invoice.error_code.
amount_changedenviarEl precio de un producto cambió desde que se creó la orden.
not_collectableregistrar un pagoLa orden ya no se debe, o nunca se envió.
payment_in_progressregistrar un pago, anularEl comprador la está pagando con su link. Reintenta en unos minutos.
invalid_paymentregistrar un pagoPor ejemplo, un monto mayor a lo que falta. Ver errors.
not_openrecordar, dar por perdida, anularLa orden no está abierta.
draftanularEs un borrador: no se anula, se elimina con DELETE.
fel_not_reversedanularLa SAT no anuló la factura; la orden sigue abierta. El message dice si vale la pena reintentar en unos minutos.
already_reminded_today, held, unreachable, contract_declined, already_sentrecordarYa se le recordó hoy, sus recordatorios están en pausa (o esperan una promesa de pago), la orden va solo con link y no hay a quién escribirle, el comprador rechazó el contrato, o ese recordatorio ya salió.

Por qué no se certificó la factura

Cuando la factura de una orden falla, tax_invoice.error_code dice quién puede resolverlo, y tax_invoice.error_message lo dice en español, como lo muestra Por cobrar:

error_codeQué pasóQué hacer
service_unavailableEl servicio de certificación no respondió a tiempo.Reintenta finalization en unos minutos.
buyer_tax_id_invalidLa SAT no reconoce el NIT del comprador.Corrige buyer_tax_id con PATCH (o elimina el borrador y crea otro) y envíala de nuevo.
buyer_tax_id_requiredArriba de Q2,500 la factura necesita el NIT del comprador.Igual: agrega buyer_tax_id y envíala de nuevo.
account_action_requiredAlgo de la cuenta ante la SAT (su firma, su régimen).error_message dice qué corregir; luego reintenta.
processing_errorCualquier otra falla.Ya lo estamos revisando.

Sandbox

En un Sandbox las órdenes de compra funcionan con estas diferencias:

  • La factura se simula: tiene uuid, pero no llega a la SAT ni tiene página (tax_invoice.url es null). Anular también se simula.
  • Al comprador no le llega nada, así que nunca recibes purchase_order.sent. Comparte checkout_url a mano y págalo con la tarjeta de prueba.
  • reminder está bloqueado, porque un Sandbox no le escribe a nadie.
  • Listar, leer, editar, eliminar, registrar pagos y dar por perdida funcionan igual que en vivo, sobre las órdenes del Sandbox.
  • Los eventos salen solo a los webhooks del Sandbox.

Agentes: CLI y MCP

Todas las operaciones de esta guía están en el catálogo de agentes, así que el CLI recurrente y el servidor MCP las corren sin código adicional:

recurrente purchase-orders list --overdue true
recurrente purchase-orders record-payment --purchase-order-id oc_k3j9x2ab --amount-in-cents 50000 --payment-method transfer