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/

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

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 со значениями следующих параметров:

Пример запроса

 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 со значениями следующих параметров:

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

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

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

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

Пример запроса

 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"

}
}'