API-dokumentasie

Shifton Take laat toe om die werk met die platform te outomatiseer en dit deur die oop API aan eksterne dienste te koppel. Deur die API is al die sleutelentiteite beskikbaar — take, kliënte, werknemers, kontrolelyste, inventaris, diensgebiede, dokumente van Finansiële dokumente en verslae — daarom kan Shifton met u stelsels vir HR, loonberekening en analise verbind word, en ook met die interne dienste van die maatskappy.

API-dokumentasie

Die dokumentasie is in twee weergawes gepubliseer:

• 🚀 Nuwe dokumentasie — die aktuele weergawe van die naslaanwerk met ’n bygewerkte struktuur en die nuutste metodes: 👉 https://api2.shifton.com/openapi/
• 📄 Ou dokumentasie — die vorige weergawe (word steeds vir bestaande integrasies ondersteun): 👉 https://api2.shifton.com/docs/

Beide weergawes kan direk uit die toepassing oopgemaak word — in die afdeling Developer, op die oortjie Oorsig, met die knoppies “Nuwe dokumentasie” en “Ou dokumentasie”.

Die dokumentasie is in twee tale beskikbaar. In die regter boonste hoek van die bladsy met die nuwe dokumentasie is daar ’n skakelaar EN / RU — die gekose taal word onthou.

Hoe om ’n API-sleutel te kry

Die API-sleutel word in die toepassing self geskep:

• Maak die afdeling Developer oop.
• Gaan na die oortjie API-sleutels (“API-sleutels”).
• Klik op “Skep API-sleutel”.

Wat om by die skepping van ’n sleutel in te vul

Die sypaneel Skep API-sleutel gaan oop met die velde:

• Titel — die naam van die sleutel, ’n verpligte veld. Noem dit volgens die doel sodat dit later duidelik is wat om af te skakel: “Uitvoer na 1C”, “Verslae vir analise”.
• Verstryk om — die datum waarna die sleutel ophou werk. As die veld leeg gelaat word, is die geldigheidsduur onbeperk.
• Toegang — die omvang van die regte van die sleutel:
• Full access (act as me) — die sleutel werk in u naam en met u regte.
• Beperkte toestemmings — ’n beperkte stel toestemmings wat u self kies.

Klik op Voeg by om die sleutel te skep, of op Kanselleer om die paneel te sluit.

📷 *Skermskoot van die paneel vir die skepping van ’n sleutel — op prod neem*

Die sleutel word vir ’n bepaalde maatskappy geskep en werk slegs met die gegewens daarvan. Die sleutel kan op enige oomblik teruggetrek word — die terugtrekking geld onmiddellik, en alle daaropvolgende versoeke met hierdie sleutel gee die fout 401 terug.

Belangrik: die geskepte sleutel word slegs een keer gewys. Kopieer dit dadelik en bewaar dit op ’n veilige plek — dit kan nie weer verkry word nie. As die sleutel verlore is, skep ’n nuwe een en trek die oue terug.

Outorisasie

Alle versoeke aan die API word met die sleutel in die kopstuk onderteken:

Authorization: Bearer {your_API_key}

Die basisadres van die API:

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

’n Versoek sonder ’n geldige sleutel gee 401 terug en die liggaam {"message":"Unauthenticated."}.

Die eerste versoek

Byvoorbeeld, om die lys werknemers van die maatskappy te kry (vervang {companyId} met u eie maatskappy-ID):

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

Dieselfde deur curl:

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

Die maatskappy-ID is in die adresbalk van die toepassing te sien: app.shifton.com/c/8397/... — die getal ná /c/.

Wat deur die API beskikbaar is

Die naslaanwerk dek meer as 360 metodes. Die hoofafdelings vir uitgaande diens:

• Take — /companies/{companyId}/tasks: die skepping, verandering, statusse, lêers van take.
• Takelys (To Do) — /companies/{companyId}/todo.
• Kliënte — /companies/{companyId}/clients, en ook die adresse en die gebruikersvelde van die kliënte.
• Kontrolelyste — /companies/{companyId}/checklists.
• Diensgebiede — /companies/{companyId}/tasks/service-areas.
• Vaardighede — /companies/{companyId}/skills.
• Werknemers — /companies/{companyId}/employees: die byvoeging, redigering, ontslag en herstel.
• Inventaris — items, kategorieë, stelle en die oorskotte in die pakhuise.
• Finansiële dokumente — kwotasies, werkopdragte, fakture, kwitansies, dokumenttellers en die logo.
• Verslae — die uitvoer van gegewens oor die werk en die aanwesigheid.

Daarbenewens is die roosters en skofte, die vakansies en versoeke om vryaf, die aanwesigheid, die fakturering en SMS-fakturering, die kennisgewings en die modules beskikbaar.

Webhooks

As u in plaas van gereelde versoeke aan die API die gebeurtenisse op die oomblik van hulle ontstaan moet ontvang, gebruik webhooks — die oortjie Webhooks in die afdeling Developer. Shifton stuur self ’n versoek na u adres wanneer die nodige gebeurtenis plaasvind; die lys van ondersteunde gebeurtenisse word deur ’n afsonderlike metode teruggegee.

Foutkodes

Die API van Shifton gebruik die standaard HTTP-statuskodes:

