Integración con POS

La integración con POS permite que tu sistema de punto de venta registre transacciones directamente vía una API REST. Cada vez que un cliente paga, tu POS llama al endpoint de Xtarly y el cliente recibe sus puntos o sellos al instante — sin necesidad de escanear manualmente.

Obtener tu API key

1. Abre el dashboard de tu organización y ve a Configuración → General.
2. Desplázate hasta la sección Integración con POS.
3. Haz clic en Generar API key. La clave se muestra una sola vez — cópiala de inmediato y guárdala de forma segura (por ejemplo, en las variables de entorno de tu POS).
4. Si la clave se ve comprometida, haz clic en Rotar para invalidar la clave anterior y generar una nueva. Si ya tienes una clave viva, puedes rotarla aunque cambies de plan: nunca te quedas sin forma de reemplazar una credencial filtrada.

URL base

Todos los endpoints POS se sirven desde tu dominio de Xtarly:

https://www.xtarly.com/api/integrations/pos

Autenticación

Incluye tu API key en cada solicitud mediante el header X-API-Key:

X-API-Key: xtarly_pos_<tu_clave>

Las solicitudes sin una clave válida devuelven 401 Unauthorized.

Endpoints

Registrar una transacción

POST /api/integrations/pos/transaction

Llama a este endpoint cuando un cliente completa una compra. Xtarly calcula los puntos o sellos ganados según tu programa de recompensas activo y los acredita al cliente.

Cuerpo de la solicitud

Proporciona customerId o customerEmail — al menos uno es obligatorio.

Ejemplo de solicitud

curl -X POST https://www.xtarly.com/api/integrations/pos/transaction \
  -H "Content-Type: application/json" \
  -H "X-API-Key: xtarly_pos_<tu_clave>" \
  -d '{
    "amount": 35000,
    "customerEmail": "cliente@ejemplo.com",
    "metadata": { "ticket": "T-00412" }
  }'

Respuesta exitosa 200 OK

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "earnedPoints": 35,
    "earnedStamps": 0,
    "customerPoints": 210,
    "customerStamps": 0
  }
}

Consultar un cliente

GET /api/integrations/pos/customer/:id

Devuelve el saldo y nivel actual de un cliente. Útil para mostrar el estado de fidelización en el punto de venta antes o después de una transacción.

Ejemplo de solicitud

curl https://www.xtarly.com/api/integrations/pos/customer/cus_abc123 \
  -H "X-API-Key: xtarly_pos_<tu_clave>"

Respuesta exitosa 200 OK

{
  "success": true,
  "data": {
    "id": "cus_abc123",
    "name": "María García",
    "email": "cliente@ejemplo.com",
    "points": 210,
    "stamps": 0,
    "tier": null
  }
}

Endpoints para el punto de venta

La misma API key da acceso a los endpoints que usa un punto de venta conectado: identificar al cliente en la caja, ver qué puede aplicar hoy y canjear cupones o premios en el momento del cobro.

Los cuatro endpoints de búsqueda de cliente devuelven la misma forma: id, name, email, phone, points, stamps y tier (el nombre del nivel, o null).

Acreditar una venta desde el POS

POST /api/integrations/pos/accrue

La respuesta trae status: ACCRUED cuando se acreditó (con pointsAccrued y stampsAccrued), SKIPPED si esa venta ya se había procesado o no hay programa activo, y CUSTOMER_NOT_FOUND si ningún cliente tiene ese teléfono.

Qué puede aplicar el cliente hoy

GET /api/integrations/pos/customer/benefits?customerId=cus_abc123

Devuelve, en una sola llamada, el tipo de programa, el cliente, sus cupones disponibles y todos los premios con el veredicto ya calculado: attainable dice si lo puede canjear ahora, y si no, blockedReason y blockedMessage explican por qué (le faltan puntos, no alcanza el nivel, ya lo usó este ciclo…).

Cada premio incluye además un objeto benefit con la semántica ejecutable del descuento — el tipo, el valor y los productos del menú a los que aplica — para que el POS lo aplique solo en lugar de dejarle la cuenta al cajero.

Canjear un cupón o un premio

POST /api/integrations/pos/coupon/redeem
POST /api/integrations/pos/reward/redeem

Para un cupón manda couponId, saleId, amountCentavos y, opcionalmente, customerId y branchName. Un cupón marcado como de mostrador se puede canjear sin customerId.

Para un premio manda rewardId, customerId, saleId y, opcionalmente, amountCentavos y branchName.

Ambos responden status: "REDEEMED" con el redemptionId, y DUPLICATE si esa misma venta ya había canjeado. El canje de premio devuelve además pointsSpent, stampsSpent y el saldo del cliente después del canje.

Cálculo de puntos

Los puntos o sellos acreditados por transacción dependen del tipo de programa activo:

Configuras currencyUnit y pointsPerCurrency en Configuración → Programa.

Códigos de error