Skip to navigation

Crear una orden de compra

Crea una orden de compra en borrador (draft) junto con la venta que cobra: un monto (amount_in_cents) o productos de tu tienda (items), nunca los dos. Nada le llega al comprador hasta que la envías con POST /purchase_orders/{purchase_order_id}/finalization.

Al comprador se le encuentra o se le crea como cliente por su correo, o por su WhatsApp cuando la orden va solo por ahí. Con delivery: link no se le envía nada: compartes checkout_url tú.

Si tu cuenta emite facturas electrónicas con Recurrente, la orden pide su factura (una Factura Cambiaria) salvo que mandes issue_tax_invoice: false. Un NIT que la SAT no reconoce se rechaza aquí, y arriba de Q2,500 la factura necesita el NIT del comprador.

Usa un Idempotency-Key único por orden. Para impedir duplicados sin vencimiento, envía también external_reference: es única por cuenta y ambiente, incluso después de anular o eliminar. Repetirla responde 409 external_reference_exists con el id y status actuales de la orden original (deleted si fue eliminada), sin crear ni enviar otra. Una repetición de la misma Idempotency-Key dentro de sus 24 horas sigue devolviendo la respuesta original almacenada.

Authentication

X-SECRET-KEYstring

Tu clave secreta de API.

Una llave de cuenta (sk_live_..., sk_test_...) opera sobre su propia cuenta y, con X-ACCOUNT-ID, sobre sus cuentas conectadas.

La llave también fija el ambiente: una sk_test_ solo lista y resuelve objetos de prueba (live_mode: false) y una sk_live_ solo objetos reales. Un ID del otro ambiente responde 404 (401 en /customers).

Una llave de organización (sk_org_live_..., sk_org_test_...) alcanza todas las cuentas de una organización y solo sirve para leer: saldos, movimientos y reportes. Para operar sobre una cuenta debe nombrarla con X-ACCOUNT-ID; omitirlo en una lectura devuelve todas las cuentas de la organización. Cualquier otro endpoint responde 403 con code: organization_key_unsupported.

Headers

X-ACCOUNT-IDstringOptional

ID de una cuenta hija conectada. Ejecuta el request dentro de esa cuenta, como Stripe-Account en Stripe Connect. La plataforma puede acceder a todos los recursos API que pertenecen a la hija, sin filtrar por creador. Solo aplica a hijas directas: si la cuenta no está conectada a la tuya, el request responde 404 con code: connected_account_not_found.

Con una llave de organización este header nombra la cuenta miembro sobre la que quieres operar; si no pertenece a la organización, el request responde 404 con code: organization_account_not_found. En una lectura puedes omitirlo para abarcar todas las cuentas de la organización.

Request

Lo que se envía para crear o editar una orden de compra.

amount_in_centsintegerOptional

Monto de la orden, en centavos. Envía este o items.

currencystringOptional
Moneda del monto. Por defecto, la moneda principal de tu cuenta.
itemslist of objectsOptional

Productos de tu tienda que vende la orden. Envía este o amount_in_cents.

descriptionstringOptional<=100 characters

Qué vende la orden, como lo lee el comprador. Solo con amount_in_cents; sin ella, la línea se llama como la orden.

buyer_namestringOptional

Nombre o razón social del comprador. Si lo omites y mandas un NIT, se usa el nombre que la SAT tiene para ese NIT.

deliveryenumOptionalDefaults to email

Por dónde le llega la orden al comprador: email, whatsapp, ambos (both), o link para no enviarle nada y compartir tú el link.

Allowed values:
buyer_emailstringOptional

Correo del comprador. Requerido con delivery email o both.

buyer_phonestringOptional

WhatsApp del comprador. Requerido con delivery whatsapp o both.

cc_emailslist of stringsOptional

Hasta tres correos que reciben copia (cuentas por pagar, un gerente)

buyer_tax_idstringOptional

NIT del comprador para su factura. Vacío es consumidor final.

external_referencestring or nullOptional1-255 characters

Referencia opcional del ERP, única por cuenta y ambiente para siempre, incluso si la orden se anula o elimina. Distingue mayúsculas y minúsculas y conserva espacios; no acepta texto vacío ni solo espacios. Solo se asigna al crear: no se puede cambiar ni agregar con PATCH (422 external_reference_immutable). null al crear equivale a omitirla.

buyer_referencestringOptional<=60 characters

