Guía rápida para desarrolladores: API pública y webhooks de QrX

La API pública de QrX permite a comercios y desarrolladores crear y gestionar transacciones de Payment on Delivery, etiquetas de envío, productos, devoluciones y webhooks. Es una API REST con JSON, autenticación Bearer y webhooks firmados. La referencia completa, generada en tiempo real a partir de la API, está en qrx.eu/api.

Lo básico

URL base: https://api.qr-x.net
Formato: solicitudes y respuestas en JSON. Los errores usan application/problem+json con un código legible por máquina y un mensaje legible.
Especificación: OpenAPI, con ejemplos de código en cURL, Node.js, C#, PHP y Python, una consola "try it" (pruébelo) y una colección de Postman lista para usar.
Acceso: necesita una cuenta de comercio QrX aprobada. Regístrese en portal.qr-x.app o solicite acceso a través de qrx.eu/api.

Paso 1: Obtenga una clave de API y un token de acceso

En PortalX, abra Settings, Merchant channels (Ajustes, Canales del comercio) y cree una clave de API para el canal de venta que desea conectar. Cada canal tiene su propia clave.
Intercambie la clave por un token de acceso: POST /api/v1/auth/token con la cabecera QrX-MerchantChannel-API-Key: YOUR_KEY. La respuesta contiene accessToken y expiresIn (3600 segundos).
Envíe Authorization: Bearer <accessToken> en todas las demás llamadas. Solicite un nuevo token cuando caduque.

Guarde la clave de API en su servidor. Nunca la ponga en un navegador, en una app móvil ni en un repositorio público.

Paso 2: Cree una transacción

POST /api/v1/transactions crea una transacción de Payment on Delivery. El cuerpo contiene el importe, la moneda, la configuración regional, orderDetails (id del pedido, nombre del cliente, correo electrónico, teléfono, dirección y líneas del pedido) y, opcionalmente, un bloque parcel para elegir un método de envío y un remitente y crear la etiqueta del transportista en la misma llamada. Use los endpoints de referencia (/api/v1/reference/carriers, countries, locales, shipping-methods, senders) para obtener valores válidos.

La respuesta devuelve el transactionId, el valor del código QR (un enlace en go.qr-x.app) y su imagen y, si solicitó una etiqueta, las etiquetas de envío con el número de seguimiento. Para UPS Payment on Delivery, el conjunto de etiquetas incluye la etiqueta de pago de QrX.

Importante: HTTP 201 significa que QrX aceptó la transacción. No es una prueba de pago. La sesión de pago con el PSP puede crearse en segundo plano, y el cliente paga más tarde en la puerta.

Paso 3: Siga el resultado

GET /api/v1/transactions/{id}/status indica si la transacción está pagada o abierta.
POST /api/v1/transactions/{id}/ship guarda los datos de seguimiento de su propio sistema.
POST /api/v1/transactions/{id}/cancel cancela una transacción abierta que cumpla los requisitos, indicando un motivo. Una transacción cancelada ya no se puede pagar, etiquetar ni completar.

Paso 4: Suscríbase a webhooks

Los webhooks son la forma fiable de mantener su sistema sincronizado, porque el procesamiento del pago puede completarse o fallar después de que su solicitud haya respondido.

Cree un webhook con POST /api/v1/webhooks: un nombre, su targetUrl HTTPS, los eventTypes que desee (por ejemplo transaction/created y transaction/paid) y una versión de la API.
Obtenga la lista actual de tipos de eventos y versiones de la API con GET /api/v1/webhooks/event-types.
transaction/edited se envía cuando cambian los productos de un pedido no pagado de pago en la puerta (se quita una línea, cambia una cantidad o se añade una línea), también cuando el importe no cambia. Contiene eventId (úselo para eliminar duplicados), transactionId, orderId, shopOrderId, editId, oldAmount, newAmount, currency, paymentLinkChanged y las removedLines, changedLines y addedLines con SKU, nombre, cantidad antigua y nueva, y totales.
Cada entrega incluye las cabeceras X-QrX-Event, X-QrX-Delivery-Id y X-QrX-Signature. La firma tiene la forma sha256=<hex>: un HMAC-SHA256 del cuerpo sin procesar con su secreto de firma del webhook. Verifíquela antes de confiar en el evento.
Responda rápidamente con un estado 2xx y procese el evento después. Gestione los duplicados de forma segura, porque pueden producirse reintentos y reenvíos.
Use los endpoints para enviar un webhook de prueba, listar entregas, reenviar o cancelar una entrega, reactivar un webhook desactivado y rotar el secreto de firma.

Stock de almacén

Con el stock de almacén de QrX puede leer niveles de stock, artículos de stock y ubicaciones con GET /api/v1/stock/levels, /items y /locations, y registrar una corrección con POST /api/v1/stock/adjust. Los eventos de webhook stock/adjusted y stock/low le avisan cuando el stock cambia o baja. Consulte "API de stock y almacén" y "Webhooks de stock y almacén".

Modo de prueba

Establezca testMode: true al crear una transacción para probar el flujo completo. Las transacciones de prueba usan la configuración sandbox o de prueba cuando está disponible, nunca crean un pago ni un abono real y no deben tratarse como pedidos reales. Las etiquetas de las cuentas de prueba se crean en el sandbox del transportista.

Idempotencia

Los comandos sobre devoluciones (como aprobar, rechazar, registrar una resolución o publicar un mensaje) requieren una cabecera Idempotency-Key de 200 caracteres como máximo. Reutilice la misma clave al reintentar el mismo comando para recibir su resultado almacenado; use una clave nueva para un comando nuevo. Para las transacciones, use su propio id de pedido y los webhooks para evitar crear el mismo pedido dos veces. POST /api/v1/stock/adjust también necesita una cabecera Idempotency-Key.

Límites de uso

Los límites se aplican por clave de API o canal del comercio, por ejemplo 60 solicitudes de token por minuto y 300 comandos de transacción por minuto. Una respuesta 429 incluye Retry-After y RateLimit-Reason. Espere al menos Retry-After segundos antes de reintentar y reutilice su token de acceso.

¿Desarrolla para otros comercios?

Si desarrolla una app, un WMS o una plataforma que usan muchos comercios, use QrX Connect para que los comercios puedan vincular su canal QrX sin pegar una clave de API. Consulte "QrX Connect: conectar su plataforma con OAuth".

Cuándo contactar con nuestro equipo de soporte

Contacte con el soporte de QrX en [email protected] para acceso a la API, incidencias en producción, credenciales filtradas o problemas de firma que no pueda explicar. Incluya el entorno, el canal, el id de la transacción, el id de la entrega del webhook y una solicitud depurada, nunca la clave, el token ni el secreto. Consulte también "Solución de problemas de API y webhooks".