Documentazione API

Shifton Attività permette di automatizzare il lavoro con la piattaforma e di collegarla a servizi esterni tramite un’API aperta. Attraverso l’API sono disponibili tutte le entità principali — attività, clienti, dipendenti, elenchi di controllo, inventario, zone di servizio, documenti Documenti finanziari e report — perciò Shifton può essere collegato ai tuoi sistemi di HR, di calcolo delle retribuzioni e di analisi, così come ai servizi interni dell’azienda.

La documentazione è pubblicata in due versioni:

🚀 Nuova documentazione — la versione attuale del manuale, con la struttura aggiornata e gli ultimi metodi: 👉 https://api2.shifton.com/openapi/
📄 Vecchia documentazione — la versione precedente (ancora supportata per le integrazioni esistenti): 👉 https://api2.shifton.com/docs/

Puoi aprire entrambe le versioni direttamente dall’applicazione — nella sezione Developer, nella scheda Panoramica, con i pulsanti «Nuova documentazione» e «Vecchia documentazione».

La documentazione è disponibile in due lingue. Nell’angolo in alto a destra della pagina della nuova documentazione c’è un selettore EN / RU: la lingua scelta viene memorizzata.

Come ottenere una chiave API

La chiave API si crea direttamente nell’applicazione:

Apri la sezione Developer.
Passa alla scheda Chiavi API («Chiavi API»).
Premi «Crea chiave API».

Cosa compilare durante la creazione della chiave

Si aprirà il pannello laterale Crea chiave API con i campi:

Titolo — il nome della chiave, campo obbligatorio. Assegna un nome in base allo scopo, così poi saprai cosa disattivare: «Esportazione verso 1C», «Report per l’analisi».
Scade alle — la data dopo la quale la chiave cesserà di essere valida. Se lasci il campo vuoto, la validità non ha limiti.
Accesso — l’ampiezza dei permessi della chiave:
Full access (act as me) — la chiave funziona a tuo nome e con i tuoi permessi.
Autorizzazioni limitate — un insieme limitato di permessi, che scegli tu stesso.

Premi Aggiungi per creare la chiave, oppure Annulla per chiudere il pannello.

📷 *Schermata del pannello di creazione della chiave — da acquisire in produzione*

La chiave viene creata per un’azienda specifica e funziona solo con i dati di quell’azienda. Puoi revocare la chiave in qualsiasi momento: la revoca è immediata e tutte le richieste successive con quella chiave restituiranno l’errore 401.

Importante: la chiave creata viene mostrata una sola volta. Copiala subito e conservala in un luogo sicuro — non è possibile ottenerla di nuovo. Se la chiave va perduta, creane una nuova e revoca quella vecchia.

Autorizzazione

Tutte le richieste all’API vengono firmate con la chiave nell’intestazione:

Authorization: Bearer {your_API_key}

Indirizzo di base dell’API:

https://api2.shifton.com/work/1.0.0

Una richiesta senza una chiave valida restituisce 401 e il corpo {"message":"Unauthenticated."}.

Prima richiesta

Per esempio, per ottenere l’elenco dei dipendenti dell’azienda (sostituisci il tuo ID azienda al posto di {companyId}):

GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/json

La stessa cosa tramite curl:

curl -H "Authorization: Bearer {your_API_key}" \
     -H "Accept: application/json" \
     https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees

L’ID dell’azienda è visibile nella barra degli indirizzi dell’applicazione: app.shifton.com/c/8397/... — il numero che segue /c/.

Cosa è disponibile tramite l’API

Il manuale copre più di 360 metodi. Le sezioni principali per il servizio in campo:

Attività — /companies/{companyId}/tasks: creazione, modifica, stati, file delle attività.
Elenco delle cose da fare (To Do) — /companies/{companyId}/todo.
Clienti — /companies/{companyId}/clients, oltre agli indirizzi e ai campi personalizzati dei clienti.
Elenchi di controllo — /companies/{companyId}/checklists.
Zone di servizio — /companies/{companyId}/tasks/service-areas.
Competenze — /companies/{companyId}/skills.
Dipendenti — /companies/{companyId}/employees: aggiunta, modifica, cessazione e ripristino.
Inventario — articoli, categorie, kit e giacenze nei magazzini.
Documenti finanziari — preventivi, ordini di lavoro, fatture, ricevute, contatori dei documenti e logo.
Report — esportazione dei dati su lavoro e presenze.

Inoltre sono disponibili pianificazioni e turni, ferie e richieste di permesso, presenze, fatturazione e fatturazione SMS, notifiche e moduli.

Webhook

Se, invece di inviare richieste periodiche all’API, hai bisogno di ricevere gli eventi nel momento in cui si verificano, usa i webhook — la scheda Webhooks nella sezione Developer. Shifton invierà da sé una richiesta al tuo indirizzo quando si verificherà l’evento desiderato; l’elenco degli eventi supportati viene restituito da un metodo a parte.

