Використання REST API Bitrix24

Зміст

Загальний порядок роботи з OAuth при створенні програм для Бітрікс24

Реєструється свій додаток у Маркетплейсі Бітрікс24
Запитуються з віддаленого сервера ключі
Сервер перенаправляє браузер на зареєстрований програмою URL
Обробляється відповідь
Підписуються отриманим ключем усі запити до Rest API.

Реєстрація програми в Маркетплейс Бітрікс24

З 25 травня 2015р. щоб додавати свої програми на портал більше не потрібно ставати технологічним партнером.

Якщо у вас є права адміністратора на вашому порталі, зайдіть у розділ Програми — Додати програму. Вибрати для особистого користування (у цьому випадку ніхто крім вас та вашого порталу не зможе використовувати цю програму)

Відкриється форма додавання програми

У формі заповнюємо:

Назва програми - довільна.
Додаток використовує лише API – обов'язково
Права доступу — Вказуємо до яких розділів буде доступ у цієї програми
Вкажіть посилання — вказуємо довільний сайт (або будь-яку довільну сторінку).

Після цього натискаємо «Зберегти»

Desktop додаток має слухати будь-який порт на localhost (Oktell зазвичай слухає порт 4055).

Після отримання даних браузер більше не потрібен. Дані, які були отримані в результаті створення програми і отриманий code, необхідно внести в таблицю oktell.dbo.bitrix_oauth у відповідні поля. Скрипт для створення таблиці наведено наприкінці статті

У відповідь сервер поверне json-структуру з усіма необхідними здійснення запитів до сервера даними.

Все, додаток може здійснюватизапити до REST-сервісу.

4)При досягненні періоду життя at необхідно надіслати запит на отримання нового at на наступного виду:

В результаті виконання цього запиту буде повернуто json-структуру виду:

access_token, який зберігається в БД оновлюється щогодини, щоб була можливість безперервно виконувати будь-які запити до Bitrix24.

Приклад сценарію, який надсилає запит на отримання access_token, після отримання code та оновлює access_token за існуючим refresh_token:

Приклад використання REST API

Розглянемо приклад отримання списку всіх лідів. Для цього нам знадобляться 2 методи:

Сценарій «bitrix_crm_lead_list»

0) Виводимо повідомлення про Запуск сценарію та Отримуємо поточну дату та час для того, щоб відобразити час виконання сценарію. Дату та час отримуємо з функції «Поточна дата та час». 1)У цьому сценарії, як і в будь-якому іншому, зручно використовувати існуючий, автоматично оновлюваний access_token, який ми отримали в попередньому розділі. Отримуємо дані з таблиці oktell.dbo.bitrix_oauth для виконання запиту REST. Текст запиту, що виконується -

2) Встановлюємо лічильник для отримання списку лідів = 0 та лічильник останньої ітерації = 0 та лічильник ітерацій отримання лідів = 0

3)Отримуємо перші N лідів, у другій ітерації слід N лідів, кількість N отримуємо після виконання 1-го запиту і в кожному наступному, так само після першого запиту отримаємо скільки всього лідів. У прикладі: 'https://'+[domain]+'/rest/crm.lead.list?start='+[counter_lead_start]+'&auth='+[access_token]

4) Отримуємо скільки всього лідів. Використовується компонент парсера з алгоритмом «Парсер JSON». У прикладі: пошуковий запит -total

Важливо! Усі компоненти парсер у цьому сценарії використовують алгоритм «Парсер JSON».

5) Записуємо в лічильник отримання лідів початковий номер для наступної ітерації. У прикладі: пошуковий запит -next

5.1) Якщо парсер JSON виконався з помилкою, це означає, що лічильник для наступної ітерації відсутній, що свідчить про останню ітерацію, тоді додатково визначаємо лічильник останньої ітерації і встановлюємо для останньої ітерації лічильник отримання лідів = скільки всього лідів (total)

6) Встановлюємо лічильник для отримання N-го ліда парсером (як правило лічильник буде бігати від 0 до 49).

7) Отримуємо N-ий лід для подальшого парсингу (Парсер JSON). У прикладі: пошуковий запит-вираз - '"result"/'+[counter_lead_parse]

Важливо! У компонентів парсера завжди повинні бути призначені переходи по гілці «Помилка», т.к. Якщо даних у цьому полі не буде парсер відпрацює саме по цьому переходу і якщо він не вказаний, то сценарій завершиться.

8) Оновлюємо лід у таблиці - [oktell]. [dbo]. [bitrix_leads] якщо він там є і додаємо якщо ні, визначення відбувається за sql_ID (по № ліду). Текст запиту, що виконується -

8.1)Якщо sql запит додавання\оновлення ліда виконався з помилкою, то Записуємо інформацію про помилку в таблицю [oktell].[dbo].[bitrix_import_lead_error]

Текст запиту, що виконується -

9) Збільшуємо лічильник для отримання N-го ліду на 1 (+1)

10) Після цього відбувається перевірка Лічильник отримання N-го ліду менше, ніж Лічильник кількості отриманих лідів у веб-запиті? Текст виразу - [Лічильник ітерацій отримання списку лідів]*50+num([counter_lead_parse]) У виразі використовуємо коефіцієнт у вигляді лічильника ітерацій отриманнясписку лідів, щоб коректно проходити по всіх лідах, які отримали в результаті web-запиту. Наприклад за першої ітерації пройдемо по 0*50+[0..49] лідам, за другий по 1*50+[0..49], тобто. з 50 до 99 лід тощо.