• 200 — die versoek is suksesvol uitgevoer.
• 201 — die objek is suksesvol geskep.
• 400 — verkeerde parameters van die versoek.
• 401 — ’n fout by die outorisasie: die sleutel is nie oorgedra nie, is ongeldig of is teruggetrek.
• 403 — die toegang is verbode.
• 404 — die hulpbron is nie gevind nie (meestal ’n tikfout in die adres van die metode).
• 500 — ’n fout van die bediener.

Wenke vir die gebruik

• Gebruik vir nuwe integrasies die nuwe dokumentasie — die oue is gelaat vir integrasies wat reeds werk.
• Vir die kontrole van die versoeke is Postman of curl gerieflik — hulle laat toe om die antwoord te sien sonder om ’n enkele reël kode te skryf.
• Bewaar die sleutel nie in oop vorm in die kode nie en dra dit nie aan derde partye oor nie: die sleutel gee toegang tot die gegewens van die maatskappy.
• Hou by die beperkings op die frekwensie van versoeke (rate limits) — die oorskryding daarvan kan tot ’n tydelike blokkering van die toegang tot die API lei.

Gereelde vrae

Vraag: Waar kry ek ’n API-sleutel? Antwoord: In die toepassing: die afdeling Developer → die oortjie API-sleutels → die knoppie “Skep API-sleutel”. Die sleutel word vir die huidige maatskappy uitgereik.

Vraag: Ek het die venster toegemaak en die sleutel nie gekopieer nie. Waar kan ek dit sien? Antwoord: Nêrens — die sleutel word slegs een keer gewys en word nie weer uitgereik nie. Skep ’n nuwe sleutel en trek die oue terug.

Vraag: Hoe trek ek die sleutel terug as dit in die verkeerde hande beland het? Antwoord: Verwyder dit op die oortjie API-sleutels. Die terugtrekking geld onmiddellik: alle versoeke met hierdie sleutel begin dadelik 401 teruggee.

Vraag: Waarin verskil “Full access” en “Restricted permissions”? Antwoord: Full access (act as me) gee die sleutel dieselfde regte as wat u het. Beperkte toestemmings laat toe om aan die sleutel slegs die gekose stel toestemmings te gee — so is dit veiliger vir ’n integrasie wat slegs toegang tot ’n deel van die gegewens nodig het.

Vraag: Kan die geldigheidsduur van die sleutel beperk word? Antwoord: Ja, die veld Verstryk om by die skepping. As dit nie gevul word nie, is die sleutel onbeperk geldig.

Vraag: Werk een sleutel vir ’n paar maatskappye? Antwoord: Nee. Die sleutel is aan die maatskappy gekoppel waarin dit geskep is, en werk slegs met die gegewens daarvan. Skep vir ’n ander maatskappy ’n afsonderlike sleutel.

Vraag: Wat is die basisadres van die API? Antwoord: https://api2.shifton.com/work/1.0.0. Daarna volg die pad van die metode, byvoorbeeld /companies/{companyId}/tasks.

Vraag: Waar kry ek die maatskappy-ID vir die versoeke? Antwoord: Dit is in die adresbalk van die toepassing net ná /c/ — byvoorbeeld, in app.shifton.com/c/8397/tasks is die identifiseerder van die maatskappy gelyk aan 8397.

Vraag: Watter weergawe van die dokumentasie moet gebruik word? Antwoord: Vir nuwe integrasies — die nuwe een (api2.shifton.com/openapi). Die oue (api2.shifton.com/docs) word vir bestaande integrasies ondersteun.

Vraag: Is daar dokumentasie in Russies? Antwoord: Ja. Op die bladsy met die nuwe dokumentasie is daar in die regter boonste hoek ’n skakelaar EN / RU.

Vraag: Waarmee moet die versoeke aan die API getoets word? Antwoord: Postman of curl is die gerieflikste — hulle laat toe om versoeke te stuur en die antwoorde te bekyk sonder om kode te skryf.

Vraag: Waarom kom 401 terug al het ek die sleutel gekopieer? Antwoord: Kontroleer dat die sleutel in die kopstuk Authorization met die woord Bearer daarvoor oorgedra word, dat die sleutel nie teruggetrek is nie en dat die geldigheidsduur daarvan nie verstryk het nie.

Vraag: Waarom kom 404 terug? Antwoord: Meestal is die adres verwar: die basisdeel moet https://api2.shifton.com/work/1.0.0 wees, en in die pad van die metode — die korrekte {companyId}.

Vraag: Wat kan deur die API geoutomatiseer word? Antwoord: Die skepping en verandering van take, die werk met kliënte en hulle adresse, kontrolelyste, diensgebiede, vaardighede, werknemers, inventaris, dokumente van Finansiële dokumente en die uitvoer van verslae, en ook die roosters, skofte en vakansies.

Vraag: Kan gebeurtenisse uit Shifton ontvang word in plaas daarvan om die API te bevraag? Antwoord: Ja, daarvoor is daar webhooks — die oortjie Webhooks in die afdeling Developer.

Vraag: Beïnvloed die verandering van die wagwoord die werking van die integrasie? Antwoord: Nee. Die integrasies werk met die API-sleutel en nie met die wagwoord van die rekening nie.