Τεκμηρίωση API

Το Shifton Εργασίες σας επιτρέπει να αυτοματοποιήσετε την εργασία με την πλατφόρμα και να τη συνδέσετε με εξωτερικές υπηρεσίες μέσω ανοιχτού API. Μέσω του API είναι διαθέσιμες όλες οι βασικές οντότητες — εργασίες, πελάτες, εργαζόμενοι, λίστες ελέγχου, απογραφή, ζώνες εξυπηρέτησης, έγγραφα της Τιμολόγησης και αναφορές — γι’ αυτό το Shifton μπορεί να συνδεθεί με τα συστήματά σας HR, μισθοδοσίας και ανάλυσης, καθώς και με τις εσωτερικές υπηρεσίες της εταιρείας.

Η τεκμηρίωση έχει δημοσιευθεί σε δύο εκδόσεις:

🚀 Νέα τεκμηρίωση — η τρέχουσα έκδοση του εγχειριδίου με ανανεωμένη δομή και τις τελευταίες μεθόδους: 👉 https://api2.shifton.com/openapi/
📄 Παλιά τεκμηρίωση — η προηγούμενη έκδοση (εξακολουθεί να υποστηρίζεται για τις υπάρχουσες ενσωματώσεις): 👉 https://api2.shifton.com/docs/

Και τις δύο εκδόσεις μπορείτε να τις ανοίξετε απευθείας από την εφαρμογή — στην ενότητα Developer, στην καρτέλα Επισκόπηση, με τα κουμπιά «Νέα τεκμηρίωση» και «Παλιά τεκμηρίωση».

Η τεκμηρίωση είναι διαθέσιμη σε δύο γλώσσες. Στην πάνω δεξιά γωνία της σελίδας της νέας τεκμηρίωσης υπάρχει ο διακόπτης EN / RU — η επιλεγμένη γλώσσα απομνημονεύεται.

Πώς να πάρετε ένα κλειδί API

Το κλειδί API δημιουργείται μέσα στην ίδια την εφαρμογή:

Ανοίξτε την ενότητα Developer.
Μεταβείτε στην καρτέλα Κλειδιά API («Κλειδιά API»).
Πατήστε «Δημιουργία κλειδιού API».

Τι να συμπληρώσετε κατά τη δημιουργία του κλειδιού

Θα ανοίξει το πλαϊνό πάνελ Δημιουργία κλειδιού API με τα πεδία:

Τίτλος — το όνομα του κλειδιού, υποχρεωτικό πεδίο. Ονομάζετέ τα κατά τον σκοπό τους, ώστε αργότερα να είναι σαφές τι να απενεργοποιήσετε: «Εξαγωγή στο 1C», «Αναφορές για ανάλυση».
Λήγει στις — η ημερομηνία μετά την οποία το κλειδί παύει να ισχύει. Αν αφήσετε το πεδίο κενό, η διάρκεια ισχύος δεν είναι περιορισμένη.
Πρόσβαση — το εύρος των δικαιωμάτων του κλειδιού:
Full access (act as me) — το κλειδί λειτουργεί στο όνομά σας και με τα δικαιώματά σας.
Περιορισμένα δικαιώματα — περιορισμένο σύνολο αδειών, το οποίο επιλέγετε εσείς.

Πατήστε Προσθέτω, για να δημιουργήσετε το κλειδί, ή Ματαίωση, για να κλείσετε το πάνελ.

📷 *Στιγμιότυπο του πάνελ δημιουργίας κλειδιού — να τραβηχτεί στο prod*

Το κλειδί δημιουργείται για μια συγκεκριμένη εταιρεία και λειτουργεί μόνο με τα δεδομένα της. Η ανάκληση του κλειδιού μπορεί να γίνει ανά πάσα στιγμή — η ανάκληση ισχύει άμεσα και όλα τα επόμενα αιτήματα με αυτό το κλειδί θα επιστρέψουν σφάλμα 401.

Σημαντικό: το κλειδί που δημιουργείται εμφανίζεται μόνο μία φορά. Αντιγράψτε το αμέσως και φυλάξτε το σε ασφαλές μέρος — δεν μπορείτε να το πάρετε ξανά. Αν το κλειδί χαθεί, δημιουργήστε νέο και ανακαλέστε το παλιό.

Εξουσιοδότηση

Όλα τα αιτήματα προς το API υπογράφονται με το κλειδί στην κεφαλίδα:

Authorization: Bearer {your_API_key}

Η βασική διεύθυνση του API:

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

Ένα αίτημα χωρίς έγκυρο κλειδί επιστρέφει 401 και το σώμα {"message":"Unauthenticated."}.

Το πρώτο αίτημα

Για παράδειγμα, για να πάρετε τη λίστα των εργαζομένων της εταιρείας (βάλτε το δικό σας ID εταιρείας στη θέση του {companyId}):

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

