Documentația API

Shifton Sarcini permite automatizarea lucrului cu platforma și conectarea acesteia la servicii externe prin API-ul deschis. Prin API sunt accesibile toate entitățile-cheie — sarcini, clienți, angajați, liste de verificare, inventar, zone de deservire, documentele Documente financiare și rapoartele —, de aceea Shifton poate fi legat de sistemele dvs. HR, de calcul al salariilor și de analiză, precum și de serviciile interne ale companiei.

Documentația este publicată în două versiuni:

🚀 Nouă documentație — versiunea actuală a ghidului, cu structură actualizată și cu cele mai noi metode: 👉 https://api2.shifton.com/openapi/
📄 Documentație veche — versiunea anterioară (în continuare susținută pentru integrările existente): 👉 https://api2.shifton.com/docs/

Ambele versiuni pot fi deschise direct din aplicație — în secțiunea Developer, pe fila Prezentare generală, cu butoanele „Nouă documentație” și „Documentație veche”.

Documentația este disponibilă în două limbi. În colțul din dreapta sus al paginii de documentație nouă există comutatorul EN / RU — limba selectată este memorată.

Cum obțineți o cheie API

Cheia API se creează chiar în aplicație:

Deschideți secțiunea Developer.
Treceți la fila Chei API („Chei API”).
Apăsați „Creați cheia API”.

Ce se completează la crearea cheii

Se va deschide panoul lateral Creați cheia API cu câmpurile:

Titlu — denumirea cheii, câmp obligatoriu. Denumiți-o după destinație, ca să fie clar mai târziu ce anume dezactivați: „Export în 1C”, „Rapoarte pentru analiză”.
Expiră la — data după care cheia va înceta să funcționeze. Dacă lăsați câmpul gol, termenul de valabilitate este nelimitat.
Acces — volumul de drepturi al cheii:
Full access (act as me) — cheia funcționează în numele dvs. și cu drepturile dvs.
Permisiuni restricționate — un set limitat de permisiuni, pe care îl alegeți chiar dvs.

Apăsați Adaugă pentru a crea cheia sau Anulează pentru a închide panoul.

📷 *Captură a panoului de creare a cheii — de făcut pe prod*

Cheia se creează pentru o companie concretă și funcționează numai cu datele acesteia. Cheia poate fi revocată în orice moment — revocarea are efect imediat, iar toate cererile ulterioare cu această cheie vor returna eroarea 401.

Important: cheia creată se afișează o singură dată. Copiați-o imediat și păstrați-o într-un loc sigur — nu poate fi obținută din nou. Dacă cheia este pierdută, creați una nouă, iar pe cea veche revocați-o.

Autorizare

Toate cererile către API se semnează cu cheia în antet:

Authorization: Bearer {your_API_key}

Adresa de bază a API-ului:

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

O cerere fără cheie valabilă returnează 401 și corpul {"message":"Unauthenticated."}.

Prima cerere

De exemplu, pentru a obține lista angajaților companiei (puneți ID-ul companiei dvs. în locul lui {companyId}):

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

Același lucru prin curl:

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

ID-ul companiei se vede în bara de adrese a aplicației: app.shifton.com/c/8397/... — numărul de după /c/.

Ce este accesibil prin API

Ghidul cuprinde peste 360 de metode. Secțiunile principale pentru serviciul pe teren:

Sarcini — /companies/{companyId}/tasks: crearea, modificarea, statusurile, fișierele sarcinilor.
Lista de treburi (To Do) — /companies/{companyId}/todo.
Clienți — /companies/{companyId}/clients, precum și adresele și câmpurile personalizate ale clienților.
Liste de verificare — /companies/{companyId}/checklists.
Zone de deservire — /companies/{companyId}/tasks/service-areas.
Abilități — /companies/{companyId}/skills.
Angajați — /companies/{companyId}/employees: adăugarea, editarea, concedierea și restabilirea.
Inventar — obiecte, categorii, seturi și stocuri în depozite.
Documente financiare — devize, comenzi de lucru, facturi, chitanțe, contoarele documentelor și sigla.
Rapoarte — exportul datelor despre muncă și prezență.

În afară de acestea, sunt disponibile programele și turele, concediile și cererile de învoire, prezența, facturarea și facturarea SMS, notificările și modulele.

Webhook-uri

Dacă în loc de cereri regulate către API aveți nevoie să primiți evenimentele în momentul apariției lor, folosiți webhook-urile — fila Webhooks din secțiunea Developer. Shifton va trimite el însuși cererea la adresa dvs. atunci când se va produce evenimentul necesar; lista evenimentelor susținute este returnată de o metodă separată.

