API rakto kūrimas ir teisių valdymas

Ką atliksite

API raktas yra slaptas prisijungimo duomuo, kuriuo išorinė sistema patvirtina savo prieigą prie „Hanna“. Kiekvienai integracijai naudokite atskirą, aiškiai pavadintą raktą ir suteikite tik reikalingas teises.

Prieš pradedant

Reikalinga administratoriaus arba darbuotojui suteikta API ir MCP prieiga. Suteikite tik konkrečiai integracijai reikalingas teises ir nenaudokite asmeninių raktų bendroms įmonės integracijoms.

Kaip sukurti raktą

1. Atidarykite Sistemos nustatymai → API ir MCP.
2. Paspauskite Naujas įrašas.
3. Įrašykite pavadinimą, pagal kurį vėliau atpažinsite integraciją.
4. Pasirinkite Asmeninis arba Sisteminis.
5. Pažymėkite reikalingas teises.
6. Paspauskite Išsaugoti.
7. Iškart nukopijuokite parodytą raktą į saugią paslapčių saugyklą.

Visas raktas parodomas tik vieną kartą. Uždarius langą jo dar kartą peržiūrėti negalėsite.

Ką reiškia bendrosios teisės

• Skaitymas leidžia gauti ir ieškoti duomenų. Ši teisė yra privaloma.
• Rašymas leidžia kurti ir redaguoti įrašus.
• Trynimas leidžia trinti API dokumentacijoje nurodytus įrašus.

Jei integracija tik skaito duomenis, rašymo ir trynimo teisių nesuteikite.

Asmeninis raktas

Asmeninis raktas veikia kaip jį sukūręs darbuotojas. Integracija mato ir gali keisti tik tai, ką darbuotojui leidžia jo rolė, individualios teisės bei laukų nustatymai.

Šį tipą patogu naudoti asmeniniam įrankiui arba procesui, kuris turi veikti konkretaus darbuotojo vardu. Darbuotoją išjungus ar pakeitus jo teises, integracijos galimybės taip pat gali pasikeisti.

Sisteminis raktas

Sisteminis raktas skirtas bendrai įmonės integracijai, kurios veikimas neturi priklausyti nuo vieno darbuotojo paskyros. Jį kuria administratorius.

Pasirinkus sisteminį raktą pateikiama modulių matrica. Kiekvienam moduliui atskirai galima leisti:

• peržiūrėti;
• sukurti;
• redaguoti;
• ištrinti.

Ne visi moduliai turi visus veiksmus. Pažymėkite tik tas eilutes, kurių reikia konkrečiai integracijai.

Kaip naudoti raktą

API užklausoje raktas perduodamas Authorization antraštėje:

Authorization: Bearer {jūsų-raktas}

Nerašykite rakto į URL, viešą kodo saugyklą, užduoties komentarą ar naudotojo vadovą. Jei raktas galėjo būti paviešintas, sukurkite pakaitinį ir senąjį atšaukite.

Rakto pakeitimas ir atšaukimas

Rakto veiksmai pasiekiami API ir MCP sąraše.

Pasirinkus Pakeisti, sukuriamas pakaitinis raktas. Senasis dar veikia, todėl galite pirmiausia atnaujinti integraciją ir patikrinti naują raktą. Kai naujasis veikia, senąjį atšaukite.

Pasirinkus Atšaukti, raktas iškart nustoja veikti. Prieš tai patikrinkite, kuri sistema jį naudoja.

Sąraše taip pat matysite galiojimo pabaigą ir paskutinį naudojimą. Tai padeda pastebėti nebenaudojamus arba laiku nepakeistus raktus.

Jei užklausa neveikia

• 401 dažniausiai reiškia neteisingą, pasibaigusį arba atšauktą raktą.
• 403 reiškia, kad raktas atpažintas, tačiau trūksta bendrosios arba modulio teisės.
• 422 nurodo netinkamus ar trūkstamus duomenis.
• 429 reiškia, kad per trumpą laiką išsiųsta per daug užklausų.

Tikslius laukus ir operacijas tikrinkite per puslapio viršuje esančią nuorodą API Dokumentacija.

Jei patikrinus dokumentaciją ir teises užklausa vis tiek neveikia, Hanna klientų aptarnavimo komandai nurodykite savo įmonės Hanna adresą, HTTP metodą, API kelią, atsakymo būsenos kodą, bandymo laiką su laiko juosta ir nuasmenintą atsakymo tekstą. Nesiųskite API rakto ar Authorization antraštės.

Susiję straipsniai

• API ir MCP nustatymai bei dokumentacija
• MCP prijungimas ir prieigos valdymas