Webhooks y claves de API en PortalX
Los webhooks envían notificaciones en tiempo real a su propio sistema cuando ocurre algo en QrX, como un pago o una entrega. Las claves de API permiten que su sistema cree transacciones a través de la API de QrX. La documentación de la API está en qrx.eu/api.
Claves de API
Cada canal de venta tiene su propia clave de API: Settings > Business > Merchant Channels (Ajustes > Negocio > Canales de comercio), abra el canal, pestaña Settings, API Key (clave de API) (permiso Manage Channels). La clave se guarda de forma segura y solo se muestra completa una vez, cuando hace clic en Regenerate API Key (regenerar clave de API). Cópiela de inmediato. Al regenerarla, deja de funcionar cualquier integración que siga usando la clave anterior.
Debajo de la clave de API está el bloque Acceso a la API. Una clave empieza con Acceso completo. Active Restringir esta clave para limitar la clave a las partes de la API que usted marque, por ejemplo solo leer el stock. Consulte "Restringir una clave de API (Acceso a la API)".
Crear un webhook
Vaya a Settings > Advanced > Webhooks (Ajustes > Avanzado > Webhooks).
Introduzca un nombre y la URL de su endpoint (https).
Elija la versión de la API y, opcionalmente, un canal (o All Channels).
Haga clic en los eventos que quiere recibir. Use Customize payload (personalizar payload) para elegir los campos que se envían para un evento.
Mantenga Active (activo) activado. Mientras un webhook está en pausa, los eventos se omiten, no se ponen en cola.
Eventos
Transacción: creada, pagada, caducada, reembolsada, cancelada y cambio de estado.
Envío: creado, enviado, entregado y etiqueta creada.
Pedido: cancelado. Pago: abono procesado. Entrega: confirmada.
Eventos de devolución: solicitada, información requerida, aprobada, rechazada, etiqueta emitida, en tránsito, recibida, inspeccionada, resuelta, reembolsada, cancelada y más.
Fulfilment (QrX WMS):
picklist/created,picklist/completed,fulfilment/picked,fulfilment/packedyfulfilment/exception. Consulte "Estación de embalaje y listas de preparación".Stock (stock de almacén de QrX WMS):
stock/adjusted(el stock de un artículo cambió en un almacén) ystock/low(un artículo bajó hasta su nivel de alerta de stock bajo). Van a cada webhook activo que los haya marcado, también a un webhook para un solo canal. Consulte "Webhooks de stock y almacén".
Seguridad
Cada entrega está firmada. Verifique la cabecera X-QrX-Signature con el secreto de firma de su webhook; X-QrX-Event y X-QrX-Delivery-Id identifican el evento y la entrega. Use Rotate (rotar) para cambiar el secreto: se aplica de inmediato a todas las entregas siguientes, así que actualice primero su endpoint.
Fallos y pruebas
Failure Notifications (notificaciones de fallos): elija a qué miembros del equipo se envía un correo electrónico. Se envía una advertencia tras 6 horas de fallos continuos, y el webhook se desactiva automáticamente tras 24 horas. Corrija su endpoint y vuelva a activar el webhook en el editor.
Send Test (enviar prueba) envía un evento de ejemplo, incluso mientras el webhook está desactivado.
Delivery Logs (registros de entregas): busque por ID de transacción, ID de pedido o evento. Estados: Queued, Delivering, Delivered, Retrying, Failed y Cancelled. Abra una entrega para ver la solicitud y la respuesta, usar Redeliver (volver a entregar) o cancelarla.
El editor muestra el número de entregas correctas y fallidas de las últimas 24 horas. En la zona de peligro puede purgar el historial o eliminar el webhook.
Conectar apps (OAuth)
Algunas apps, como la app de QrX para Shopify, se conectan mediante una pantalla de consentimiento ("Connect QrX"). Usted elige un canal y hace clic en Allow. A partir de ese momento, la app puede crear transacciones de pago en la entrega y etiquetas de envío, y leer el estado de los pagos y los envíos, solo para ese canal. No puede cambiar la facturación, los usuarios ni otros canales.
Cuándo contactar con nuestro equipo de soporte
Contacte con QrX cuando las entregas fallen aunque su endpoint devuelva 2xx, cuando las firmas no se verifiquen con el secreto actual o cuando necesite un evento que no está en la lista. Incluya el nombre del webhook y un ID de entrega.