Coduri de eroare

API-ul Shifton folosește codurile de stare HTTP standard:

200 — cererea a fost executată cu succes.
201 — obiectul a fost creat cu succes.
400 — parametri incorecți ai cererii.
401 — eroare de autorizare: cheia nu a fost transmisă, este nevalabilă sau a fost revocată.
403 — acces interzis.
404 — resursa nu a fost găsită (cel mai des, o greșeală de scriere în adresa metodei).
500 — eroare de server.

Sfaturi de utilizare

Pentru integrările noi folosiți documentația nouă — cea veche este lăsată pentru integrările care funcționează deja.
Pentru verificarea cererilor sunt comode Postman sau curl — ele permit să vedeți răspunsul fără a scrie nicio linie de cod.
Nu păstrați cheia în formă deschisă în cod și nu o transmiteți terților: cheia dă acces la datele companiei.
Respectați limitările privind frecvența cererilor (rate limits) — depășirea lor poate duce la blocarea temporară a accesului la API.

Întrebări frecvente

Întrebare: De unde iau cheia API? Răspuns: Din aplicație: secțiunea Developer → fila Chei API → butonul „Creați cheia API”. Cheia se emite pentru compania curentă.

Întrebare: Am închis fereastra și nu am copiat cheia. Unde o văd? Răspuns: Nicăieri — cheia se afișează o singură dată și nu se mai emite din nou. Creați o cheie nouă, iar pe cea veche revocați-o.

Întrebare: Cum revoc cheia, dacă a ajuns în mâini nepotrivite? Răspuns: Ștergeți-o pe fila Chei API. Revocarea are efect imediat: toate cererile cu această cheie vor începe imediat să returneze 401.

Întrebare: Prin ce se deosebesc „Full access” și „Restricted permissions”? Răspuns: Full access (act as me) dă cheii aceleași drepturi pe care le aveți dvs. Permisiuni restricționate permite să acordați cheii numai setul de permisiuni ales — așa este mai sigur pentru o integrare care are nevoie de acces doar la o parte din date.

Întrebare: Se poate limita termenul de valabilitate al cheii? Răspuns: Da, prin câmpul Expiră la la creare. Dacă nu îl completați, cheia va fi fără termen.

Întrebare: Funcționează o singură cheie pentru mai multe companii? Răspuns: Nu. Cheia este legată de compania în care a fost creată și funcționează numai cu datele acesteia. Pentru altă companie creați o cheie separată.

Întrebare: Care este adresa de bază a API-ului? Răspuns: https://api2.shifton.com/work/1.0.0. Mai departe urmează calea metodei, de exemplu /companies/{companyId}/tasks.

Întrebare: De unde iau ID-ul companiei pentru cereri? Răspuns: El se află în bara de adrese a aplicației imediat după /c/ — de exemplu, în app.shifton.com/c/8397/tasks identificatorul companiei este 8397.

Întrebare: Ce versiune a documentației să folosesc? Răspuns: Pentru integrările noi — cea nouă (api2.shifton.com/openapi). Cea veche (api2.shifton.com/docs) este susținută pentru integrările existente.

Întrebare: Există documentație în limba rusă? Răspuns: Da. Pe pagina documentației noi, în colțul din dreapta sus, se află comutatorul EN / RU.

Întrebare: Cu ce testez cererile către API? Răspuns: Cel mai comod este cu Postman sau curl — ele permit trimiterea cererilor și vizualizarea răspunsurilor fără a scrie cod.

Întrebare: De ce primesc 401, deși am copiat cheia? Răspuns: Verificați ca cheia să fie transmisă în antetul Authorization cu cuvântul Bearer înaintea ei, ca ea să nu fie revocată și să nu îi fi expirat termenul de valabilitate.

Întrebare: De ce primesc 404? Răspuns: Cel mai des adresa este încurcată: partea de bază trebuie să fie https://api2.shifton.com/work/1.0.0, iar în calea metodei — un {companyId} corect.

Întrebare: Ce se poate automatiza prin API? Răspuns: Crearea și modificarea sarcinilor, lucrul cu clienții și adresele lor, listele de verificare, zonele de deservire, abilitățile, angajații, inventarul, documentele Documente financiare și exportul rapoartelor, precum și programele, turele și concediile.

Întrebare: Pot primi evenimente din Shifton, fără a interoga API-ul? Răspuns: Da, pentru aceasta există webhook-urile — fila Webhooks din secțiunea Developer.

Întrebare: Schimbarea parolei afectează funcționarea integrării? Răspuns: Nu. Integrările funcționează pe bază de cheie API, nu pe baza parolei contului.