Το ίδιο μέσω curl:

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

Το ID της εταιρείας φαίνεται στη γραμμή διευθύνσεων της εφαρμογής: app.shifton.com/c/8397/... — ο αριθμός μετά το /c/.

Τι είναι διαθέσιμο μέσω του API

Το εγχειρίδιο καλύπτει πάνω από 360 μεθόδους. Οι βασικές ενότητες για την υπηρεσία πεδίου:

Εργασίες — /companies/{companyId}/tasks: δημιουργία, τροποποίηση, καταστάσεις, αρχεία εργασιών.
Λίστα υποχρεώσεων (To Do) — /companies/{companyId}/todo.
Πελάτες — /companies/{companyId}/clients, καθώς και διευθύνσεις και προσαρμοσμένα πεδία πελατών.
Λίστες ελέγχου — /companies/{companyId}/checklists.
Ζώνες εξυπηρέτησης — /companies/{companyId}/tasks/service-areas.
Δεξιότητες — /companies/{companyId}/skills.
Εργαζόμενοι — /companies/{companyId}/employees: προσθήκη, τροποποίηση, απόλυση και επαναφορά.
Απογραφή — αντικείμενα, κατηγορίες, σετ και υπόλοιπα στις αποθήκες.
Τιμολόγηση — εκτιμήσεις, εντολές εργασίας, γραμμάτια, αποδείξεις, μετρητές εγγράφων και λογότυπο.
Αναφορές — εξαγωγή δεδομένων για την εργασία και την παρουσία.

Επιπλέον, είναι διαθέσιμα τα προγράμματα και οι βάρδιες, οι άδειες και τα αιτήματα ρεπό, η παρουσία, η χρέωση και η χρέωση SMS, οι ειδοποιήσεις και οι μονάδες.

Webhooks

Αν αντί για τακτικά αιτήματα προς το API χρειάζεται να λαμβάνετε τα γεγονότα τη στιγμή που συμβαίνουν, χρησιμοποιήστε τα webhooks — καρτέλα Webhooks στην ενότητα Developer. Το Shifton θα στείλει μόνο του αίτημα στη διεύθυνσή σας, όταν συμβεί το γεγονός που χρειάζεστε· τη λίστα των υποστηριζόμενων γεγονότων την επιστρέφει ξεχωριστή μέθοδος.

Κωδικοί σφαλμάτων

Το API του Shifton χρησιμοποιεί τους τυπικούς κωδικούς κατάστασης HTTP:

200 — το αίτημα εκτελέστηκε με επιτυχία.
201 — το αντικείμενο δημιουργήθηκε με επιτυχία.
400 — λανθασμένες παράμετροι του αιτήματος.
401 — σφάλμα εξουσιοδότησης: το κλειδί δεν στάλθηκε, δεν είναι έγκυρο ή έχει ανακληθεί.
403 — η πρόσβαση απαγορεύεται.
404 — ο πόρος δεν βρέθηκε (συνήθως τυπογραφικό λάθος στη διεύθυνση της μεθόδου).
500 — σφάλμα του διακομιστή.

Συμβουλές για τη χρήση

Για νέες ενσωματώσεις χρησιμοποιείτε τη νέα τεκμηρίωση — η παλιά έχει μείνει για τις ενσωματώσεις που λειτουργούν ήδη.
Για τον έλεγχο των αιτημάτων βολεύουν το Postman ή το curl — σας επιτρέπουν να δείτε την απάντηση χωρίς να γράψετε ούτε μια γραμμή κώδικα.
Μην αποθηκεύετε το κλειδί σε ανοιχτή μορφή μέσα στον κώδικα και μην το δίνετε σε τρίτους: το κλειδί δίνει πρόσβαση στα δεδομένα της εταιρείας.
Τηρείτε τους περιορισμούς στη συχνότητα των αιτημάτων (rate limits) — η υπέρβασή τους μπορεί να οδηγήσει σε προσωρινό αποκλεισμό της πρόσβασης στο API.

Συχνές ερωτήσεις

Ερώτηση: Από πού παίρνω το κλειδί API; Απάντηση: Στην εφαρμογή: ενότητα Developer → καρτέλα Κλειδιά API → κουμπί «Δημιουργία κλειδιού API». Το κλειδί εκδίδεται για την τρέχουσα εταιρεία.

Ερώτηση: Έκλεισα το παράθυρο και δεν αντέγραψα το κλειδί. Πού το βλέπω; Απάντηση: Πουθενά — το κλειδί εμφανίζεται μόνο μία φορά και δεν εκδίδεται ξανά. Δημιουργήστε νέο κλειδί και ανακαλέστε το παλιό.

