Рабочие пространства
Ключ принадлежит ровно одному рабочему пространству. Что это значит для мультитенантных приложений и чем портал Bitrix24 отличается от отдельного рабочего пространства.
Рабочее пространство владеет подключениями WhatsApp. API key выдаётся для ровно одного рабочего пространства, и всё, что ключ может видеть или делать, ограничено им — запросить данные другого пространства нельзя.
Один ключ, одно рабочее пространство, много подключений
Для мультитенантного приложения нужна именно такая схема:
- Один API key, а не по одному на каждого клиента. Не создавайте ключ для каждого клиента.
- Один
POST /connectionsна каждого клиента, включая самый первый, и у каждого — свой новыйIdempotency-Key. - Направляйте входящие события по
connection_id— это стабильный cuid, который есть в каждом ответе REST и в каждом payload webhook. Сопоставьте его со своей записью о клиенте: идентификатор создаём мы, сопоставление делаете вы. - Новые подключения доступны сразу. Список подключений ключа определяется при каждом запросе заново, поэтому после создания ничего обновлять не нужно.
Два вида рабочих пространств
Отдельное рабочее пространство
Создаётся при регистрации на developers.wasync.app. API — это весь продукт: вы создаёте подключения через REST, и у каждого подключения своя лицензия.
Портал Bitrix24
Создаётся при установке WASync на портал Bitrix24. Подключения создаёт администратор портала в WASync, а доступ к номеру через API — платное дополнение.
Разница проявляется ровно в двух местах, и о ней стоит знать до того, как вы начнёте писать код не для того типа:
Создание подключений. POST /connections работает только в отдельных рабочих пространствах.
На портале Bitrix24 он отвечает 403 forbidden_portal_kind — подключения создаёт
администратор портала в интерфейсе WASync. Все остальные эндпоинты ведут себя
на обоих типах одинаково.
Что делает подключение доступным. В отдельном рабочем пространстве это
собственная лицензия подключения (trial или платная). На портале Bitrix24 номер в CRM оплачивает
подписка портала, а чтобы обращаться к этому же номеру
через API, дополнительно нужно дополнение API — $12 за номер в месяц.
Без него подключения просто нет в GET /connections.
Начало работы
С API key отдельного шага начальной настройки нет: ключ выдаётся для вашего
рабочего пространства напрямую, поэтому POST /connections так же легко создаёт
первое подключение, как и десятое.
Грант OAuth2 устроен иначе: он выдаётся только для уже существующих подключений, поэтому интеграция, которая использует только OAuth2, не может создать первое подключение рабочего пространства. Именно поэтому каждое руководство по быстрому старту здесь начинается с ключа.