API-dokumentatsioon

Shifton Ülesanded võimaldab automatiseerida tööd platvormiga ja ühendada selle avatud API kaudu väliste teenustega. API kaudu on saadaval kõik põhilised olemid — ülesanded, kliendid, töötajad, kontroll-loendid, inventar, teeninduspiirkonnad, arveldamise dokumendid ja aruanded —, seetõttu saab Shiftoni siduda teie HR-, palgaarvestuse ja analüütika süsteemidega ning ka ettevõtte sisemiste teenustega.

Dokumentatsioon on avaldatud kahes versioonis:

🚀 Uus dokumentatsioon — teatmiku ajakohane versioon uuendatud struktuuri ja uusimate meetoditega: 👉 https://api2.shifton.com/openapi/
📄 Vana dokumentatsioon — eelmine versioon (olemasolevate integratsioonide jaoks endiselt toetatud): 👉 https://api2.shifton.com/docs/

Mõlemat versiooni saab avada otse rakendusest — jaotises Developer, vahekaardil Ülevaade, nuppudega „Uus dokumentatsioon“ ja „Vana dokumentatsioon“.

Dokumentatsioon on saadaval kahes keeles. Uue dokumentatsiooni lehe paremas ülanurgas on lüliti EN / RU — valitud keel jäetakse meelde.

Kuidas saada API-võti

API-võti luuakse rakenduses endas:

Avage jaotis Developer.
Minge vahekaardile API-võtmed („API-võtmed“).
Klõpsake „Loo API-võti“.

Mida tuleb võtme loomisel täita

Avaneb külgpaneel Loo API-võti järgmiste väljadega:

Pealkiri — võtme nimi, kohustuslik väli. Nimetage otstarbe järgi, et hiljem oleks selge, mida välja lülitada: „Eksport 1C-sse“, „Aruanded analüütika jaoks“.
Aegub kell — kuupäev, mille järel võti lakkab kehtimast. Kui väli tühjaks jätta, ei ole kehtivusaeg piiratud.
Juurdepääs — võtme õiguste ulatus:
Full access (act as me) — võti töötab teie nimel ja teie õigustega.
Piiratud õigused — piiratud õiguste komplekt, mille valite ise.

Klõpsake Lisa, et võti luua, või Tühista, et paneel sulgeda.

📷 *Võtme loomise paneeli kuvatõmmis — teha prodis*

Võti luuakse konkreetse ettevõtte jaoks ja töötab ainult selle andmetega. Võtme saab igal ajal tühistada — tühistamine jõustub kohe ja kõik järgnevad päringud selle võtmega tagastavad vea 401.

Tähtis: loodud võtit näidatakse ainult üks kord. Kopeerige see kohe ja hoidke turvalises kohas — uuesti seda saada ei ole võimalik. Kui võti on kaotatud, looge uus ja vana tühistage.

Autoriseerimine

Kõik päringud API-le allkirjastatakse päises oleva võtmega:

Authorization: Bearer {your_API_key}

API baasaadress:

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

Päring ilma kehtiva võtmeta tagastab 401 ja keha {"message":"Unauthenticated."}.

Esimene päring

Näiteks selleks, et saada ettevõtte töötajate loend (asendage {companyId} oma ettevõtte ID-ga):

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

Sama curl-i abil:

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

Ettevõtte ID on näha rakenduse aadressiribal: app.shifton.com/c/8397/... — arv pärast /c/.

Mis on API kaudu saadaval

Teatmik hõlmab üle 360 meetodi. Väljasõiduteeninduse peamised jaotised:

Ülesanded — /companies/{companyId}/tasks: loomine, muutmine, olekud, ülesannete failid.
Tegemiste loend (To Do) — /companies/{companyId}/todo.
Kliendid — /companies/{companyId}/clients, samuti klientide aadressid ja kohandatud väljad.
Kontroll-loendid — /companies/{companyId}/checklists.
Teeninduspiirkonnad — /companies/{companyId}/tasks/service-areas.
Oskused — /companies/{companyId}/skills.
Töötajad — /companies/{companyId}/employees: lisamine, muutmine, vabastamine ja taastamine.
Inventar — esemed, kategooriad, komplektid ja laojäägid.
Arveldamine — hinnangud, töökorraldused, arved, kviitungid, dokumentide loendurid ja logo.
Aruanded — töö ja kohaloleku andmete eksport.

Lisaks on saadaval graafikud ja vahetused, puhkused ja vabade päevade taotlused, kohalolek, arveldus ja SMS-i arveldus, teavitused ja moodulid.

Veebihookid

Kui teil on vaja API korrapärase pärimise asemel saada sündmusi nende tekkimise hetkel, kasutage veebihooke — vahekaart Webhooks jaotises Developer. Shifton saadab ise päringu teie aadressile, kui toimub vajalik sündmus; toetatud sündmuste loendi tagastab eraldi meetod.

Veakoodid

