WAuth

Система вдохновлена OAuth2.0, но формально ей не является. Этот способ подключения должен использовать каждый технический партнер, который хочет опубликоваться в нашем магазине интеграций.

Неформально Wauth нужен, чтобы не заставлять пользователя копировать и вставлять API ключи, а чтобы подключать интеграцию, что называется, «по кнопке».

Целевой кейс со стороны пользователя CRM, который хочет подключить Wazzup CRM Х:

1. Пользователь находит CRM X внутри магазина интеграций Wazzup;

2. Пользователь кликает “Подключить CRM X”;

3. Пользователь редиректится в CRM X;

4. Пользователь проходит авторизацию в CRM X и подтверждает намерения создания интеграции;

>>> интеграция между Wazzup и CRM X подключена

Подготовительные шаги

Разработчики тех.партнера:

1. Регистрируются в Wazzup

2. Переходят в раздел “интеграции”

3. Создают интеграцию с типом API

4. Получают API KEY —> могут начать отлаживать основные сценарии интеграции (все, кроме WAuth)

5. Когда пришло время работать над WAuth, вызывают POST v3/marketplace, чтобы передать значения полей:

  • crmCode — строка из латинских букв, цифр (можно использовать дефис и нижнее подчеркивание). Служит для внутренней идентификации CRM. Уникальное в рамках Wazzup
  • authRedirectUri — адрес страницы, на которую будет делаться редирект устанавливающего интеграцию клиента для подтверждения авторизации
  • secret — ключ (токен), который используется при подтверждении установки интеграции. Участвует только в запросах «сервер — сервер», клиенту никогда не отсылается

>>> Можно начинать работу с Wauth

Описание процесса WAuth

1. Пользователь в ЛК Wazzup нажимает кнопку «добавить» интеграцию.

В этот момент:

  • генерируется state, в котором закодированы crmCode и accountId (которые тех.партнер передал с помощью POST v3/marketplace)
  • в query string authRedirectUri, добавляем state и переводим пользователя по этой ссылке. (authRedirectUri тех.партнер тоже передал с помощью POST v3/marketplace)

2. Клиент переходит по ссылке, осуществляет процесс авторизации на стороне CRM.

3. При успешной авторизации, CRM делает запрос POST v3/connect (подробнее о запросе). Для отладки этого пункта необходимо использовать POST /v3/wauth, который имитирует установку интеграции клиентов.

4. Получив запрос, Wazzup сохраняет crmKey, генерирует apiKey и отдает его в теле ответа, если всё успешно

5. CRM загружает информацию о пользователях, сделках, контактах, воронках с этапами и устанавливает URL для вебхуков

>>>> интеграция успешно подключена

Важно! На любом этапе тех.партнер может попросить тестовые каналы для отладки интеграции. Мы выдаем бесплатные подписки на несколько каналов разных типов, чтобы была возможность обработать все кейсы, включая многоканальность. 

Публикация в маркетплейсе интеграций Wazzup

Для публикации необходимо:

1. Реализовать сценарии интеграции

2. Настроить авторизацию с помощью Wauth

3. Установить название CRM и логотип с помощью PATCH v3/marketplace

4. Написать в поддержку Wazzup с просьбой опубликовать модуль интеграции. Техническая поддержка Wazzup передаст тикет ревьюверу, который проверит работоспособность интеграции и ее соответствие требованиям. Если все ок, то интеграция будет опубликована, иначе модуль вернутся на доработку разработчику, об этом он получит оповещение в чате, в котором был отправлен запрос на публикацию.

Подключение интеграции, размещенной в маркетплейсе, через WAuth

Если пользователь кликнул “подключить интеграцию”, успешно был переведен по заданной ссылке и авторизовался в CRM, то CRM должна сделать запрос на

 POST https://api.wazzup24.com/v3/connect/
