API ключове и достъп на външни системи

Страницата "API ключове" е реалният екран, от който управлявате API достъпа на външни системи до вашите данни.

Кога да използвате тази страница

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

Достъп

1. Отворете Интеграции.
2. Изберете "API ключове".

Какво виждате в списъка

• "Име"
• "Изтича на" (или "Никога")
• "Последно използван" — кога външна система е ползвала ключа за последно (или "Никога", ако още не го е ползвала)
• "Активен"
• Действия: "Редактирай API ключ", "Генерирай нов ключ", "Изтрий API ключ"

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

1. Изберете "Нов API ключ".
2. Попълнете "Име" (задължително), "Изтича на" (по избор), "Активен" и "Избери права".
3. Изберете "Създай".
4. Съхранете показания токен и го предайте сигурно на външната система.

Какво означава всяко поле

• "Име" е вашето вътрешно описание на ключа.
• "Изтича на" определя до кога ключът ще работи. Ако полето е празно, ключът няма срок.
• "Активен" включва или спира ключа без да го изтривате.
• "Избери права" определя кои ресурси и действия ще бъдат достъпни през този ключ.

Как работят правата

• Правата се избират поотделно за всеки ключ.
• Ключът има достъп само до ресурсите и действията, за които сте избрали права.
• До всяко право стои кратко описание какво точно позволява.
• Ако достъпът трябва да е по-ограничен, създайте отделен ключ с по-малко права.

Права, които променят календара ви

Три права позволяват на външната система да променя вече създадени часове. До всяко от тях в екрана стои кратко описание — тук са последиците, които не се побират там:

• "Пренасрочва резервации" работи само за единични часове. Групови часове и вече започнали или минали резервации се отказват. Планираните напомняния се преместват към новия час, но клиентът не получава автоматично известие „часът е променен" — в Business приложението това е отделен избор при запис, а през API такъв избор няма.
• "Променя статус на участник (отказ / неявил се)" важи за отделния човек, не за цялата група. Може да зададе всеки статус на бизнеса ви, включително ваш собствен — не само трите от името на правото. При отказ в група освободеното място автоматично промотира клиент от списъка с чакащи.
• "Изтрива резервации" премахва часа от календара напълно.

Внимание

Дайте тези права само на система, на която имате доверие да управлява календара ви. Изтрита резервация не може да бъде върната от Business приложението. За отказ, който остава видим в историята, ползвайте правото за статус на участник вместо изтриване.

Смяната на броя места в групов час не е достъпна през API.

Права за клиентски данни

• "Преглежда списък с клиенти" позволява търсене в целия ви клиентски списък — по телефон, имейл, външен номер или част от име.
• "Преглежда клиент" отваря профила на конкретен клиент.
• "Създава клиент" позволява на външната система да записва нови клиентски профили при вас.
• "Редактира клиент" позволява да променя данните на вече съществуващ профил.

Внимание

"Създава клиент" винаги създава нов профил — външната система не търси съвпадение и не слива с вече съществуващ клиент. Ако интеграцията изпрати един и същ човек два пъти, при вас се появяват два профила. Затова външната система трябва първо да провери дали клиентът вече съществува, най-често по външен номер. Имейлът не е достатъчен признак — един бизнес може да има два профила с един и същ имейл.

Новите клиенти влизат в лимита за клиенти на абонамента ви точно както и създадените ръчно.

Внимание

Правата за резервации също показват клиентски данни. Ключ само с "Преглежда списък с резервации" вижда и клиентите по тези резервации, без да сте му дали клиентските права.

Телефонът и имейлът се показват частично скрити навсякъде. Пълните данни за контакт се отварят само ако дадете и "Преглежда чувствителна информация" от група "Клиенти".

Това е решение за личните данни на вашите клиенти, а не техническа подробност.

Права за абонаменти

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

• "Преглежда издадени абонаменти" показва абонаментите, издадени на клиентите, и какво е останало по тях;
• "Преглежда издаден абонамент" отваря детайлите на конкретен издаден абонамент.

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

Двете права работят само ако бизнесът има включени абонаменти в абонаментния си план. Ако абонаментите не са включени, заявката се отказва вместо да върне празен списък — така разликата между „няма издадени абонаменти" и „нямате абонаменти в плана" остава видима.

През API не могат да се издават, променят или анулират абонаменти.

