Endpoints

Todos los endpoints de negocio requieren autenticacion y estan bajo el prefijo:

/integrations/stores/{store_id}/...

Donde {store_id} es el ID de la tienda a la que tu integracion tiene acceso. Si intentas acceder a una tienda no autorizada, recibiras un error 403.

---

Consulta de Saldo y Beneficios

Consulta los datos de un cliente, su tipo de cliente, puntos acumulados y el beneficio vigente para el dia de hoy.

GET /integrations/stores/{store_id}/clients/{dni}
Authorization: Bearer {access_token}

Parametros de ruta:

Parametro	Tipo	Descripcion
store_id	int	ID de la tienda
dni	string	DNI/Identificacion del cliente

Response 200:

{
  "client": {
    "subscription_id": 1234,
    "identification": "12345678",
    "email": "cliente@email.com",
    "card_number": "0001-0001-1234",
    "name": "Juan",
    "last_name": "Perez",
    "points": 150.5,
    "cash": 150.5
  },
  "client_type": {
    "id": 1,
    "name": "Gold"
  },
  "today_benefit": {
    "points_percentage": 10,
    "discount_percentage": 5
  }
}

Campo	Descripcion
client.points	Puntos acumulados del cliente
client.cash	Saldo en efectivo acumulado
client_type.name	Categoria del cliente (ej: Regular, Gold, VIP)
today_benefit.points_percentage	Porcentaje de puntos que gana hoy por compra
today_benefit.discount_percentage	Porcentaje de descuento que tiene hoy

---

Registrar Transaccion

Registra una compra del cliente. El sistema automaticamente:

• Calcula los puntos a sumar segun el tipo de cliente y dia de la semana
• Aplica descuentos configurados
• Procesa recompensas (si aplica)
• Otorga estampas (si aplica)
• Envia emails de transaccion, encuestas, sorteos (si estan configurados)
• Evalua si el cliente debe subir de categoria

POST /integrations/stores/{store_id}/transactions
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "identification": "12345678",
  "amount": 5000.00,
  "ticket_id": "FAC-001-00123",
  "branch_id": 5,
  "idempotency_key": "unique-key-123"
}

Campos del body:

Campo	Tipo	Requerido	Descripcion
identification	string	Si	DNI del cliente
amount	float	Si	Monto de la compra (debe ser > 0)
ticket_id	string	No	Numero de factura/ticket
branch_id	int	No	ID de la sucursal (para beneficios por sucursal)
idempotency_key	string	No	Clave unica para evitar transacciones duplicadas

Response 201:

{
  "transaction_id": 5678,
  "points_added": 50.5,
  "cash_added": 0,
  "discount_pct": 5,
  "final_amount": 4750.00
}

Campo	Descripcion
transaction_id	ID de la transaccion creada
points_added	Puntos otorgados al cliente
cash_added	Cash otorgado (por recompensas)
discount_pct	Porcentaje de descuento aplicado
final_amount	Monto final despues del descuento

Idempotencia

Usa idempotency_key para evitar transacciones duplicadas. Si mandas el mismo key dos veces, la segunda llamada devuelve la transaccion original sin crear una nueva.

---

Canje de Puntos

Permite al cliente canjear puntos acumulados.

POST /integrations/stores/{store_id}/swap
Authorization: Bearer {access_token}
Content-Type: application/json

{
  "identification": "12345678",
  "amount": 50.0
}

Campos del body:

Campo	Tipo	Requerido	Descripcion
identification	string	Si	DNI del cliente
amount	float	Si	Cantidad de puntos a canjear (debe ser > 0)

Response 200:

{
  "transaction_id": 5679,
  "points_used": 50.0,
  "new_points": 100.5,
  "new_cash": 100.5
}

Campo	Descripcion
transaction_id	ID de la transaccion de canje
points_used	Puntos canjeados
new_points	Puntos restantes del cliente
new_cash	Cash restante del cliente