Entrar
.md

Checkout Genérico

Si tu tienda no es VTEX ni Shopify (o si quieres control fino), esta es la integración a nivel de API — la base sobre la que se construye todo lo demás. Los conectores listos para usar VTEX IO y Shopify hablan con los mismos endpoints por debajo.

Conecta Guper a tu checkout en tres llamadas. Cada paso tiene una responsabilidad específica:

  1. Acumulación — calcula el cashback y los descuentos del pedido
  2. Confirmar — aplica los beneficios cuando el pago es aprobado
  3. Actualizar — modifica el pedido pendiente antes de confirmar (cambio de cantidad, cancelación, etc.)

Un cuarto paso opcional permite exigir PIN para canjes de alto valor.

Paso 1 — Acumulación por pedido

Envía los ítems del carrito y el identificador del cliente. Guper devuelve un confirmToken, el cashback que se acumularía y los canjes disponibles para el cliente.

POST /api/loyalty/rewardByOrder

Usa la variante Público (omite x-guper-authorization) para una vista previa sin datos del cliente, o Privado cuando necesites la vista completa del cliente + token. Consulta Acumulación por pedido para el schema completo.

Paso 2 — Confirmar transacción

Una vez que el procesador de pago retorne éxito, devuelve el confirmToken a Guper. Los beneficios se vuelven reales en la cuenta del cliente y la transacción queda registrada.

POST /api/loyalty/confirmOrder/{confirmToken}

A partir de ese momento el cashback está en el saldo del cliente y el pedido aparece en el Feed de datos para los sistemas downstream.

Paso 3 — Actualizar transacción (opcional)

Si el pedido cambia entre Acumulación y Confirmar — ítems agregados/eliminados, dirección modificada, cancelación parcial — llama a Update antes del Confirm para recalcular el cashback.

POST /api/loyalty/updateTransaction/{confirmToken}

El mismo confirmToken se mantiene. Guper recalcula y el siguiente Confirm usa el nuevo monto.

Opcional — Validación por PIN

Para canjes de alto valor puedes exigir un PIN al cliente. Dos endpoints:

GET  /api/register/customer/{person}/pin            # genera / envía PIN al cliente
POST /api/register/customer/{person}/pin/validate   # valida el PIN ingresado en el POS

Valida el PIN entre Acumulación y Confirm — solo continúa con el Confirm si la validación pasa.

Flujo completo

                 ┌──────────────────────────────────────────────┐
                 │                                              │
   ┌──────────┐  │   ┌─────────┐                                │
   │Acumulac. │ ─→│   │ Update  │ ─→ (PIN, opcional) ──────→    │
   └──────────┘  │   └─────────┘                                │
                 │     ↑                                        │
                 │     │                                       ↓
                 │     │                              ┌──────────────┐
                 │     └─────────────────────────────│   Confirm    │
                 │                                    └──────────────┘
                 └──────────────────────────────────────────────┘
                       (loops de recálculo hasta que el pago se apruebe)

Cancelación

Si necesitas deshacer un pedido confirmado — total o parcial:

  • Total — POST /api/loyalty/cancelOrderByTransaction/{TID} devuelve el cashback acumulado y revierte cualquier canje.
  • Parcial — POST /api/loyalty/cancelPartial/{TID} para cancelar ítems específicos. Consulta Cancelación parcial para las reglas por ítem.

Autenticación

Todos los endpoints de Confirm/Update/Cancel requieren un token x-guper-authorization válido. Solo la variante Pública de Acumulación no requiere autenticación. Consulta Autenticación.

Ver también