Shiftoni API kasutab standardseid HTTP olekukoode:

200 — päring täideti edukalt.
201 — objekt loodi edukalt.
400 — päringu parameetrid on valed.
401 — autoriseerimise viga: võtit ei edastatud, see on kehtetu või tühistatud.
403 — juurdepääs on keelatud.
404 — ressurssi ei leitud (kõige sagedamini trükiviga meetodi aadressis).
500 — serveri viga.

Kasutusnõuanded

Uute integratsioonide jaoks kasutage uut dokumentatsiooni — vana on jäetud juba töötavate integratsioonide jaoks.
Päringute kontrollimiseks on mugavad Postman või curl — need võimaldavad vastust näha, ilma et kirjutaksite ainsatki koodirida.
Ärge hoidke võtit koodis avatud kujul ja ärge edastage seda kolmandatele isikutele: võti annab juurdepääsu ettevõtte andmetele.
Järgige päringute sageduse piiranguid (rate limits) — nende ületamine võib kaasa tuua ajutise API-le juurdepääsu blokeerimise.

Korduma kippuvad küsimused (KKK)

Küsimus: Kust saada API-võti? Vastus: Rakendusest: jaotis Developer → vahekaart API-võtmed → nupp „Loo API-võti“. Võti väljastatakse praeguse ettevõtte jaoks.

Küsimus: Sulgesin akna ja ei kopeerinud võtit. Kust seda vaadata? Vastus: Mitte kusagilt — võtit näidatakse ainult üks kord ja uuesti seda ei väljastata. Looge uus võti ja vana tühistage.

Küsimus: Kuidas võti tühistada, kui see on sattunud valedesse kätesse? Vastus: Kustutage see vahekaardil API-võtmed. Tühistamine jõustub kohe: kõik selle võtmega tehtud päringud hakkavad kohe tagastama 401.

Küsimus: Mille poolest erinevad „Full access“ ja „Restricted permissions“? Vastus: Full access (act as me) annab võtmele samad õigused, mis on teil. Piiratud õigused võimaldab anda võtmele ainult valitud õiguste komplekti — nii on turvalisem integratsiooni jaoks, mis vajab juurdepääsu ainult osale andmetest.

Küsimus: Kas võtme kehtivusaega saab piirata? Vastus: Jah, loomisel on selleks väli Aegub kell. Kui seda mitte täita, on võti tähtajatu.

Küsimus: Kas üks võti töötab mitme ettevõtte jaoks? Vastus: Ei. Võti on seotud selle ettevõttega, milles see loodi, ja töötab ainult selle andmetega. Teise ettevõtte jaoks looge eraldi võti.

Küsimus: Milline on API baasaadress? Vastus: https://api2.shifton.com/work/1.0.0. Edasi tuleb meetodi tee, näiteks /companies/{companyId}/tasks.

Küsimus: Kust saada päringute jaoks ettevõtte ID? Vastus: See on rakenduse aadressiribal kohe pärast /c/ — näiteks aadressis app.shifton.com/c/8397/tasks on ettevõtte identifikaator 8397.

Küsimus: Millist dokumentatsiooni versiooni kasutada? Vastus: Uute integratsioonide jaoks uut (api2.shifton.com/openapi). Vana (api2.shifton.com/docs) on toetatud olemasolevate integratsioonide jaoks.

Küsimus: Kas dokumentatsioon on olemas vene keeles? Vastus: Jah. Uue dokumentatsiooni lehel paremas ülanurgas on lüliti EN / RU.

Küsimus: Millega API-päringuid testida? Vastus: Kõige mugavam on Postman või curl — need võimaldavad päringuid saata ja vastuseid vaadata ilma koodi kirjutamata.

Küsimus: Miks tuleb 401, kuigi ma kopeerisin võtme? Vastus: Kontrollige, et võti edastatakse päises Authorization ja sellele eelneb sõna Bearer, et võti ei ole tühistatud ja et selle kehtivusaeg ei ole lõppenud.

Küsimus: Miks tuleb 404? Vastus: Kõige sagedamini on aadress segamini läinud: baasosa peab olema https://api2.shifton.com/work/1.0.0, meetodi tees aga peab olema õige {companyId}.

Küsimus: Mida saab API kaudu automatiseerida? Vastus: Ülesannete loomist ja muutmist, tööd klientide ja nende aadressidega, kontroll-loendeid, teeninduspiirkondi, oskusi, töötajaid, inventari, arveldamise dokumente ja aruannete eksporti, samuti graafikuid, vahetusi ja puhkusi.

Küsimus: Kas Shiftonist saab sündmusi vastu võtta, ilma et API-t korrapäraselt päriks? Vastus: Jah, selleks on veebihookid — vahekaart Webhooks jaotises Developer.

Küsimus: Kas parooli muutmine mõjutab integratsiooni tööd? Vastus: Ei. Integratsioonid töötavad API-võtme, mitte konto parooli alusel.