Solución de problemas de la API y los webhooks

La mayoría de los problemas con la API y los webhooks de QrX se deben a la autenticación, los identificadores, los límites de solicitudes o la forma en que su receptor gestiona los webhooks. Revise primero los puntos siguientes. La referencia completa de la API está en qrx.eu/api.

Errores de autenticación (401 o 403)

Los endpoints protegidos necesitan Authorization: Bearer <token>, no la clave de API. Utilice la clave de API (cabecera QrX-MerchantChannel-API-Key) solo para llamar a POST /api/v1/auth/token.
Los tokens de acceso son válidos durante una hora. Solicite un nuevo token cuando caduque.
Cada clave de API pertenece a un canal del comercio. Un token no puede leer ni modificar datos de otro canal.
Compruebe que la clave no se haya eliminado ni sustituido en PortalX en Settings, Merchant channels.
403 con el código STOCK_SCOPE_MISSING (o el código correspondiente de devoluciones o de entradas): la clave de API está restringida y la parte a la que llama no está marcada. Márquela en el bloque Acceso a la API del canal de venta y espere 30 segundos. Consulte "Restringir una clave de API (Acceso a la API)".
403 con el código ACCESS_DENIED en un endpoint de stock: el stock de almacén de QrX no está activado para la cuenta.

Demasiadas solicitudes (429)

Los límites de solicitudes se aplican por clave de API o canal del comercio. Por ejemplo, el endpoint de token permite 60 solicitudes por minuto y la creación de transacciones permite 300 solicitudes por minuto por canal. Una respuesta 429 incluye las cabeceras Retry-After y RateLimit-Reason y el código RATE_LIMIT_EXCEEDED. Espere al menos el número de segundos indicado en Retry-After antes de reintentar, y reutilice su token de acceso en lugar de solicitar uno nuevo para cada llamada.

Transacción creada pero aún no pagada

Un HTTP 201 al crear significa que QrX ha aceptado la transacción. No es una prueba de pago. La sesión de pago con el PSP puede crearse en segundo plano, y el pago se realiza más tarde en la puerta. Siga la transacción con webhooks o con el endpoint de estado, y solo prepare o entregue los productos cuando la transacción esté pagada. Si se solicita la creación de la etiqueta del transportista y esta falla, la propia solicitud de creación devuelve un error.

Otros problemas habituales

Importe, moneda, país, configuración regional o método de envío no válidos. Utilice los endpoints de referencia para obtener valores válidos.
Falta el correo electrónico o el teléfono del cliente, que son necesarios para los enlaces de pago, el envío del PIN y el soporte.
Confusión entre prueba y producción. Las transacciones creadas con testMode: true nunca generan pagos ni liquidaciones reales y no deben tratarse como pedidos reales.
Reintentar un comando de devoluciones con una nueva Idempotency-Key. Reutilice la misma clave al reintentar el mismo comando; utilice una clave nueva solo para un comando nuevo.
Correcciones de stock: POST /api/v1/stock/adjust sin cabecera Idempotency-Key responde 400 IDEMPOTENCY_KEY_REQUIRED; la misma clave con otro cuerpo responde 409 DUPLICATE_IDEMPOTENCY_KEY; 409 STOCK_CONFLICT significa que no hay stock suficiente, que el stock está asignado o que un SKU coincide con varios artículos. Consulte "API de stock y almacén".

Comprobaciones de los webhooks

Accesible y rápido: su endpoint debe ser accesible públicamente por HTTPS y devolver rápidamente un estado 2xx. Realice el trabajo lento después de responder.
Firma: verifique la cabecera X-QrX-Signature. Tiene el formato sha256=<hex>, un HMAC-SHA256 del cuerpo sin procesar de la solicitud calculado con su secreto de firma del webhook. Calcúlelo sobre los bytes exactos que recibió, antes de analizar el JSON.
Secreto rotado: después de rotar el secreto de firma, actualice su receptor o las comprobaciones de firma fallarán.
Duplicados: los reintentos y los reenvíos pueden enviar el mismo evento más de una vez. Utilice la cabecera X-QrX-Delivery-Id y los datos del evento para procesar cada evento una sola vez.
Tipos de evento: la cabecera X-QrX-Event le indica el evento. Suscríbase solo a los eventos que gestiona.
Eventos de stock: detecte duplicados con eventId y, para stock/adjusted, ignore un evento cuya sequence sea menor que la última que guardó para ese artículo y almacén. Consulte "Webhooks de stock y almacén".

Estado de los webhooks y registros de entrega

Cada suscripción de webhook en PortalX muestra un estado de salud. Si un endpoint falla de forma continua, QrX envía correos de advertencia a los destinatarios configurados y desactiva automáticamente la suscripción tras aproximadamente 24 horas de fallos; puede volver a activarse una vez corregido el endpoint. Utilice el registro de entregas (en PortalX o a través de la API) para revisar cada intento, incluidos la solicitud, la respuesta y los reintentos, y para volver a enviar una entrega fallida. También puede enviar un webhook de prueba para comprobar su receptor.

Qué enviar al soporte

Envíe el entorno (prueba o producción), el canal del comercio, la referencia del pedido, el id de transacción de QrX, la marca de tiempo, el endpoint, el estado de la respuesta, el id de entrega del webhook y un cuerpo de solicitud o respuesta depurado. Elimine las claves de API, los tokens de acceso, las firmas, los secretos, las contraseñas y los datos personales que no sean necesarios.

Cuándo contactar con nuestro equipo de soporte

Contacte directamente con el soporte de QrX para problemas de la API relacionados con credenciales filtradas, seguridad, incidencias en producción, incoherencias en los pagos, fallos de firma de webhooks que no pueda explicar o errores de integración repetidos. Estos casos siempre los atiende una persona. Consulte status.qr-x.app para conocer el estado actual de la plataforma.