Dokumentasyon ng API

Ang Shifton Mga Gawain ay nagbibigay-daan na i-automate ang trabaho sa platform at ikonekta ito sa mga panlabas na serbisyo sa pamamagitan ng bukas na API. Sa pamamagitan ng API ay available ang lahat ng mahahalagang entidad — mga gawain, mga kliyente, mga empleyado, mga checklist, imbentaryo, mga sona ng serbisyo, mga dokumentong Mga dokumentong pinansyal at mga ulat — kaya ang Shifton ay maaaring iugnay sa inyong mga sistemang HR, kalkulasyon ng sahod at pagsusuri, at gayundin sa mga panloob na serbisyo ng kumpanya.

Ang dokumentasyon ay nailathala sa dalawang bersyon:

🚀 Bagong dokumentasyon — ang kasalukuyang bersyon ng sanggunian na may na-update na istruktura at pinakabagong mga method: 👉 https://api2.shifton.com/openapi/
📄 Lumang dokumentasyon — ang nakaraang bersyon (patuloy pa ring suportado para sa umiiral na mga integrasyon): 👉 https://api2.shifton.com/docs/

Maaaring buksan ang dalawang bersyon nang direkta mula sa app — sa seksyong Developer, sa tab na Pangkalahatang-ideya, sa pamamagitan ng mga pindutang “Bagong dokumentasyon” at “Lumang dokumentasyon”.

Ang dokumentasyon ay available sa dalawang wika. Sa kanang itaas na sulok ng pahina ng bagong dokumentasyon ay may switch na EN / RU — ang napiling wika ay naaalala.

Paano makakuha ng API key

Ang API key ay ginagawa sa app mismo:

Buksan ang seksyong Developer.
Pumunta sa tab na Mga API key (“Mga API key”).
I-click ang “Gumawa ng API key”.

Ano ang pupunan sa paggawa ng key

Bubukas ang side panel na Gumawa ng API key na may mga field:

Pamagat — ang pangalan ng key, obligadong field. Pangalanan ayon sa layunin, upang malinaw sa bandang huli kung ano ang i-o-off: “Pag-export sa 1C”, “Mga ulat para sa pagsusuri”.
Mag-e-expire sa — ang petsa, pagkatapos nito ang key ay titigil na sa paggana. Kung iiwang walang laman ang field, ang bisa ay walang limitasyon.
Pag-access — ang laki ng mga karapatan ng key:
Full access (act as me) — ang key ay gumagana sa inyong pangalan at may inyong mga karapatan.
Mga pinaghigpitang pahintulot — limitadong set ng mga pahintulot na kayo mismo ang pumipili.

I-click ang Idagdag upang gawin ang key, o ang Kanselahin upang isara ang panel.

📷 *Screenshot ng panel ng paggawa ng key — kunin sa prod*

Ang key ay ginagawa para sa partikular na kumpanya at gumagana lamang sa datos nito. Maaaring bawiin ang key anumang oras — ang pagbawi ay agad na nagkakabisa, at ang lahat ng sumusunod na request na may key na ito ay magbabalik ng error na 401.

Mahalaga: ang nagawang key ay ipinapakita isang beses lamang. Kopyahin ito agad at iimbak sa maaasahang lugar — hindi na ito makukuha muli. Kung nawala ang key, gumawa ng bago, at bawiin ang luma.

Awtorisasyon

Ang lahat ng request sa API ay pinipirmahan ng key sa header:

Authorization: Bearer {your_API_key}

Ang base address ng API:

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

Ang request na walang balidong key ay nagbabalik ng 401 at ng body na {"message":"Unauthenticated."}.

Unang request

Halimbawa, upang makuha ang listahan ng mga empleyado ng kumpanya (ipasok ang inyong ID ng kumpanya sa halip na {companyId}):

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

Ang parehong bagay sa pamamagitan ng curl:

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

Ang ID ng kumpanya ay nakikita sa address bar ng app: app.shifton.com/c/8397/... — ang numero pagkatapos ng /c/.

Ano ang available sa pamamagitan ng API

Ang sanggunian ay sumasaklaw sa mahigit 360 method. Ang mga pangunahing seksyon para sa field service:

Mga Gawain — /companies/{companyId}/tasks: paggawa, pagbabago, mga katayuan, mga file ng gawain.
Listahan ng gagawin (To Do) — /companies/{companyId}/todo.
Mga Kliyente — /companies/{companyId}/clients, at gayundin ang mga address at mga custom na field ng mga kliyente.
Mga checklist — /companies/{companyId}/checklists.
Mga sona ng serbisyo — /companies/{companyId}/tasks/service-areas.
Mga Kasanayan — /companies/{companyId}/skills.
Mga Empleyado — /companies/{companyId}/employees: pagdagdag, pag-edit, pagtanggal sa trabaho at pagbabalik.
Imbentaryo — mga item, kategorya, set at natitira sa mga bodega.
Mga dokumentong pinansyal — mga estimate, order ng trabaho, invoice, resibo, mga counter ng dokumento at logo.
Mga Ulat — pag-export ng datos tungkol sa trabaho at pagdalo.

Bukod pa rito, available ang mga iskedyul at shift, mga bakasyon at request para sa day off, pagdalo, billing at SMS-billing, mga abiso at mga module.

Mga webhook

Kung sa halip na regular na mga request sa API ay kailangan ninyong makatanggap ng mga event sa sandaling ito ay mangyari, gamitin ang mga webhook — ang tab na Webhooks sa seksyong Developer. Ang Shifton mismo ay magpapadala ng request sa inyong address kapag naganap ang kinakailangang event; ang listahan ng mga suportadong event ay ibinabalik ng hiwalay na method.

