Endpoints

Store y Sucursales

GET /api/v1/store

Devuelve los datos del comercio asociado al API Client.

Scope requerido: ninguno

Response 200:

{
  "id": 17,
  "name": "Mi Comercio",
  "logo_url": "https://...",
  "country": "AR",
  "status": "ACTIVE"
}

---

GET /api/v1/branches

Lista las sucursales del comercio.

Scope requerido: ninguno

Response 200:

[
  {
    "id": 18,
    "name": "Sucursal Centro",
    "address": "Av. Corrientes 1234",
    "phone": "11-1234-5678",
    "latitude": -34.6037,
    "longitude": -58.3816,
    "isOpen": 1
  }
]

---

Clientes

GET /api/v1/clients

Lista todos los clientes del comercio.

Scope requerido: clients:read

Response 200:

[
  {
    "id": 100,
    "identification": "33456789",
    "email": "juan@example.com",
    "points": 1500.00,
    "cash": 1500.00,
    "client_type_id": 1
  }
]

---

GET /api/v1/clients/{lookup}

Busca un cliente por DNI, email o numero de tarjeta.

Scope requerido: clients:read

Parametros de ruta:

Parametro	Descripcion
lookup	DNI, email o numero de tarjeta del cliente

Response 200:

{
  "id": 100,
  "store_id": 17,
  "user_id": 50,
  "identification": "33456789",
  "email": "juan@example.com",
  "points": 1500.00,
  "cash": 1500.00,
  "client_type_id": 1,
  "card_number": "FID-001234"
}

Response 404:

{ "error": "Cliente no encontrado" }

---

POST /api/v1/clients

Registra un nuevo cliente en el comercio.

Scope requerido: clients:write

Request:

{
  "name": "Juan",
  "last_name": "Perez",
  "email": "juan@example.com",
  "identification": "33456789",
  "phone": "1155667788"
}

Response 201:

{
  "id": 101,
  "store_id": 17,
  "identification": "33456789",
  "email": "juan@example.com",
  "points": 0,
  "cash": 0,
  "client_type_id": 1
}

Response 409:

{ "error": "Ya existe un cliente con esa identificacion" }

Tracking

El campo created_by_api_client se registra automaticamente con el client_id del integrador.

---

GET /api/v1/clients/{identification}/benefits

Consulta los puntos, cash y nivel de lealtad disponibles para un cliente.

Scope requerido: clients:read

Response 200:

{
  "client_id": 100,
  "identification": "33456789",
  "email": "juan@example.com",
  "points": 1500.00,
  "cash": 1500.00,
  "client_type_id": 1,
  "client_type": "Gold"
}

---

Transacciones

POST /api/v1/transactions

Registra una compra y suma puntos automaticamente segun las reglas de fidelizacion del comercio.

Scope requerido: transactions:write

Request:

{
  "identification": "33456789",
  "amount": 5000.00,
  "branch_id": 18,
  "ticket_id": "TK-001",
  "idempotency_key": "venta-2026-03-16-001"
}

Identificar al cliente con uno de: identification, email, card_number.

Response 201:

{
  "transaction_id": 5001,
  "points_added": 500.00,
  "cash_added": 0,
  "discount_pct": 0,
  "final_amount": 5000.00
}

Response 404:

{ "error": "Cliente no encontrado" }

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.

Tracking

El campo created_by_api_client se registra automaticamente.

---

GET /api/v1/clients/{lookup}/transactions

Historial de transacciones de un cliente.

Scope requerido: transactions:read

Response 200:

[
  {
    "id": 5001,
    "date": "2026-03-16 14:30:00",
    "reason": "Venta",
    "amount": 5000.00,
    "points": 500.00,
    "type": "PURCHASE",
    "status": "created"
  }
]

---

Canjes (Swap)

POST /api/v1/swap

Canjea puntos, cash o stamps del cliente.

Scope requerido: swap:write

Request:

{
  "identification": "33456789",
  "type": "P",
  "amount": 500,
  "branch_id": 18,
  "idempotency_key": "canje-2026-03-16-001"
}

Campo	Tipo	Descripcion
identification	string	DNI del cliente
card_number	string	Alternativa al DNI
type	string	"P" = puntos, "I" = cash, "S" = stamps
amount	number	Cantidad a canjear
branch_id	int	ID de la sucursal (opcional)
idempotency_key	string	Clave de idempotencia

Response 200:

{
  "id": 5002,
  "points": -500.00,
  "type": "SWAP",
  "status": "created"
}

---

Catalogo

GET /api/v1/catalog

Devuelve el catalogo completo de productos agrupado por categorias.

Scope requerido: catalog:read

Query params:

Parametro	Descripcion
branch_id	ID de la sucursal (opcional). Si la branch tiene catalogo propio se usa; si no, se usa el del store.

Response 200:

[
  {
    "id": 5,
    "name": "Bebidas",
    "image_path": "https://...",
    "store_id": 17,
    "products": [
      {
        "id": 101,
        "name": "Coca Cola 500ml",
        "price": 1500.00,
        "available": 1,
        "featured": 0
      }
    ]
  }
]

---

Giftcards

GET /api/v1/giftcards/{lookup}

Consulta el saldo y datos de una giftcard.

Scope requerido: giftcards:read

Response 200:

{
  "id": 10,
  "card_number": "GC-001234",
  "balance": 5000.00,
  "status": "ACTIVE"
}

---

POST /api/v1/giftcards/charge

Carga saldo a una giftcard.

Scope requerido: giftcards:write

Request:

{
  "card_number": "GC-001234",
  "amount": 2000.00
}

---

POST /api/v1/giftcards/discharge

Descuenta saldo de una giftcard.

Scope requerido: giftcards:write

Request:

{
  "card_number": "GC-001234",
  "amount": 500.00
}

---

Tipos de Cliente

GET /api/v1/client-types

Lista los niveles de lealtad configurados en el comercio.

Scope requerido: clients:read

Response 200:

[
  {
    "id": 1,
    "name": "Standard",
    "points1": 10,
    "discount1": 0
  },
  {
    "id": 2,
    "name": "Gold",
    "points1": 15,
    "discount1": 5
  }
]