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.

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
  }
}

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