Órdenes

Compra de certificados PREPAID: crear orden, ejecutar pago WOMPI, consultar estado y reintentar el pago de órdenes que siguen en PENDING. Cada orden se compra para un tipo de emisión (issuance_flow: BIOMETRIC / DOCUMENTARY) y sus cupos solo se consumen en solicitudes de ese tipo.

📄️Listar órdenes de compra de la empresa

Devuelve las órdenes de la empresa del usuario autenticado, de todos los tipos y estados, de la más reciente a la más antigua, paginadas de a 15 registros (tamaño fijo, no configurable). Se pagina con el parámetro estándar `page`. Cada orden incluye su última transacción de pago en `latest_transaction` (null si aún no se ha intentado pagar). Tipos (`order_type`): `QUOTA_PURCHASE` = compra de cupos PREPAID creada con POST /orders; `CERTIFICATE_RENEWAL` = renovación por 1 año de un certificado Viafirma emitido, creada con POST /certificate-request/{id}/issuance/renew, con `certificate_request_id`, `quantity` = 1 y `vigencia` = 1, sin ítems PREPAID (al pagarse extiende la vigencia del certificado). Una orden `CERTIFICATE_RENEWAL` en PENDING pasa a FAILED cuando el certificado deja de ser renovable, en tres momentos: cuando el cliente intenta pagarla o reintentarla (POST /orders/{uuid}/pay o /retry responden 422 con `reason`) y, sin intervención del cliente, cuando la revocación automática revoca el certificado al terminar el periodo de gracia o cuando el certificado se marca como vencido. Pagar una renovación no cancela las demás renovaciones PENDING del mismo certificado: siguen en PENDING hasta que se intente pagarlas o reintentarlas (422 con `reason` = MAX_TERM) o hasta que el certificado se marque como vencido.

📄️Crear orden de compra de certificados

Crea una orden en estado PENDING para la empresa del usuario autenticado, con precio calculado según el tipo de usuario y el rango de volumen (ver GET /pricing), y genera `quantity` ítems PREPAID con la vigencia indicada (quedan utilizables solo cuando la orden pasa a PAID). Devuelve los datos para abrir el widget de pago de WOMPI. El precio unitario ya incluye IVA; `total_amount` = precio unitario × cantidad. Responde 200 (no 201). Si falla la consulta a la pasarela después de crear la orden, la orden queda PENDING y puede recuperarse con POST /orders/{uuid}/retry. La respuesta 500 de ese caso no incluye el uuid de la orden: obténgalo con GET /orders (la orden más reciente, en PENDING) antes de llamar a POST /orders/{uuid}/retry. Repetir POST /orders crea otra orden PENDING. **Tipo de emisión:** la orden se compra para un `issuance_flow` (BIOMETRIC o DOCUMENTARY) y sus cupos solo se consumen en solicitudes de ese tipo; no se pasan de un tipo a otro. Sin `issuance_flow` se usa el de la empresa (`viafirma` → BIOMETRIC; `mail` y `dual` → DOCUMENTARY). Se cotiza con la lista de precios de ese tipo (ver GET /pricing); si el tipo de usuario no tiene lista para ese tipo de emisión, responde 422 `PRICING_TIER_NOT_FOUND`.

📄️Ver detalle de una orden

Devuelve una orden de la empresa del usuario autenticado (cualquier tipo y estado) con sus ítems PREPAID y su última transacción de pago. Nota: la respuesta viene anidada en `dataRecords.data`. Las órdenes `CERTIFICATE_RENEWAL` (renovación de un certificado, con `certificate_request_id`) no tienen ítems: `items` es un arreglo vacío. Una renovación en PENDING pasa a FAILED si el certificado deja de ser renovable: cuando el cliente intenta pagarla o reintentarla (POST /orders/{uuid}/pay o /retry responden 422 con `reason`; p. ej. MAX_TERM si otra orden de renovación del mismo certificado ya se pagó) o, sin intervención del cliente, cuando la revocación automática revoca el certificado al terminar el periodo de gracia o cuando el certificado se marca como vencido. Pagar otra renovación del mismo certificado no la cancela por sí solo: sigue en PENDING hasta uno de esos momentos.

📄️Eliminar una orden PENDING

Elimina de forma definitiva (no lógica) una orden PENDING de la empresa del usuario, junto con sus ítems y sus transacciones de pago registradas. Las órdenes PAID, FAILED o REFUNDED no pueden eliminarse. Aplica también a órdenes CERTIFICATE_RENEWAL en PENDING. Nota: la eliminación es solo local: no anula en la pasarela una transacción ya iniciada (POST /orders/{uuid}/pay o widget). Si esa transacción se aprueba después, el pago no se acredita (ni cupos ni renovación) porque la orden ya no existe. No elimine una orden con un pago en curso.

📄️Ejecutar pago de una orden

Crea directamente la transacción de pago en la pasarela para una orden PENDING de la empresa del usuario (alternativa al widget de pago). El monto enviado es el `total_amount` de la orden. La orden sigue en PENDING al responder: el estado final (PAID si la transacción es APPROVED, FAILED si es DECLINED) llega de forma asíncrona por el webhook de WOMPI. Consulte GET /orders/{uuid} para ver el resultado. Si la transacción termina en VOIDED o ERROR, la orden permanece en PENDING (no pasa a FAILED): consulte el estado de la transacción en `latest_transaction` de GET /orders/{uuid} y, si ya es final, vuelva a pagar con POST /orders/{uuid}/pay y un nuevo token de pago (use POST /orders/{uuid}/retry si necesita un token de aceptación nuevo o los datos del widget) o elimine la orden. Si la orden es `CERTIFICATE_RENEWAL`, antes de cobrar se comprueba que el certificado aún se pueda renovar: si no, no se crea ninguna transacción, las órdenes de renovación PENDING de ese certificado pasan a FAILED y se responde 422 con `reason`; si sí, se actualiza la fecha de la orden, lo que pospone hasta 48 horas la revocación automática del certificado mientras el pago se completa. Esa espera solo se respeta hasta 3 días después de terminado el periodo de gracia (fecha de vencimiento + días de gracia + 3 días); pasado ese límite, la revocación automática revoca el certificado aunque haya un pago de renovación en curso. La validación del cuerpo se hace antes que cualquier otra comprobación (empresa del usuario, existencia y estado de la orden, renovación): un cuerpo inválido responde 422 aunque la orden no exista o no esté en PENDING.

📄️Reintentar pago de una orden PENDING

Devuelve un token de aceptación y una firma de integridad nuevos para volver a abrir el widget de pago sobre una orden PENDING existente de la empresa del usuario. No crea una orden nueva ni cambia el monto ni la referencia de pago. Sin cuerpo de petición. Las órdenes FAILED no se pueden reintentar: cree una orden nueva (para una renovación, POST /certificate-request/{id}/issuance/renew). Si la orden es `CERTIFICATE_RENEWAL`, primero se comprueba que el certificado aún se pueda renovar: si no, las órdenes de renovación PENDING de ese certificado pasan a FAILED y se responde 422 con `reason`; si sí, se actualiza la fecha de la orden, lo que pospone hasta 48 horas la revocación automática del certificado mientras el pago se completa. Esa espera solo se respeta hasta 3 días después de terminado el periodo de gracia (fecha de vencimiento + días de gracia + 3 días); pasado ese límite, la revocación automática revoca el certificado aunque haya un pago de renovación en curso.