У процесі реалізації проєкту по Zoho CRM часто виникає задача інтегрувати CRM з іншими сервісами клієнта. Найчастіше це сайт, але також можуть бути й інші сервіси — наприклад, LMS-система чи внутрішні інструменти. Частиною роботи CRM-аналітика є написання технічного завдання (ТЗ) для розробників, а також обов’язкове тестування описаних у ТЗ API-запитів. Щоб мати змогу виконати хоча б один запит до Zoho API, спершу потрібно створити Server-based Applications токен — про це й піде мова в цій статті.
Різниця між Self Client і Server-based Applications
В Zoho є 5 різних типів додатків, але за свою роботу я використовував тільки два, тому про них і буде мова
Часто так буває, що приходиш на проєкт і можна побачити використання Self Client додатку, але якщо ви робите інтеграцію з сайтом, або даєте цей token авторизації підряднику, то це хибна практика і ось чому.
Self Client – більш простий з точки зору підключення, не потрібно створювати OAuth авторизацію і слугує більше для швидкого тестування гіпотез. І ще важливо знати, що його можна створити тільки один.
Server-based Applications – використовується повноцінна OAuth-авторизація, можна створювати під різні інтеграції, легко видалити.
А тепер на реальному прикладі. У вас є підрядник по сайту, з якими ви робите інтеграцію. Ви описали ТЗ, згенерували token і віддали йому. Але з часом ви закінчили співпрацю з ним і для безпеки хочете змінити token авторизації. У випадку з Server-based Applications вам достатньо згенерувати новий token і передати новому підряднику. У випадку Self Client вам потрібно зрозуміти, які ще сервіси висять на цій інтеграції і генерація нового token може привести до неочікуваних наслідків.
Я собі запамʼятав, що гарна практика:
- це створювати Server-based Applications під кожну окрему інтеграцію і називати його відповідно, щоб з часом було зрозуміло, до чого цей token.
- Уникати назв Сайт 1, Сайт New, Сайт 2.0 і так далі – Назва повинна бути унікальна для одного сервісу. Якщо ви згенерували новий токен, видаліть старий, вам же буде легше в майбутньому
Важливо звертати увагу на домен вашого Zoho EU/COM
В генерації додатку і у використанні API в цілому важливо завжди перевіряти, чи правильний домен ви використовуєте для запитів. В залежності від того, як ви або ваш клієнт реєстрував Zoho, в нього може бути https://crm.zoho.eu/ або https://crm.zoho.com/.
Нижче я буду про це ще згадувати, але важливо завжди памʼятати, тому що у вас просто запити будуть видавати помилку і інколи можна годину провести перш ніж зрозумієш, що ти просто вказав не той домен. Будьте уважні 🙂
Тепер переходимо до покрокової інструкції зі створення і використання Server-based Applications token
Покрокова інструкція із створення Server-based Applications токену
Щоб створити додаток, вам необхідно перейти за посиланням https://api-console.zoho.eu/ і натиснути Get Started і обираємо
Server-based Applications
Далі необхідно заповнити дані:
Client Name – Назва інтеграції. Як описував вище, краще називати логічно, щоб потім було легко зрозуміти, що це за інтеграція
Homepage URL – Я використовую просто “https://www.google.com/“. Але ви можете додавати сайт клієнта наприклад. Це не принципово.
Authorized Redirect URIs – так само, як і в Homepage
Після цього, Zoho попросить вас авторизуватись і після цього ми отримаємо Client ID і Client Secret. Можете їх одразу збрегети, вони нам знадобляться в подальшому для роботи.
Використання Postman для генерації токену
Для своєї зручності я зробив Postman колекцію, тому далі буду показувати на прикладі її використання, але якщо вам дуже не хочеться, то використовувати Postman не обовʼязково.
Ділюсь з вами своєю колекцією за посиланням. Щоб скористатись колекцією, потрібно натиснути в Postman імпорт і вставити туди це посилання.
Створення authorization_code
Першим етапом, нам потрібно сформувати url для отримання authorization_code. У Postman колекції він вже сформований, вам потрібно лише підставити свої дані.
https://accounts.zoho.eu/oauth/v2/auth?response_type=code&client_id=client_id_put_here&scope=ZohoCRM.modules.ALL&redirect_uri=https://www.google.com/&access_type=offline&prompt=consentresponse_type = code
client_id = Client ID з вашого додатку Zoho
scope = ZohoCRM.modules.ALL (Це дає доступ до всіх модулів Zoho CRM)
redirect_uri = https://www.google.com/ (Бажано використовувати такий самий, як і при створенні додадтку)
access_type = offline
prompt = consent
Не забуваємо слідкувати за доменом, на якому у вас створений Zoho. Якщо ви використовуєте Postman, то вам достатньо тільки замінити свій Client ID і посилання готове
Після створення посилання, вам необхідно вставити його в браузері і надати всі дозволи, які просить Zoho. Після надання всіх доступів, у вас відкриється сайт, який ви вказували в redirect url (в мене це google) і в рядку браузера ви зможете забрати ваш згенерований code
ВАЖЛИВО! Цей код має дуже маленький час життя, тому спочатку вам треба підготувати наступний запит, а потім зробити повторно цей запит на authorization_code
Створення refresh_token
Створення refresh_token схоже і ти можеш знову використати Postman, але на цей раз нам вже не потрібно вставляти нічого в браузер і ми будемо робити запит в самому Postman
https://accounts.zoho.eu/oauth/v2/token?client_id=client_id_put_here&redirect_uri=https://www.google.com/&grant_type=authorization_code&client_secret=client_secret_put_here&code=authorization_code_put_hereТут працює така ж логіка, як і в першому запиті. Code з попереднього запиту треба вставляти в параметр code
Після того, як ви вставили всі дані і наново згенерували code з першого етапу, потрібно в Postman натиснути Send. У відповідь ви отримаєте refresh_token, які вже нам потрібен для останнього етапу.
Створення access_token
Для всіх подальших запитів нам буде потрібен access_token. Він має 3600 секунд життя і його час від часу доводиться генерувати знову, але refresh_token вже залишається не змінним.
https://accounts.zoho.eu/oauth/v2/token?client_id=client_id_put_here&client_secret=client_secret_put_here&refresh_token=refresh_token_put_here&grant_type=refresh_tokenЯк ти можеш побачити, логіка така ж сама, потрібно вставити Client ID, Client Secret і refresh_token з попереднього запиту і ми отримаємо у відповідь access_token, який можемо використовувати у запитах API
Нарешті, ми згенерували все що треба і тепер можемо описувати ТЗ для розробника і тестувати наші запити.
Методи API ти можеш знайти за посиланням https://www.zoho.com/crm/developer/docs/api/, використовуй свіжі версії API
Бонус! Приклад запиту на створення Контакту
Не міг вас відпустити без прикладу реального використання, тому ловіть приклад створення контакту в Zoho CRM.
Знаходимо в API документації метод для створення записів https://www.zoho.com/crm/developer/docs/api/v8/insert-records.html
Беремо url з прикладу і підставляємо необхідний модуль https://www.zohoapis.eu/crm/v8/Contacts і обовʼязково перевіряємо домен, тому що в API документації можуть бути приклади з .com доменом і у вас це просто не спрацює.
Далі створюємо в Postman новий запит і вказуємо всі необхідні дані. Для створення записів потрібно використовувати POST метод і звісно не забуваємо про токен авторизації. Також, в запиті нам необхідно передати тіло запиту, тобто поля для контакту (Імʼя, телефон, пошту і т.д.)
Приклад body
{
"data": [
{
"Company": "Zoho Company",
"Last_Name": "Analyst",
"First_Name": "Zoho",
"Email": "zohoanalyst@test.com",
"Phone":"+380672343434"
}
],
"trigger": [
"approval",
"workflow",
"blueprint"
]
}
Не забуваємо про Header
Якщо все успішно, то отримаємо у відповідь SUCCESS
Підсумки
Описав для вас покрокову інструкцію, навіть трохи намагався пояснити що і до чого. Звісно я не розказав все ідеально, але коли я перший раз зустрівся з задачею, що мені потрібно було зробити ТЗ і протестувати API виклики, то було щось страшне. Тому сподіваюсь, що ти знайшов цю статтю і я трохи полегшив тобі життя.
P.S. Якщо зʼявилось більше запитань, ніж відповідей, пиши мені в телеграм.