Ερώτηση: Πώς να ανακαλέσω το κλειδί, αν έπεσε σε λάθος χέρια; Απάντηση: Διαγράψτε το στην καρτέλα Κλειδιά API. Η ανάκληση ισχύει άμεσα: όλα τα αιτήματα με αυτό το κλειδί θα αρχίσουν αμέσως να επιστρέφουν 401.

Ερώτηση: Σε τι διαφέρουν το «Full access» και το «Restricted permissions»; Απάντηση: Το Full access (act as me) δίνει στο κλειδί τα ίδια δικαιώματα που έχετε εσείς. Τα Περιορισμένα δικαιώματα επιτρέπουν να δώσετε στο κλειδί μόνο το επιλεγμένο σύνολο αδειών — έτσι είναι ασφαλέστερο για μια ενσωμάτωση που χρειάζεται πρόσβαση μόνο σε μέρος των δεδομένων.

Ερώτηση: Μπορώ να περιορίσω τη διάρκεια ισχύος του κλειδιού; Απάντηση: Ναι, με το πεδίο Λήγει στις κατά τη δημιουργία. Αν δεν το συμπληρώσετε, το κλειδί θα είναι χωρίς λήξη.

Ερώτηση: Λειτουργεί ένα κλειδί για πολλές εταιρείες; Απάντηση: Όχι. Το κλειδί είναι συνδεδεμένο με την εταιρεία στην οποία δημιουργήθηκε και λειτουργεί μόνο με τα δεδομένα της. Για άλλη εταιρεία δημιουργήστε ξεχωριστό κλειδί.

Ερώτηση: Ποια είναι η βασική διεύθυνση του API; Απάντηση: https://api2.shifton.com/work/1.0.0. Πιο κάτω ακολουθεί η διαδρομή της μεθόδου, για παράδειγμα /companies/{companyId}/tasks.

Ερώτηση: Από πού παίρνω το ID της εταιρείας για τα αιτήματα; Απάντηση: Υπάρχει στη γραμμή διευθύνσεων της εφαρμογής αμέσως μετά το /c/ — για παράδειγμα, στο app.shifton.com/c/8397/tasks το αναγνωριστικό της εταιρείας είναι 8397.

Ερώτηση: Ποια έκδοση της τεκμηρίωσης να χρησιμοποιώ; Απάντηση: Για νέες ενσωματώσεις τη νέα (api2.shifton.com/openapi). Η παλιά (api2.shifton.com/docs) υποστηρίζεται για τις υπάρχουσες ενσωματώσεις.

Ερώτηση: Υπάρχει τεκμηρίωση στα ρωσικά; Απάντηση: Ναι. Στη σελίδα της νέας τεκμηρίωσης, στην πάνω δεξιά γωνία, υπάρχει ο διακόπτης EN / RU.

Ερώτηση: Με τι να δοκιμάσω τα αιτήματα προς το API; Απάντηση: Πιο βολικά με το Postman ή το curl — σας επιτρέπουν να στέλνετε αιτήματα και να βλέπετε τις απαντήσεις χωρίς να γράψετε κώδικα.

Ερώτηση: Γιατί έρχεται 401, ενώ αντέγραψα το κλειδί; Απάντηση: Ελέγξτε ότι το κλειδί στέλνεται στην κεφαλίδα Authorization με τη λέξη Bearer μπροστά του, ότι δεν έχει ανακληθεί και ότι δεν έχει λήξει η ισχύς του.

Ερώτηση: Γιατί έρχεται 404; Απάντηση: Συνήθως η διεύθυνση είναι μπερδεμένη: το βασικό μέρος πρέπει να είναι https://api2.shifton.com/work/1.0.0, και στη διαδρομή της μεθόδου το σωστό {companyId}.

Ερώτηση: Τι μπορεί να αυτοματοποιηθεί μέσω του API; Απάντηση: Η δημιουργία και η τροποποίηση εργασιών, η εργασία με τους πελάτες και τις διευθύνσεις τους, οι λίστες ελέγχου, οι ζώνες εξυπηρέτησης, οι δεξιότητες, οι εργαζόμενοι, η απογραφή, τα έγγραφα της Τιμολόγησης και η εξαγωγή αναφορών, καθώς και τα προγράμματα, οι βάρδιες και οι άδειες.

Ερώτηση: Μπορώ να λαμβάνω γεγονότα από το Shifton χωρίς να ρωτώ το API; Απάντηση: Ναι, γι’ αυτό υπάρχουν τα webhooks — καρτέλα Webhooks στην ενότητα Developer.

Ερώτηση: Επηρεάζει η αλλαγή του κωδικού πρόσβασης τη λειτουργία της ενσωμάτωσης; Απάντηση: Όχι. Οι ενσωματώσεις λειτουργούν με το κλειδί API, όχι με τον κωδικό πρόσβασης του λογαριασμού.