Данный метод имеет нестандартную авторизацию. Идентификация пользователя проходит по свойству secret, размещенному в теле запроса.

В теле запроса должен содержаться JSON со значениями следующих параметров:

Параметр Тип Описание
state String сгенерированный и подписанный на стороне wazzup ключ, полученный интегратором на первом этапе подключения СРМ
secret String секрет, введённый администратором маркетплейсной CRM
crmKey String сгенерированный тех.партнером ключ, который будет приходить в заголовке { Authorization: «Bearer {wazzupKey}» } при отправке вебхуков
name String название интеграции
curl --location --request POST 'https://api.wazzup24.comi/v3/connect' \
--header 'Content-Type: application/json' \
--data-raw '
{
"state": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2Vy....",
"secret": "61e5a375-1760-452f-ad73-5318844ffc4f",
"crmKey": "e0629e11-0f67-4567-92a9-2237e91ec1b9",
"name": "Any integration name"
}
'
Ответ

200 ok

data — ключ, который необходимо использовать * в заголовке Authorization: Bearer {apiKey} при запросах в Wazzup

Загрузка параметров Wauth

Для обновления crmCode, authRedirectUri, secret необходимо вызвать

 POST https://api.wazzup24.com/v3/marketplace

В теле запроса должен содержаться JSON со значениями следующих параметров:

Параметр Тип Описание
crmCode String Строка из латинских букв, цифр (можно использовать дефис и нижнее подчеркивание). Служит для внутренней идентификации CRM. Уникальное в рамках Wazzup. Не более 50 символов.
authRedirectUri String Адрес страницы, на которую будет переводиться пользователь, который устанавливает интеграцию, для подтверждения авторизации.
secret String Ключ (токен), который используется при подтверждении установки интеграции. Участвует только в запросах «сервер — сервер».
Пример запроса
 curl --location --request POST 'https://api.wazzup24.com/v3/marketplace' \
--header 'Authorization: Bearer 4a0с541451244aa9a281fba4716da40d' \
--header 'Content-Type: application/json' \
--data-raw '{
"crmCode": "BestCrmInTheWorld",
"secret": "our-secret",
"authRedirectUri": "http://redirect.uri"
}'

Имитация установки интеграции клиентом (тест Wauth)

Чтобы имитировать установку интеграции клиентом, необходимо вызвать:

 POST https://api.wazzup24.com/v3/wauth

В теле запроса должен содержаться JSON со значениями следующих параметров:

Параметр Тип Описание
type String crmCode указанный интегратором в момент вызова POST /v3/marketplace

Загрузка названия и логотипа интеграции

Для изменение логотипа и публичного названия модуля интеграции, необходимо вызвать:

 PATCH https://api.wazzup24.com/v3/marketplace

В теле запроса должен содержаться JSON со значениями следующих параметров:

Параметр Тип Описание
crmName String Публичное название CRM на английском языке, которое будет отображаться в ЛК Wazzup
logo Object Объект с данными логотипа:
— Прозрачный или белый фон— Формат svg— Без внутренних отступов в логотипе— Название компании на логотипе на английском языке
logo.name String Название файла с логотипом
logo.content String base64-кодированный файл с логотипом
Этот метод может быть вызван только тогда, когда модуль интеграции находится в стадии разработки, т.е еще не прошел ревью и не был опубликован в маркетплейсе Wazzup. Если вам нужно изменить crmName или логотип после публикации модуля, то обратитесь в поддержку.
Пример запроса
 curl --location --request PATCH 'https://api.wazzup24.com/v3/marketplace' \
--header 'Authorization: Bearer 4a0b541a61244aa9a281fba4816da48d' \
--header 'Content-Type: application/json' \
--data-raw '{
"crmName": "The Cool CRM",
"logo": {
"name": "the-cool-crm.svg",
"content": "YmFzZTY0LWVuY29kZWQtbG9nby1maWxlLWNvbnRlbnQK"

}
}'