Codici di errore

L’API di Shifton usa i codici di stato HTTP standard:

200 — richiesta eseguita con successo.
201 — oggetto creato con successo.
400 — parametri della richiesta errati.
401 — errore di autorizzazione: la chiave non è stata trasmessa, non è valida oppure è stata revocata.
403 — accesso negato.
404 — risorsa non trovata (nella maggior parte dei casi si tratta di un errore di battitura nell’indirizzo del metodo).
500 — errore del server.

Consigli per l’uso

Per le nuove integrazioni usa la nuova documentazione — quella vecchia è stata mantenuta per le integrazioni già funzionanti.
Per verificare le richieste sono comodi Postman o curl: permettono di vedere la risposta senza scrivere una riga di codice.
Non conservare la chiave in chiaro nel codice e non trasmetterla a terzi: la chiave dà accesso ai dati dell’azienda.
Rispetta i limiti sulla frequenza delle richieste (rate limits) — il loro superamento può portare a un blocco temporaneo dell’accesso all’API.

Domande frequenti

Domanda: Dove si ottiene la chiave API? Risposta: Nell’applicazione: sezione Developer → scheda Chiavi API → pulsante «Crea chiave API». La chiave viene rilasciata per l’azienda corrente.

Domanda: Ho chiuso la finestra e non ho copiato la chiave. Dove posso vederla? Risposta: In nessun posto — la chiave viene mostrata una sola volta e non viene rilasciata di nuovo. Crea una nuova chiave e revoca quella vecchia.

Domanda: Come si revoca una chiave se è finita nelle mani sbagliate? Risposta: Eliminala nella scheda Chiavi API. La revoca è immediata: tutte le richieste con quella chiave inizieranno subito a restituire 401.

Domanda: Qual è la differenza tra «Full access» e «Restricted permissions»? Risposta: Full access (act as me) dà alla chiave gli stessi permessi che hai tu. Autorizzazioni limitate consente di assegnare alla chiave solo l’insieme di permessi selezionato — è più sicuro per un’integrazione che deve accedere solo a una parte dei dati.

Domanda: È possibile limitare la validità della chiave? Risposta: Sì, con il campo Scade alle durante la creazione. Se non lo compili, la chiave sarà senza scadenza.

Domanda: Una sola chiave funziona per più aziende? Risposta: No. La chiave è associata all’azienda in cui è stata creata e funziona solo con i dati di quell’azienda. Per un’altra azienda crea una chiave a parte.

Domanda: Qual è l’indirizzo di base dell’API? Risposta: https://api2.shifton.com/work/1.0.0. Poi segue il percorso del metodo, per esempio /companies/{companyId}/tasks.

Domanda: Dove si trova l’ID azienda da usare nelle richieste? Risposta: Si trova nella barra degli indirizzi dell’applicazione subito dopo /c/ — per esempio, in app.shifton.com/c/8397/tasks l’identificativo dell’azienda è 8397.

Domanda: Quale versione della documentazione conviene usare? Risposta: Per le nuove integrazioni quella nuova (api2.shifton.com/openapi). Quella vecchia (api2.shifton.com/docs) è supportata per le integrazioni esistenti.

Domanda: Esiste la documentazione in lingua russa? Risposta: Sì. Nella pagina della nuova documentazione, nell’angolo in alto a destra, c’è il selettore EN / RU.

Domanda: Con che cosa si testano le richieste all’API? Risposta: Il modo più comodo è Postman o curl: permettono di inviare richieste e vedere le risposte senza scrivere codice.

Domanda: Perché ricevo 401 anche se ho copiato la chiave? Risposta: Verifica che la chiave venga trasmessa nell’intestazione Authorization con la parola Bearer davanti, che la chiave non sia stata revocata e che non sia scaduta.

Domanda: Perché ricevo 404? Risposta: Nella maggior parte dei casi l’indirizzo è sbagliato: la parte di base deve essere https://api2.shifton.com/work/1.0.0, e nel percorso del metodo deve esserci il {companyId} corretto.

Domanda: Che cosa si può automatizzare tramite l’API? Risposta: La creazione e la modifica delle attività, la gestione dei clienti e dei loro indirizzi, gli elenchi di controllo, le zone di servizio, le competenze, i dipendenti, l’inventario, i documenti Documenti finanziari e l’esportazione dei report, così come le pianificazioni, i turni e le ferie.

Domanda: È possibile ricevere gli eventi da Shifton invece di interrogare l’API? Risposta: Sì, a questo servono i webhook — la scheda Webhooks nella sezione Developer.

Domanda: Il cambio della password influisce sul funzionamento dell’integrazione? Risposta: No. Le integrazioni funzionano con la chiave API, non con la password dell’account.