Arquitectura de un vistazo

Arquitectura recomendada

POS / ecommerce / app / web
            ↓ HTTPS
Retailer backend / BFF / integration layer
            ↓ X-API-Key
     Qualth Integration API
            ↓
 customer → purchase → state

El backend del retailer es el límite de integración

La X-API-Key vive en una capa server-side controlada por el retailer. Los canales llaman a ese backend; no llaman directamente a Qualth con la credencial de integración.

Responsabilidades del retailer

• Mantener POS, ecommerce, ERP y experiencias de cliente como sistemas propios.
• Completar la venta en su sistema transaccional y conservar sus identificadores comerciales.
• Resolver la identidad en sus canales y conservar el customer.id de Qualth cuando corresponda.
• Guardar la Idempotency-Key y el payload lógico de una compra hasta resolver su resultado.
• Correlacionar errores y reconciliar resultados ambiguos antes de generar una nueva operación.

Responsabilidades de Qualth en este recorrido

• Autenticar la Integration API y aplicar tenant y scopes según la operación.
• Buscar o crear el customer dentro del alcance del contrato.
• Procesar la purchase y devolver el resultado expuesto por la API.
• Permitir la lectura del estado resultante del customer.
• Aplicar las semánticas de error, correlación e idempotencia documentadas en la Reference.

Sistema de registro de la venta

En esta arquitectura, el retailer sigue siendo el sistema de registro de la transacción comercial. Qualth procesa el evento de compra para loyalty; no reemplaza órdenes, pricing, inventario, ERP ni checkout.