Desarrolladores

Una API transaccional de lealtad

Identifica al cliente, cotiza sus beneficios, reserva la recompensa, completa la venta y redime. El contrato es el mismo para cualquier POS o e-commerce.

POST/v1/loyalty/identifyResuelve al cliente desde el QR, el email o un ID externo.
POST/v1/loyalty/benefits/quoteDevuelve las recompensas aplicables a la canasta.
POST/v1/loyalty/rewards/{id}/reserveBloquea la recompensa mientras se cobra.
POST/v1/loyalty/transactionsRegistra la venta y acumula puntos.
POST/v1/loyalty/rewards/{id}/redeemConfirma el uso tras el pago.
POST/v1/loyalty/rewards/{id}/releaseLibera la reserva si la venta falla.

El evento central

`order.completed`

Todo sistema de origen se normaliza a este evento. Desde ahí, cada servicio reacciona por su cuenta.

POST/v1/events

{
  "type": "order.completed",
  "customer": {
    "external_id": "123",
    "email": "customer@example.com",
    "phone": "+57..."
  },
  "order": { "id": "ABC", "total": 250000, "currency": "COP" },
  "items": [
    { "product_id": "P01", "quantity": 2, "unit_price": 50000 }
  ]
}

Recompensa como instrucción de redención

{
  "reward_id": "reward_123",
  "type": "fixed_discount",
  "value": 20000,
  "currency": "COP",
  "constraints": {
    "minimum_purchase": 50000,
    "stores": ["store_1", "store_2"],
    "categories": ["combos"],
    "valid_until": "2026-10-15"
  },
  "redemption": { "method": "pos", "requires_customer_identification": true }
}

Redención segura

Nunca hay doble redención

El POS reserva antes de cobrar. Si la venta se completa, la recompensa queda redimida; si falla, vuelve a estar disponible.

Estados de una recompensa: AVAILABLE pasa a RESERVED con reserve; RESERVED pasa a REDEEMED con redeem o a RELEASED con release, que vuelve a disponible

Eventos semánticos

Suscríbete a lo que significa algo

PointsBalanceChangedRewardUnlockedTierChangedCampaignStartedRewardExpiringRewardRedeemed