Създаване на API ключ

API е врата в задната част на Вашия акаунт. Там, където Вие щракате в панела за управление, друга програма може да мине през тази врата и да вземе данните Ви директно: продуктите, цените, свободните места, продажбите.

Полезно е, когато например искате:

• да показвате на собствения си сайт кои обиколки още имат места тази седмица;
• счетоводителят Ви автоматично да изтегля оборотите;
• да свържете списъка с членове с друга програма.

Този, който изгражда връзката — Вашият уебразработчик, счетоводният Ви софтуер или приятел, който програмира — има нужда от две неща: адреса и ключ. И двете се намират на един-единствен екран.

Добре е да знаете: API е част от по-голям план. При по-малък план API достъп не се появява в менюто Ви; ако все пак попаднете на екрана, виждате обяснение и бутон Към абонамента, а не ключове.

Къде да отидете

От менюто вляво отворете Настройки → API достъп. Само ролята Собственик вижда този екран.

Най-горе има два раздела: Ключове и Webhooks. Тази статия е за първия; уебхуковете са описани в Настройване на webhooks.

В раздела Ключове виждате три блока:

1. Връзката — адресът и техническото описание. Тези две неща предавате на този, който изгражда връзката.
2. Нов ключ — тук създавате ключ.
3. Ключове — какво вече съществува и кога е използвано за последно.

Създаване на ключ

Стъпка 1. Дайте име. Не Вашето име, а името на това, което стои от другата страна: „нашият сайт“, „счетоводство“, „бюлетин“. Името е само за Вас. То ще стои в списъка, до „последно използван“. След година пак ще знаете кой ключ за какво служи — и кой спокойно може да бъде анулиран.

Стъпка 2. Отметнете какво може ключът. Под Какво може този ключ? са правата, на професионален език scopes. Четене вече е отметнато:

Право	Какво може програмата
Четене	Да разглежда каталога, цените, свободните места, отстъпките, ваучерите и годишните карти — а също и поръчките, билетите, сканиранията и купувачите Ви, с тяхното име и имейл адрес.
Запис	Да създава поръчки, да ги плаща, анулира и възстановява, да заявява фактура, да анулира билети и да ги изпраща повторно по имейл, да регистрира влизания, както и да издава, използва или удължава подаръчни ваучери и годишни карти.
Уебхукове	Да настрои да изпращаме известие към Ваш адрес, щом се случи нещо.
Платено външно	Да отбелязва поръчка като платена без доставчик на плащания (банков превод, в брой). Работи само заедно със Запис.

Отмятайте само това, което наистина е нужно. Сайт, който трябва само да показва свободните места, се справя с Четене. Ако този ключ получи и Запис, грешка в сайта може да създаде или възстанови поръчки, които не желаете.

Бъдете особено пестеливи с Платено външно: който има това право, може да издава билети, без да постъпват пари. Давайте го само на каса или счетоводство, които управлявате сами.

Трябва да отметнете поне едно право. Ключ без права не би могъл нищо, а това е най-трудният за откриване вид грешка — затова екранът не го приема.

Стъпка 3 (по избор). Задайте дата на изтичане. Ако оставите полето Изтича на (по избор) празно, ключът работи, докато сами не го анулирате. Ако посочите дата, той работи и през този ден, а след това спира сам. Датата трябва да е в бъдещето. Удобно е, когато временно допускате някого: няма да се налага да мислите за това после.

Стъпка 4 (по избор). Тестов ключ. Отметнете Тестов ключ (пясъчник) за този, който още разработва. Такъв ключ чете същите данни като обикновения. Ако има и Запис, той създава само тестови поръчки: те никога не отиват към доставчика Ви на плащания, не се броят в оборота Ви и се изтриват автоматично след 24 часа. Така печатна грешка не може да предизвика истинско плащане или възстановяване. Тестов ключ не може да настройва уебхукове.

Внимание: докато не бъде изтрита, тестовата поръчка все пак заема истинско място, а имейлът за потвърждение наистина се изпраща. Оставете да се тества с продукт или часови интервал, който създавате специално за това.

Разпознавате тестовия ключ по началото: започва с pv_test_ вместо с pv_live_.

Стъпка 5. Щракнете върху „Създаване на ключ“.

Ключът се вижда само веднъж

Веднага след създаването ключът се появява в рамка. Това е единственият път, в който го виждате.

Копирайте го сега и го предайте веднага. Презаредите ли страницата, той изчезва.

Това не е неудобство, а защита. Ние не пазим ключа Ви: пазим само нещо като негов отпечатък, с който можем да го разпознаем, но не и да го прочетем обратно. Ако някой някога стигне до базата ни данни, това пак няма да му даде достъп до Вашите данни. Обратната страна е, че и ние вече не можем да Ви го покажем.

Изгубили сте го? Няма проблем: създайте нов и анулирайте стария.

Отнасяйте се към ключа като към ключ

Който държи ключа, може това, което е отметнато върху него — без парола и без да отваря акаунта Ви. Затова:

• не го изпращайте в обикновен групов чат, където ще остане видим;
• не го поставяйте във видимия код на сайта си;
• давайте на всяка връзка собствен ключ. Така можете да анулирате един, без да счупите останалите, и виждате в списъка кой още се използва.

Анулиране на ключ

В списъка щракнете върху Анулиране до ключа и потвърдете.

От този момент той вече не работи. Редът остава в списъка с етикета Анулиран: така по-късно винаги можете да проверите коя връзка кога е съществувала.

Анулирайте ключ, когато:

• спирате да използвате инструмента, който го е ползвал;
• сте го изгубили или се търкаля някъде;
• си тръгва човек, който го е имал.

Създаването и анулирането на ключ влизат и в дневника на дейностите на човека, който го е направил (Настройки → Служители, този човек, раздел Активност), с точния час. Самият ключ никога не е там.

Кога е използван за последно?

Под всеки ключ пише кога за последно е извличано нещо с него. Ако от месеци пише „още не е използван“, вероятно вече нищо не е свързано с него. Спокойно го анулирайте — врата, която никой не ползва, няма нужда да стои отворена.

Какво предавате на този, който изгражда връзката

Три неща:

1. API адреса от блока Връзката;
2. техническото описание (връзката, която завършва на openapi.json) — разработчикът вижда веднага всичко възможно;
3. самия ключ и правата, които сте отметнали.

Повече не му е нужно.

А после?

Имате адреса и ключа. Каквото следва, е работа на този, който изгражда връзката — а на него препращате портала за разработчици. Там стои пълният справочник, с примери на код на четири езика и файл, който се внася направо в Postman или Insomnia.

• Какво е API и нужно ли ми е? — ако първо искате да разберете за какво става дума.
• Уебхукове — известете сайта си, че нещо е продадено, без той да пита постоянно.
• Настройване на webhooks — раздел Webhooks на същия този екран, стъпка по стъпка.