El número con el que el comprador archiva su orden de compra. Va en el asunto del correo, la factura y la página de pago.

net_daysenumOptional

Días de crédito desde que se envía. Por defecto, 30.

Allowed values:
due_ondateOptional

Fecha de vencimiento propia, a partir de mañana. Reemplaza a net_days.

issue_tax_invoicebooleanOptional

false envía la orden sin factura. Solo aplica si tu cuenta emite facturas electrónicas con Recurrente.

contract_template_idstringOptional
Plantilla de contrato que el comprador firma antes de poder pagar
send_remindersbooleanOptionalDefaults to true

false envía la orden con sus recordatorios en pausa.

customer_idstringOptional

Cliente comprador, de esta cuenta y del ambiente de tu llave (como lo ve GET /customers). Su nombre, correo, WhatsApp y NIT llenan lo que no envíes; un buyer_name que envíes queda en la orden, sin renombrar al cliente. Sin él, al comprador se le encuentra o se le crea por su correo o su WhatsApp.

metadatamap from strings to anyOptional

Hasta 50 llaves (de 40 caracteres) con valores de hasta 500 caracteres. Al editar se combina con la que tiene; una llave en null se borra.

sendbooleanOptionalDefaults to false

true la envía en la misma llamada, como POST /purchase_orders/{purchase_order_id}/finalization. Si la factura no se certifica, la respuesta es 201 con la orden en draft y tax_invoice.status: failed.

Response

Orden creada en borrador
idstringOptional
ID de la orden de compra
statusenumOptional

draft no se ha enviado (o su factura no se certificó); open se envió y se debe; paid se pagó, con su link o afuera; void se anuló; uncollectible se dio por perdida, aunque su link sigue cobrando.

Allowed values:
overduebooleanOptional

Abierta y con la fecha de vencimiento ya pasada. «Vencida» no es un estado.

referencestringOptional

Número de la orden con su prefijo, como lo ve el comprador

external_referencestring or nullOptional

Referencia inmutable del ERP; también se incluye en los webhooks

prefixstringOptional
numberintegerOptional
Consecutivo de la orden en tu cuenta
descriptionstring or nullOptional

Qué vende, como lo lee el comprador

checkout_urlstringOptional
Link donde el comprador paga la orden. No vence mientras la orden se deba.
metadatamap from strings to anyOptional

La metadata que tu integración le puso

currencystringOptional
total_in_centsintegerOptional
Total de la orden, en centavos
amount_paid_out_of_band_in_centsintegerOptional

Lo que se registró como pagado fuera de Recurrente, en centavos

amount_remaining_in_centsintegerOptional

Lo que el comprador todavía debe, en centavos. 0 si está pagada o anulada.

paymentslist of objectsOptional

Pagos registrados fuera de Recurrente, del más antiguo al más reciente

net_daysinteger or nullOptional

Días de crédito desde que se envió. null cuando la orden tiene una fecha de vencimiento propia.

issued_ondate or nullOptional

Fecha en que se envió. null en borrador.

due_ondate or nullOptional
Fecha de vencimiento
promised_ondate or nullOptional

Fecha en que el comprador prometió pagar, si la registraste en el dashboard

reminders_pausedbooleanOptional

Los recordatorios automáticos están en pausa

void_reasonstring or nullOptional

Por qué se anuló

customer_idstringOptional
ID del cliente comprador
buyer_namestringOptional

Nombre o razón social del comprador como se escribió en la orden (lo que envió buyer_name, o el nombre del cliente). Renombrar al cliente después no lo cambia.

buyer_emailstring or nullOptional

Correo al que se envía la orden

buyer_phonestring or nullOptional

WhatsApp al que se envía la orden

buyer_tax_idstring or nullOptional

NIT de la factura. null es consumidor final.

buyer_referencestring or nullOptional

El número con el que el comprador archiva su orden de compra

cc_emailslist of stringsOptional
Correos que reciben copia
tax_invoice_requestedbooleanOptional

La orden se envía con factura electrónica

tax_invoiceobject or nullOptional

La factura de la orden tal como está (el último intento de certificarla). null si no se ha intentado.

sent_atdatetime or nullOptional
paid_atdatetime or nullOptional
voided_atdatetime or nullOptional
uncollectible_atdatetime or nullOptional
created_atdatetimeOptional
updated_atdatetimeOptional

Errors

403
Forbidden Error
409
Conflict Error
422
Unprocessable Entity Error