> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.recurrente.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.recurrente.com/_mcp/server.

# Órdenes de compra

> Vende a crédito a otra empresa con su factura, regístrale los pagos que te hace por fuera y entérate cuando paga, vence o se anula

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.

> **Note**
>
> 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](/referencia-api/api-reference/checkouts/create-checkout) o un link de pago.

## Ciclo de vida

| Estado          | Qué significa                                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `draft`         | Borrador. No le ha llegado nada al comprador. Se edita y se elimina. También queda aquí una orden cuya factura no se certificó. |
| `open`          | Enviada y se debe. Ya no se edita, solo su `metadata`.                                                                          |
| `paid`          | Pagada, con su link o con pagos registrados por fuera.                                                                          |
| `void`          | Anulada: su factura se anuló ante la SAT y su link dejó de cobrar.                                                              |
| `uncollectible` | Dada 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.

```bash
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](#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`.

```bash
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.

```json
{
  "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:

```json
{
  "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ón                 | Endpoint                                                                  | Notas                                                                                                                                                                                                                                                                                                 |
| ------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Listar                    | `GET /purchase_orders`                                                    | Filtra por `status`, `customer_id`, `overdue=true` y `from_time`/`until_time` (fecha de creación). Paginada.                                                                                                                                                                                          |
| Leer                      | `GET /purchase_orders/{id}`                                               | Con lo que se debe, los pagos registrados y la factura.                                                                                                                                                                                                                                               |
| Buscar por referencia ERP | `GET /purchase_orders/by_external_reference?external_reference=SAP-55120` | Recupera la orden o su constancia de eliminación.                                                                                                                                                                                                                                                     |
| Crear                     | `POST /purchase_orders`                                                   | En `draft`, salvo `send: true`.                                                                                                                                                                                                                                                                       |
| Editar                    | `PATCH /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 borrador      | `DELETE /purchase_orders/{id}`                                            | La orden desaparece: `GET` responde `404` y la lista ya no la incluye. Responde `{ "id": "oc_…", "status": "deleted" }`.                                                                                                                                                                              |
| Enviar                    | `POST /purchase_orders/{purchase_order_id}/finalization`                  | Certifica la factura y se la manda al comprador. Si la factura falla, llámalo otra vez para reintentar.                                                                                                                                                                                               |
| Registrar un pago         | `POST /purchase_orders/{purchase_order_id}/payments`                      | Pagos hechos por fuera, totales o abonos.                                                                                                                                                                                                                                                             |
| Recordar                  | `POST /purchase_orders/{purchase_order_id}/reminder`                      | Le manda un recordatorio ahora, como «Recordar ahora» en Por cobrar. Uno por día.                                                                                                                                                                                                                     |
| Dar por perdida           | `POST /purchase_orders/{purchase_order_id}/uncollectible`                 | Solo una orden `open`. Detiene los recordatorios; la factura sigue vigente.                                                                                                                                                                                                                           |
| Anular                    | `POST /purchase_orders/{purchase_order_id}/void`                          | Anula 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`.

| Evento                                | Cuándo                                                                                  |
| ------------------------------------- | --------------------------------------------------------------------------------------- |
| `purchase_order.created`              | Se creó un borrador, desde la API o desde Cobrar.                                       |
| `purchase_order.updated`              | Se editó con `PATCH`.                                                                   |
| `purchase_order.deleted`              | Se eliminó un borrador (`DELETE` o «Descartar orden»). Trae la orden como estaba antes. |
| `purchase_order.finalized`            | Se envió: la factura se certificó y la orden está `open`.                               |
| `purchase_order.sent`                 | Le llegó al comprador por correo o WhatsApp. No se emite con `delivery: link`.          |
| `purchase_order.payment_recorded`     | Se registró un pago hecho por fuera, total o abono.                                     |
| `purchase_order.paid`                 | Quedó pagada, con su link o con pagos registrados.                                      |
| `purchase_order.voided`               | Se anuló.                                                                               |
| `purchase_order.marked_uncollectible` | Se dio por perdida.                                                                     |
| `purchase_order.will_be_due`          | Le faltan tres días o menos para vencer. Una vez por orden.                             |
| `purchase_order.overdue`              | Pasó 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](/guias-espanol/comenzar/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:

| `code`                                                                               | Dónde                             | Qué significa                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `external_reference_immutable`                                                       | editar                            | La referencia externa solo se asigna al crear y no se puede cambiar.                                                                                                                                          |
| `invalid_purchase_order`                                                             | crear, editar                     | Un dato no es válido. `errors` dice qué campo y por qué, con los nombres de esta API.                                                                                                                         |
| `not_draft`                                                                          | editar, eliminar, enviar          | La orden ya se envió. Para corregirla, anúlala y crea otra.                                                                                                                                                   |
| `fel_outcome_unknown`                                                                | editar, eliminar, anular          | Todavía no sabemos si su factura se certificó. Llama a `finalization` para reintentar antes de cambiarla.                                                                                                     |
| `fel_issued`                                                                         | eliminar                          | El borrador ya tiene una factura certificada. Anúlalo.                                                                                                                                                        |
| `fel_failed`                                                                         | enviar                            | La factura no se certificó; la orden sigue en `draft`. Ver `tax_invoice.error_code`.                                                                                                                          |
| `amount_changed`                                                                     | enviar                            | El precio de un producto cambió desde que se creó la orden.                                                                                                                                                   |
| `not_collectable`                                                                    | registrar un pago                 | La orden ya no se debe, o nunca se envió.                                                                                                                                                                     |
| `payment_in_progress`                                                                | registrar un pago, anular         | El comprador la está pagando con su link. Reintenta en unos minutos.                                                                                                                                          |
| `invalid_payment`                                                                    | registrar un pago                 | Por ejemplo, un monto mayor a lo que falta. Ver `errors`.                                                                                                                                                     |
| `not_open`                                                                           | recordar, dar por perdida, anular | La orden no está abierta.                                                                                                                                                                                     |
| `draft`                                                                              | anular                            | Es un borrador: no se anula, se elimina con `DELETE`.                                                                                                                                                         |
| `fel_not_reversed`                                                                   | anular                            | La 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_sent` | recordar                          | Ya 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_code`              | Qué pasó                                                   | Qué hacer                                                                                  |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `service_unavailable`     | El servicio de certificación no respondió a tiempo.        | Reintenta `finalization` en unos minutos.                                                  |
| `buyer_tax_id_invalid`    | La 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_required`   | Arriba de Q2,500 la factura necesita el NIT del comprador. | Igual: agrega `buyer_tax_id` y envíala de nuevo.                                           |
| `account_action_required` | Algo de la cuenta ante la SAT (su firma, su régimen).      | `error_message` dice qué corregir; luego reintenta.                                        |
| `processing_error`        | Cualquier otra falla.                                      | Ya lo estamos revisando.                                                                   |

## Sandbox

En un [Sandbox](/guias-espanol/guias/sandboxes-y-test-clocks) 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:

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