Rilevamento presenze Cookpit / Timbrage

Se il Suo campeggio usa Cookpit (Timbrage) per le timbrature del personale, questo adapter trasferisce ogni 15 minuti gli eventi di timbratura nel modulo di rilevamento presenze di CampOne. Totali pronti per la busta paga, senza doppio inserimento.

Se non usa Cookpit, CampOne mette a disposizione un widget di timbratura integrato nella dashboard quotidiana — il personale clicca “Clock in” all’arrivo e “Clock out” alla partenza, e gli stessi report a valle funzionano comunque.

Cosa Le offre

• Importa gli eventi di timbratura da Cookpit ogni 15 minuti (idempotente — ripetizioni non duplicano)
• Li archivia nella tabella TimeEntry di CampOne accanto agli inserimenti manuali
• Tiene traccia delle rettifiche separatamente (ogni PATCH scrive una riga di audit TimeEntryAdjustment)
• Riepiloghi orari per utente con filtri per data
• Un widget di timbratura lato personale sulla dashboard, disponibile per qualsiasi tenant

Prerequisiti

Cookpit non pubblica un portale sviluppatori pubblico — li contatta direttamente:

• Vendite: verkauf@cookpit.ch
• Supporto: support@cookpit.ch
• Pagina prodotto: https://www.cookpit.ch/cookpit-time/

Cosa chiedere:

1. Il contratto API tecnico (al momento ipotizziamo GET /api/v1/clock-events con header X-API-Key)
2. Un tenant sandbox + chiave API per un sito pilota
3. Conferma del base URL (https://api-test.cookpit.ch è la nostra ipotesi attuale)
4. La loro posizione sul push: accettano turni in entrata da noi, oppure è solo pull?

Un template di e-mail pronto da inviare si trova in docs-internal/handoffs/integrations-outreach-emails.md.

Cosa incollerà in CampOne

Impostazioni → Integrazioni → Vendor Adapters → Cookpit:

Campo	Descrizione
Environment	Test / Production
Location ID	L’identificativo Cookpit del Suo campeggio
API key	Il token che Cookpit rilascia per tenant
User mapping	Un oggetto JSON che mappa gli ID utente Cookpit → ID utente CampOne, es. {"cookpit_42": 17, "cookpit_43": 22}

Clicchi Save, poi Test connection.

Come funziona la sincronizzazione

Ogni 15 minuti un task Celery chiede a Cookpit “ci sono nuovi eventi di timbratura dall’ultimo cursore?”. Per ogni evento trovato:

1. Cerca l’ID utente Cookpit nella user mapping per ottenere l’utente CampOne.
2. Se l’utente non è mappato, salta e logga (così Lei può mapparlo e rilanciare).
3. Crea o aggiorna una TimeEntry chiavata su (tenant, source='cookpit', external_ref). Le re-importazioni sono idempotenti.
4. Aggiorna il cursore, così la sincronizzazione successiva preleva solo i nuovi eventi.

Il log di integrazione mostra quanti eventi sono stati importati per ciascun pull.

Widget di timbratura per i siti senza Cookpit

Il widget della dashboard crea righe TimeEntry con source='manual'. Stessa struttura dati, stessi report a valle. Se un sito adotta Cookpit in seguito, basta cambiare l’interruttore su questa scheda e gli inserimenti manuali precedenti restano intatti.

Rettifiche di timbratura

Gli amministratori del tenant possono modificare qualsiasi TimeEntry (es. correggere una timbratura mancata in uscita). Ogni modifica scrive una riga TimeEntryAdjustment con lo snapshot prima / dopo e l’utente che ha fatto la modifica — audit trail completo per le contestazioni di busta paga.

Contatti di supporto

• Vendite / partnership: verkauf@cookpit.ch
• Supporto tecnico: support@cookpit.ch

Limiti

• Il push dei turni verso Cookpit è documentato come punto di roadmap — l’adapter solleva NotImplementedError finché Cookpit non conferma il contratto in entrata.
• Il contratto API Cookpit è attualmente dedotto dai pattern comuni del rilevamento presenze; si aspetti un piccolo aggiustamento a services/client.py quando il fornitore confermerà la forma esatta della risposta.
• I test registrati con VCR contro la sandbox reale di Cookpit saranno aggiunti all’arrivo delle credenziali.