Как настроить callback-вызов из GetCourse

Callback-вызов (Вызов URL) — это операция в процессах, отправляющая сообщения с данными во внешний сервис по API.

Зачем использовать
Например, если вы храните и обрабатываете данные о своей клиентской базе в стороннем сервисе и хотите передавать туда данные о новых регистрациях, заказах и других изменениях, то для этого нужно будет настроить callback-вызов.

В статье расскажем:

• Как настроить callback-вызов
• Переменные, которые можно использовать для callback-вызова
• Как сохранить ответ от сервера в доп.поле
• Как протестировать callback-вызов

Создавать и настраивать процессы могут:

• владелец,
• администратор.

Для настройки callback-вызова добавьте в процесс операцию «Вызвать URL».

Обратите внимание: операция «Вызвать URL» не предназначена для массовой передачи данных. Для этого используйте экспорт объектов в файл формата .CSV с последующей обработкой во внешней системе или экспорт API.

В ссылке укажите адрес (URL) внешнего сервиса и перечислите данные, которые необходимо передать из GetCourse.

Например, в процессе по пользователям может быть использован следующий синтаксис:

api_url/?var_1={object.first_name}&var_2={object.email}&...

Тогда вместо {object.first_name} в запросе будет передано имя пользователя, вместо {object.email} — адрес электронной почты пользователя. Можно использовать и другие переменные, полный список ниже [перейти ↓].

Для POST-запроса можно дополнительно указать заголовки и тело запроса в формате x-www-form-urlencoded.

Поля для заполнения заголовка и тела запроса поддерживают те же переменные, что и для GET-запроса. О переменных для callback-вызовов читайте ниже [перейти ↓].

1. Операции «Вызвать URL» выполняются последовательно, то есть выполнение следующей в очереди операции не начнется, пока не будет получен ответ от предыдущей. Поэтому задавать завышенные значения для полей «Время на ожидание соединения» и «Время на соединение» не рекомендуется. Это может приводить к более длительной обработке запросов, и, следовательно, к задержкам в передаче данных и выполнении задач. По умолчанию используются значения в 10 секунд.

2. Для корректной отправки запроса на внешний сервис параметры в URL прописывайте только при помощи следующих символов:
   • буквы латинского алфавита,
   • цифры,
   • знак дефиса «-»,
   • знак нижнего подчеркивания «_».

3. Если во время выполнения операции на стороне принимающего сервиса возникнут какие-то сложности, задача пойдет по ветке «Ошибка». Чтобы учесть подобные ситуации, укажите в схеме процесса, что нужно сделать системе в таком случае. Например, можно уведомить ответственного сотрудника, чтобы он разобрался в ситуации/уточнил информацию.

4. В задачах для блока «Вызвать URL» иногда появляется кнопка для ручной обработки «Выполнить», даже если в настройках не включена опция «Менеджер должен подтвердить запуск». Такое поведение возникает, если до блока с вызовом URL дошло сразу много задач:
   • поскольку такие вызовы обрабатываются последовательно, задачи могут встать в очередь;
   • пока задача ждёт своей очереди, в интерфейсе отображается кнопка «Выполнить»;
   • блок запустится автоматически, как только подойдёт его очередь.
   При необходимости вы можете нажать эту кнопку, если какую-то задачу нужно сделать быстрее, — она будет выполнена вне очереди.

Ниже представлен список переменных, которые можно использовать в поле URL только с определенным синтаксисом, который зависит от объекта процесса.

Например, для использования переменной {first_name} в процессе по пользователям нужно добавить приставку object, чтобы получилось {object.first_name}. В процессе по заказам к этой переменной также необходимо добавить приставку user, чтобы получилось {object.user.first_name}.

Подробнее в статье → «Как правильно использовать переменные в процессе».

Список переменных:

1. Пользователь:

• {first_name} — имя,
• {last_name} — фамилия,
• {name} — имя полностью,
• {id} — идентификатор,
• {email} — эл. адрес,
• {phone} — телефон,
• {city} — город,
• {avatar_url} — ссылка на аватар пользователя,
• {Название дополнительного поля} — данные из дополнительного поля пользователя (нужно вписать полный заголовок поля, значение которого должно передаваться),
• {personal_manager} — имя персонального менеджера пользователя,
• {personal_manager_email} — эл. адрес персонального менеджера пользователя,
• {personal_manager_phone} — телефон персонального менеджера пользователя.

2. Заказ:

