Marejeo ya API
Violesura kwa wasanidi programu: njia za umma, wijeti ya mazungumzo, kuingia na REST-API na funguo za API.
API Reference inaelezea violesura vya Zentor App ambavyo mnaweza kuvifikia kutoka tovuti na programu zenu wenyewe: njia za umma za fomu, kiunda bidhaa na maudhui, wijeti ya mazungumzo, chatbot ya demo pamoja na kuingia ikiwemo kuingia mara moja. Kila ukurasa wa njia unaonyesha mbinu, njia, uthibitishaji, vigezo, mfano wa ombi na jibu na misimbo ya makosa iliyoandikwa.
Uthibitishaji: njia za fomu, kiunda bidhaa na maudhui zinafikika bila kuingia. Njia za wijeti ya mazungumzo zinatarajia tokeni ya kupachika ya wijeti yenu katika header `X-Widget-Token` na hukubali tu maombi kutoka vikoa vilivyoidhinishwa vya wijeti. Njia za kuingia hutoa tokeni ya ufikiaji (JWT) na tokeni ya uhuishaji kwa vipindi vya watumiaji.
Ufikiaji wa API kwa funguo ya API: kwa programu zenu wenyewe na miunganisho ya seva-kwa-seva, REST-API inapatikana kwenye URL ya msingi `https://zentor-app.de/api/v1`. Zentor huwezesha ufikiaji wa API kwa ombi kwa akaunti yenu. Baadaye wasimamizi huunda kwenye dashibodi chini ya „Funguo za API“ funguo zao na kuamua ruhusa zao (scopes) – kwa miadi na uhifadhi wa nafasi, chatbot, mawasiliano, faili, hifadhidata ya maarifa, ripoti na data ya wavuti. Kwa kila eneo kuna scope ya kusoma (`<eneo>.read`, GET pekee) na scope ya kuandika (`<eneo>.write`, inajumuisha kusoma), kwa mfano `appointments.read` au `knowledge.write`. Tumeni funguo katika header `Authorization: Bearer <funguo ya API>` au vinginevyo katika header `X-API-Key`. Kwa `GET /api/v1/me` mnakagua funguo imehusishwa na akaunti gani na scopes zipi.
Funguo kamili inaonyeshwa mara moja tu wakati wa kuunda. Ihifadhi kwa usalama na upande wa seva pekee, kamwe si katika msimbo wa kivinjari au programu za simu. Funguo zinaweza kupewa tarehe ya mwisho, kuzungushwa na kufutwa. Kupitia REST-API vipengele vinavyofikika ni vile vilivyojumuishwa katika kifurushi chenu pekee, na data zote zinabaki ndani ya mipaka ya akaunti yenu. Makosa ya kawaida: 401 `API_KEY_INVALID`, `API_KEY_EXPIRED` au `API_KEY_REVOKED` (funguo haipo, si sahihi, imeisha muda au imefutwa), 403 `API_ACCESS_NOT_ENABLED` (ufikiaji wa API kwa akaunti haujawezeshwa), 403 `API_SCOPE_MISSING` (funguo haina scope inayohitajika), 403 `TENANT_NOT_ACTIVE` au `TENANT_LOCKED` (akaunti haifanyi kazi au imefungwa) na 404 `API_ENDPOINT_NOT_AVAILABLE` (njia hii haipatikani kupitia REST-API).
Majibu na vikomo: njia zote hujibu kwa JSON. Jibu lililofanikiwa lina hali ya 2xx na `"ok": true`; jibu la kosa lina msimbo wa kosa unaosomeka na mashine (katika sehemu `error` au `error.code`) na ujumbe. Kwa kila anwani ya IP, maombi 2,000 ndani ya dakika 15 yanawezekana; kwa njia za fomu, uthibitisho na kuingia, vikomo vikali zaidi vinatumika, vinavyotajwa kwenye ukurasa husika. Vikizidishwa, seva hujibu kwa 429 `RATE_LIMIT_EXCEEDED`. Njia zilizowekwa alama kama si idempotent hazipaswi kurudiwa kiotomatiki baada ya kukatika kwa muunganisho, kwani vinginevyo maombi au ujumbe maradufu vinaweza kutokea.
Tumeni nywila, tokeni, funguo za API na misimbo ya uthibitisho tu katika mwili wa ombi au katika header kupitia HTTPS – si katika URL, kumbukumbu au maombi ya usaidizi.