Bridge POS shop esterno

Se lo shop del Suo campeggio gira su una cassa propria — Lightspeed, Zettle, uno script Python custom, qualunque sistema — questo bridge permette alla cassa di inviare ogni transazione a CampOne, così che i totali della giornata (e la scrittura SAP quotidiana, e i report) catturino tutto il fatturato, non solo quello della reception.

A differenza delle altre integrazioni, questa è inbound: il POS esterno chiama CampOne, non viceversa. Qui non c’è un account fornitore da configurare — invece, genera una chiave API CampOne con i giusti scope e la incolla nel sistema esterno.

Cosa Le offre

• Un’API pubblica su /api/v1/public/pos/transactions/ che accetta transazioni esterne
• Idempotente sull’external_ref — riprovare dopo un’intermittenza di rete non crea mai duplicati
• Autenticazione standard con chiave API CampOne, con due nuovi scope: pos:read e pos:write
• Un endpoint di lettura per la riconciliazione di fine giornata
• Un endpoint prodotti per permettere al POS esterno di sincronizzare il catalogo
• Log dell’attività in entrata sulla scheda delle impostazioni

Prerequisiti

Nessuno lato fornitore — non Le serve un contratto Lightspeed o un account Zettle per attivare l’integrazione. Configura CampOne, poi punti il sistema esterno verso di esso.

Le serve:

• Un sistema POS esterno in grado di fare richieste HTTP con un Bearer token
• Sapere come inserire URL API / token in quel sistema

Come si configura

Impostazioni → Integrazioni → API Keys (la superficie API-key esistente, accanto alla scheda Vendor Adapters):

1. Clicchi Create new key.
2. Le dia un nome (es. Lightspeed shop till).
3. Spunti gli scope pos:read e pos:write.
4. Clicchi Generate. CampOne mostra il token in chiaro una sola volta — lo copi adesso e lo salvi nel sistema esterno.
5. Il token è hashato at rest; se lo perde, revochi e ne generi uno nuovo.

Poi, nel POS esterno, configuri:

• API URL: https://your-tenant.campone.ch/api/v1/public/pos/transactions/
• Auth: Authorization: Bearer <il-token-appena-copiato>

Cosa invia il POS esterno

POST /api/v1/public/pos/transactions/
Authorization: Bearer ck_…
Content-Type: application/json

{
  "external_ref": "lightspeed-2026-04-29-T-1234",
  "payment_method": "CASH",
  "total_amount": "12.50",
  "items": [
    { "description": "Croissant", "quantity": 2, "unit_price": "3.50", "line_total": "7.00" },
    { "description": "Coffee",   "quantity": 1, "unit_price": "5.50", "line_total": "5.50" }
  ],
  "occurred_at": "2026-04-29T08:14:32Z"
}

L’external_ref è la chiave di idempotenza — deve essere univoca per transazione nel Suo sistema. CampOne impone l’unicità per tenant, quindi rilanciare la stessa transazione restituisce un 200 con il record esistente (invece di un 409 o di un duplicato).

Riconciliazione

A fine giornata, il sistema esterno può fare GET /api/v1/public/pos/transactions/<external_ref>/ per confermare che CampOne ha la transazione. Oppure GET /api/v1/public/pos/products/ per aggiornare il proprio catalogo.

In CampOne, le transazioni da fonti esterne compaiono in /kasse/transaktionen come ogni altra transazione POS, con Source: External POS per poterle filtrare.

Sicurezza

• Le chiavi API sono hashate at rest con il password hasher di Django (Argon2 / bcrypt).
• Ogni chiamata API è loggata: metodo, path, status code, latenza, prefisso della chiave.
• Le chiavi possono essere revocate immediatamente. Le chiavi revocate restituiscono 401 dalla chiamata successiva in poi.
• Gli scope sono applicati per endpoint — una chiave pos:read-only non può registrare transazioni, anche se gliele si chiede.

Limiti

• Le integrazioni live contro specifici fornitori POS esterni (Lightspeed, Zettle, Sumup) non sono ancora certificate — il contratto HTTP standard sopra è ciò a cui devono adattarsi. Roadmap: adapter testati per fornitore.
• I rimborsi registrati dal POS esterno appaiono in CampOne come transazioni separate; CampOne non collega automaticamente un rimborso alla sua vendita originale tra sistemi.