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 ключ", ако достъпът вече не е нужен.

Внимание

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

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

• Външната система използва токена като Authorization: Bearer <api-key>.
• Достъпът зависи от това ключът да е активен, да не е изтекъл и да има нужните права.
• Освен това бизнесът трябва да има активна функционалност external_connectivity в абонамента си.

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

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

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

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

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

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

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

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