11) Збільшуємо Лічильник ітерації отримання списку лідів +1

12) Перевіряємо Лічильник останньої ітерації = 1?

13) Відображаємо повідомлення про завершення сценарію з часом виконання. Текст повідомлення - вираз -

14) Оновлюємо дані по завершенню сценарію в таблиці oktell.dbo.bitrix_lead_runtime Текст запиту, що виконується -

15) Запуск сценарію bitrix_crm_lead_get_by_id, в якому ми оновимо контакти лідів, при першому запуску будуть отримані всі контакти, при подальших запусках тільки контакти у лідів, які були оновлені після виконання даного сценарію.

Сценарій «bitrix_crm_lead_get_by_id»

У цьому сценарії послідовно оброблятиметься кожен № ліда, т.к. це могло б зайняти досить багато часу, перевірятимемо лише ті ліди, які були змінені після попереднього запуску даного сценарію (якщо він запускається вперше, то отримаємо дані по всіх лідах). Дату запуску отримуємо із таблиці [oktell]. [dbo].[bitrix_lead_runtime]

0) Виводимо повідомлення про Запуск сценарію та Отримуємо поточну дату та час для відображення часу виконання сценарію. Дату та час отримуємо з функції «Поточна дата та час».

1) Отримуємо дані з таблиці oktell.dbo.bitrix_oauth для виконання запиту REST Текст запиту -

client_id - id програми, який було отримано раніше, у цьому запиті вказується як рядка.

2) Привласнюємо лічильнику для перебору лідів негативнеЗначення, необхідно для отримання першого ліда.

3) SQL-запит. Отримання N-го ліда. Отримуємо № ліда (ID)

4)sql_result>0? - в результаті виконання запиту знайшовся хоча б один лід?

5) Виконуємо web-запит і отримуємо інформацію по N-му ліду передаючи його ID

Текст запиту - вираз виду - 'https://'+[domain]+'/rest/crm.lead.get?id='+[sql_ID]+'&auth='+[access_token]

6) Отримуємо «Вибране рішення» лідом (опціонально, можна прибрати цей компонент)

Текст запиту - вираз виду - '"result"/"UF_CRM_1387525788"/'+str([i])

7) Додаємо обране клієнтом рішення в таблицю - oktell.dbo.bitrix_lead_solution (опційно, можна прибрати цей компонент) Текст запиту -

8) Встановлюємо Лічильник i = 0, він необхідний для того, щоб з JSON структури ми могли отримати довільну кількість e-mail на наступному ланцюжку кроків.

9) Підраховуємо кількість e-mail у ліда. Компонент Парсер. Текст запиту - вираз виду - "result"/"EMAIL"

10) Отримуємо перший e-mail і виконуємо серію компонентів Парсер JSON, для отримання кожного з них. Отримуємо структуру виду:

11)Кожен з них додаємо до таблиці oktell.dbo.bitrix_lead_contacts Текст запиту -

12) Збільшуємо лічильник i = i +1

13) Перевіряємо i 13.1) Якщо так, то йдемо на крок 10) 13.2) Якщо ні, то йдемо на крок 14)

17)Кожен з них додаємо до таблиці oktell.dbo.bitrix_lead_contacts Текст запиту -

18) Збільшуємо лічильник i = i +1

19) Перевіряємо i 19.1) Якщо так, то йдемо на крок 16) 19.2) Якщо ні, то йдемо на крок 20)

20) Привласнюємо лічильник перебору лідів = поточному ID ліда, для пошуку рядково і переходимо на крок 3) і так до тих пір, поки невідпрацює умову 4.2)

Створення службових завдань

Після того, як всі сценарії були налаштовані, можна створити службові завдання для автоматизації процесу отримання нових refresh_token, access_token, та інформації з Bitrix24. Виходячи з опису REST API слід, що access_token необхідно отримувати кожні 3600с, в той час як refresh_token активний протягом 1 місяця. У цьому прикладі було створено службове завдання з періодом запуску — раз на 50 хвилин. Що дозволяє завжди зберігати діючий access_token, слід враховувати, що після виконання запиту refresh_token так само оновлюється.

Таким чином було створено 2 службові завдання:

Висновок

В результаті ми можемо здійснювати запити використовуючи REST API та отримувати та записувати практично будь-яку інформацію з хмарної версії Bitrix24. У цій статті було розглянуто приклад отримання всіх лідів та збереження інформації у БД.

Ці дані ми можемо використати:

1)Для визначення номера при вхідному дзвінку та відображенні web-форми в Call-центрі відразу зі сторінкою ліда.

2)Для відображення назві компанії в різних звітах, наприклад пропущені дзвінки, що спростить пошук та швидкість прийняття рішення на відпрацювання виклику.

3)Для використання даної бази в різних вихідних дзвінках, надсилання пошти на e-mail.

Наведено лише кілька прикладів. Застосування може бути різним.

Вихідний код

Скрипт створення таблиць у БД OKTELL

/*[bitrix_oauth] – Таблиця з даними по Bitrix OAuth*/

/*[bitrix_leads] – Таблиця, яка містить всю інформацію щодо лідів*/

/* [bitrix_lead_contacts] – Список контактів лідів*/

/*[bitrix_import_lead_error] – таблиця помилок при виконанні SQL запиту на додавання\оновленняліда*/

/*[bitrix_lead_runtime] – Таблиця з даними за датою запуску сценаріїв імпорту лідів та імпорту контактів лідів*/

/*[bitrix_lead_solution] – Таблиця, що містить рішення клієнтів за проектами (розташовується в самому низу картки ліда)*/