Mga code ng error

Ang API ng Shifton ay gumagamit ng standard na mga status code ng HTTP:

200 — ang request ay naisagawa nang matagumpay.
201 — ang object ay matagumpay na nagawa.
400 — mali ang mga parametro ng request.
401 — error ng awtorisasyon: ang key ay hindi naipasa, hindi balido o nabawi na.
403 — ipinagbabawal ang access.
404 — hindi natagpuan ang resource (kadalasan ay may typo sa address ng method).
500 — error ng server.

Mga tip sa paggamit

Para sa mga bagong integrasyon ay gamitin ang bagong dokumentasyon — ang luma ay iniwan para sa mga integrasyong gumagana na.
Para sa pagsuri ng mga request ay maginhawa ang Postman o curl — nagbibigay-daan silang makita ang sagot nang hindi sumusulat ng kahit isang linya ng code.
Huwag iimbak ang key sa bukas na anyo sa code at huwag ipasa ito sa mga third party: ang key ay nagbibigay ng access sa datos ng kumpanya.
Sundin ang mga limitasyon sa dalas ng mga request (rate limits) — ang paglampas dito ay maaaring magdulot ng pansamantalang pagharang sa access sa API.

Mga Madalas Itanong

Tanong: Saan makukuha ang API key? Sagot: Sa app: ang seksyong Developer → ang tab na Mga API key → ang pindutang “Gumawa ng API key”. Ang key ay ibinibigay para sa kasalukuyang kumpanya.

Tanong: Isinara ko ang window at hindi ko nakopya ang key. Saan ito matitingnan? Sagot: Wala — ang key ay ipinapakita isang beses lamang at hindi na ibinibigay muli. Gumawa ng bagong key, at bawiin ang luma.

Tanong: Paano bawiin ang key kung napunta ito sa maling kamay? Sagot: Tanggalin ito sa tab na Mga API key. Ang pagbawi ay agad na nagkakabisa: ang lahat ng request na may key na ito ay agad na magsisimulang magbalik ng 401.

Tanong: Ano ang pagkakaiba ng “Full access” at “Restricted permissions”? Sagot: Ang Full access (act as me) ay nagbibigay sa key ng parehong mga karapatan na mayroon kayo. Ang Mga pinaghigpitang pahintulot ay nagbibigay-daan na ibigay sa key ang napiling set lamang ng mga pahintulot — mas ligtas ito para sa integrasyong nangangailangan ng access sa bahagi lamang ng datos.

Tanong: Maaari bang limitahan ang bisa ng key? Sagot: Oo, ang field na Mag-e-expire sa sa paggawa. Kung hindi ito pupunan, ang key ay walang hangganan.

Tanong: Gumagana ba ang isang key para sa ilang kumpanya? Sagot: Hindi. Ang key ay nakakabit sa kumpanyang kung saan ito ginawa, at gumagana lamang sa datos nito. Para sa ibang kumpanya ay gumawa ng hiwalay na key.

Tanong: Ano ang base address ng API? Sagot: https://api2.shifton.com/work/1.0.0. Pagkatapos ay ang path ng method, halimbawa /companies/{companyId}/tasks.

Tanong: Saan makukuha ang ID ng kumpanya para sa mga request? Sagot: Nasa address bar ito ng app agad pagkatapos ng /c/ — halimbawa, sa app.shifton.com/c/8397/tasks ang identifier ng kumpanya ay 8397.

Tanong: Anong bersyon ng dokumentasyon ang gagamitin? Sagot: Para sa mga bagong integrasyon — ang bago (api2.shifton.com/openapi). Ang luma (api2.shifton.com/docs) ay suportado para sa umiiral na mga integrasyon.

Tanong: May dokumentasyon ba sa wikang Ruso? Sagot: Oo. Sa pahina ng bagong dokumentasyon sa kanang itaas na sulok ay may switch na EN / RU.

Tanong: Ano ang gagamitin sa pagsubok ng mga request sa API? Sagot: Pinakamaginhawa ang Postman o curl — nagbibigay-daan silang magpadala ng mga request at tingnan ang mga sagot nang hindi sumusulat ng code.

Tanong: Bakit dumarating ang 401, kahit nakopya ko ang key? Sagot: Suriin na ang key ay naipapasa sa header na Authorization na may salitang Bearer sa harap nito, na ang key ay hindi nabawi at hindi nag-expire ang bisa nito.

Tanong: Bakit dumarating ang 404? Sagot: Kadalasan ay napagpalit ang address: ang base na bahagi ay dapat na https://api2.shifton.com/work/1.0.0, at sa path ng method — ang tamang {companyId}.

Tanong: Ano ang maaaring i-automate sa pamamagitan ng API? Sagot: Ang paggawa at pagbabago ng mga gawain, ang trabaho sa mga kliyente at sa kanilang mga address, mga checklist, mga sona ng serbisyo, mga kasanayan, mga empleyado, imbentaryo, mga dokumentong Mga dokumentong pinansyal at ang pag-export ng mga ulat, at gayundin ang mga iskedyul, shift at bakasyon.

Tanong: Maaari bang makatanggap ng mga event mula sa Shifton, at hindi mag-poll sa API? Sagot: Oo, para dito ay may mga webhook — ang tab na Webhooks sa seksyong Developer.

Tanong: Nakakaapekto ba ang pagpalit ng password sa paggana ng integrasyon? Sagot: Hindi. Ang mga integrasyon ay gumagana ayon sa API key, at hindi ayon sa password ng account.