• {number} — номер заказа,
• {id} — идентификатор заказа,
• {positions} — состав заказа (наименования предложений),
• {offers} — состав заказа (ID-идентификаторы предложений),
• {created_at format='d-m-Y'} — дата создания заказа,
• {payed_at format='d-m-Y'} — дата оплаты заказа,
• {cost_money} — стоимость заказа с пробелом,
• {cost_money_value} — стоимость заказа без пробела,
• {left_cost_money} — сколько осталось заплатить,
• {payed_money} — сколько оплачено,
• {status} — статус заказа,
• {payment_link} — ссылка на оплату,
• {promocode} — если в заказе использован промокод, можно передать его название,
• {Название дополнительного поля} — данные из дополнительного поля заказа (нужно вписать полный заголовок поля, значение которого должно передаваться),
• {manager} — имя менеджера заказа,
• {manager_email} — эл. адрес менеджера заказа,
• {manager_phone} — телефон менеджера заказа,
• {positions_price} — наименование и стоимость предложения, его количество в заказе и валюта (значения выводятся через точку с запятой). Важно! Если в заказе несколько предложений, то они будут разделены между собой переносом строки %0A.
• {funnel_id} — ID доски продаж, на которой находится заказ,
• {funnel_stage_id} — ID этапа на доске продаж, в котором находится заказ.

Также у заказа есть специальное поле user, по которому можно получить дополнительные данные о клиенте, оформившем заказ: user.first_name и т.п. (см. выше).

3. Покупка:

• {product_title} — название продукта,
• {start_at} — дата начала покупки,
• {finish_at} — дата окончания покупки,
• {start_at_ago} — время, прошедшее от старта,
• {finish_at_ago} — время, оставшееся до окончания,
• {period_string} — период доступа,
• {state} — статус покупки (текущее состояние),
• {link} — ссылка на покупку,
• {training_link} — ссылка на тренинг (если продукт связан с тренингом),
• {training_title} — название тренинга,
• {training_teacher_full_name} — полное имя основного преподавателя тренинга,
• {training_teacher_avatar_src} — путь к файлу аватарки преподавателя.

У покупки, как и у заказа, есть специальное поле user, по которому можно получить дополнительные данные о клиенте, оформившем покупку: user.first_name и т.п. (см. выше).

Обратите внимание: для корректной работы переменных по персональному менеджеру пользователя и менеджеру заказа — personal_manager, personal_manager_email, personal_manager_phone и manager, manager_email, manager_phone — должны быть указаны данные в разделе «Партнерская программа».

Если данные в поле «Имя отправителя» не будут указаны, то для переменных personal_manager и manager значение будет получено из профиля менеджера.

4. Партнёр пользователя:

• {partner.uid} — идентификатор партнёра,
• {partner.first_name} — имя партнёра,
• {partner.last_name} — фамилия партнёра,
• {partner.real_name} — автоматическое русскоязычное имя партнёра,
• {partner.email} — эл. адрес партнёра,
• {partner.phone} — номер телефона партнёра,
• {partner.created_at} — дата регистрации партнёра.

5. Источник пользователя или заказа (сессия, во время которой пользователь зарегистрировался или создал заказ):

• {create_session.gcpc} — партнёрский код,
• {create_session.utm_source} — UTM-метки,
• {create_session.utm_medium}
• {create_session.utm_campaign}
• {create_session.utm_content}
• {create_session.utm_term}
• {create_session.utm_group}
• {create_session.clickid} и т.д.

Вы можете добавить в ссылку любой кастомный параметр — если пользователь пройдёт по этой ссылке и зарегистрируется или создаст заказ, параметр запишется в соответствующий источник и его можно будет передавать по API.

Вы также можете использовать некоторые другие переменные, например, собственные или переменные сложной автозамены. Подробнее читайте в статье → «Как правильно использовать переменные в процессе».

После вызова URL вы можете получить ответ сервера и сохранить его в дополнительное поле пользователя, чтобы использовать в дальнейшем (например, в рассылке):

Протестировать работу колбэка можно, например, через сервис RequestBin. Создайте RequestBin и на этот адрес отправьте вызов URL с необходимыми параметрами.

После этого вы увидите результат с переданными данными.

Пример запроса в процессе по заказам: 

https://requestb.in/yiy4yryi?imya={object.user.first_name}&pochta={object.user.email}&telefon={object.user.phone}&nomer_zakaza={object.number}&soderzhimoe={object.positions}&stoimost={object.cost_money}

Результат: