Система вдохновлена 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 со значениями следующих параметров:
Параметр | Тип | Описание |
state | String | сгенерированный и подписанный на стороне wazzup ключ, полученный интегратором на первом этапе подключения СРМ |
secret | String | секрет, введённый администратором маркетплейсной CRM |
wazzupKey | Srting | сгенерированный тех.партнером ключ, который будет приходить в заголовке { Authorization: «Basic {wazzupKey}» } при отправке вебхуков |
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
apikey — ключ, который необходимо использовать * в заголовке Authorization: Bearer {apiKey} при запросах в Wazzup
Загрузка параметров Wauth
Для обновления crmCode, authRedirectUri, secret необходимо вызвать
POST https://api.wazzup24.com/v3/marketplaces
В теле запроса должен содержаться 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/marketplaces
В теле запроса должен содержаться JSON со значениями следующих параметров:
Параметр | Тип | Описание |
crmName | String | Публичное название CRM на английском языке, которое будет отображаться в ЛК Wazzup |
logo | Object | Объект с данными логотипа: — Прозрачный или белый фон— Формат svg— Без внутренних отступов в логотипе— Название компании на логотипе на английском языке |
logo.name | String | Название файла с логотипом |
logo.content | String | base64-кодированный файл с логотипом |
Пример запроса
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" } }'