Известия и портфейл

Действията през API изпращат същите известия към клиента, каквито изпращат същите действия в Business приложението, според вашите настройки за канали и типове известия — включително при изтриване.

Едно изключение: пренасрочването не изпраща автоматично известие „часът е променен" (виж по-горе).

Платените канали (SMS, Viber) теглят от портфейла на бизнеса. При изчерпан баланс каналът се пропуска и известието не тръгва по него.

Как да управлявате вече създаден ключ

• използвайте "Редактирай API ключ", когато трябва да смените име, срок, активност или права;
• изключете "Активен", ако искате временно да спрете достъпа;
• използвайте "Генерирай нов ключ", когато токенът е изгубен или е попаднал при човек, който не трябва да го има;
• използвайте "Изтрий API ключ", ако достъпът вече не е нужен.

Внимание

При ключове, създадени преди въвеждането на отделното право за свободни часове, отметката вече стои сложена. Ако я махнете, външната система спира да получава свободни часове и интеграцията се чупи.

В прозореца на ключа, в секцията "Ключ за достъп", виждате:

• "Завършва на" и последните четири символа на токена — така различавате ключовете си, без токенът да се показва отново;
• "Последно използван" — кога външна система е изпратила заявка с този ключ. Брои се и отказана заявка, например при изключен ключ: и тя показва, че външната система още използва ключа. Стойността се обновява най-много веднъж на 5 минути.

Генериране на нов ключ

Ключът запазва името, правата, активността и срока си — сменя се само токенът. Служителят, който генерира новия ключ, трябва да има правото "Редактиране на API ключ" от група "API ключове".

1. Отворете Интеграции → "API ключове".
2. Изберете "Генерирай нов ключ" от менюто на ключа в списъка или от секцията "Ключ за достъп" в прозореца на ключа.
3. В прозореца "Да се генерира ли нов ключ?" потвърдете с "Генерирай нов ключ".
4. Копирайте новия токен от прозореца "Токен за достъп до API" и го поставете във външната система.
5. Изберете "Разбирам, затвори".

Старият токен спира да работи веднага след потвърждението. Докато не поставите новия във външната система, тя няма достъп до данните ви. Щом външната система започне да ползва новия токен, това се вижда в "Последно използван" — дотогава там стои "Никога".

Съвет

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

Как работи достъпът през API

Тази секция е за човека, който настройва външната система.

• Външната система изпраща токена в HTTP заглавката Authorization във вида Bearer <токен>. Токените започват с rsk_. Друг начин няма — токен в адреса на заявката или в друга заглавка не се приема.
• Достъпът зависи от това ключът да е активен, да не е изтекъл и да има нужните права.
• Освен това бизнесът трябва да има активна функционалност external_connectivity в абонамента си.

Когато ключът не може да се използва, отговорът е 401 с причина:

Съобщение	Какво означава
API key is not active.	ключът е изключен с "Активен"
API key is expired.	датата в "Изтича на" е минала
The access key is unknown or has been replaced.	няма такъв токен: ключът е изтрит, на негово място е генериран нов или токенът е сгрешен
Unauthenticated.	токенът липсва или не е валиден токен на API ключ

Какво е налично в текущия продукт

• JSON:API v2 поддържа достъп с API ключ.
• В публичната v2 спецификация са документирани ресурси като услуги, свободни часове, резервации (преглед, създаване, отказване, пренасрочване и изтриване), клиенти (търсене по телефон, имейл, външен номер или част от име, както и създаване и промяна), издадени абонаменти и абонаментни планове (само преглед), работно време, вноски и плащания.
• При липса на активна функционалност external_connectivity, част от заявките могат да върнат 402 Payment Required.

Критично за сигурността

• След създаване и след "Генерирай нов ключ" системата показва "Токен за достъп до API" в отделен прозорец.
• Този токен се вижда само веднъж. След затваряне не може да бъде показан отново — ако го загубите, генерирайте нов ключ.
• Съхранявайте токена сигурно и не го споделяйте.

Какво не е налично в текущия интерфейс

• "Логове" присъства в менюто, но в текущия интерфейс е неактивно.
• При редакция токенът не се показва. Ако ви трябва, генерирайте нов ключ.
• В Business интерфейса няма отделен екран за webhook настройка.

Свързани теми

• Интеграции и API
• Google календар