Сейчас мы проводим разделение нашего проекта на 2 разных, независимых проекта.
В России мы сохраним название amoCRM и домен amocrm.ru, все данные пользователей продолжат храниться и обрабатываться исключительно в России.
На глобальном рынке наш проект будет называться Kommo и находится на домене kommo.com. Kommo работает на своих серверах, имеет свои базы данных и не имеет связи с российским проектом.
Конечно, в первую очередь мы являемся CRM системой, но для многих международных клиентов мы больше, чем CRM система, поэтому мы приняли решение развивать наш бренд. Подробнее о ребрендинге можно почитать тут – https://www.kommo.com/blog/amocrm-rebranding/
В данной статье мы расскажем об изменениях, которые произойдут с API, интеграциями, виджетами и маркетплейсом, в связи с ребрендингом и разделением на amocrm.ru и kommo.com. Поделимся рекомендациями и обратим внимание на возможные проблемы.
Данная статья полезна вам, если вы являетесь разработчиком интеграций и можете ответить хотя бы на один вопрос положительно:
Если вы ответили на все вопросы отрицательно – то данная статья не принесет вам практической пользы. Если хотя бы на один вопрос вы ответили положительно – данная статья поможет адаптировать ваши интеграции и виджеты для работы с несколькими платформами на разных доменах.
Первое, и самое заметное изменение – это изменение домена аккаунта. Теперь amocrm.com аккаунты доступны по новому адресу SUBDOMAIN.kommo.com. Российские аккаунты продолжают быть доступны по старым адресам SUBDOMAIN.amocrm.ru.
В данный момент, при переходе на адрес SUBDOMAIN.amocrm.com происходит редирект на SUBDOMAIN.kommo.com почти для всех аккаунтов. Исключение составляют активные аккаунты, в которых подключены не адаптированные под kommo.com интеграции. Такие аккаунты, временно, доступны как на kommo.com, так и на amocrm.com. В ближайшем будущем, как интеграции будут адаптированы, мы планируем включить редирект и для таких аккаунтов.
Также важно учесть, что в данный момент редирект работает только для веб-версии. Методы API, адреса которых начинаются по следующим маскам – не подвержены редиректу :
В будущем, для API методов также будет подключен редирект. Для GET/POST/PATCH/DELETE/PUT запросов к API методам, редирект будет приходить с HTTP кодом 308 (Permanent Redirect). 308 HTTP код позволяет не терять метод запроса при редиректе, поэтому используется именно он.
Все токены, выпущенные на amocrm.com – продолжат работать и на kommo.com, повторная установка интеграции не требуется.
Дополните информацию о подключенных аккаунтах к вашей интеграции, информаций о принадлежности к версии продукта. Например, создайте колонку account_type или platform, .ru аккаунты помечайте меткой "ru" или 1, .com – меткой "global" или 2.
В зависимости от принадлежности к версии – делайте запросы на amocrm.ru или kommo.com.
Ваши пользователи могут столкнуться с проблемой, что они изменят пароль на amocrm.ru, а зайти в свой аккаунт на kommo.com не смогут. Пользователи могут обратиться к вам за помощью, как к партнеру/интегратору, поэтому мы подготовили ответ на этот вопрос.
Теперь действительно пароли могут различаться от платформы к платформе, более того, пользователь может быть зарегистрирован на amocrm.ru, но не быть зарегистрирован на kommo.com и наоборот. Такое поведение вызвано тем, что amocrm.ru и kommo.com – два независимых проекта, с разными базами данных, разными серверами, которые не синхронизируются между собой.
В связи с тем, что мы не только меняем домен, но и полноценно разрываем связанность платформ, может произойти изменение в идентификаторах, субдоменах аккаунтов.
Идентификаторы и субдомены аккаунтах на разных платформах могут начать повторяться на разных платформах.
Мы просим не использовать ID аккаунта и субдомен аккаунта, в качестве первичного ключа в ваших хранилищах. В качестве первичного ключа вы можете использовать поле id с автоинкрементом. А ID аккаунта и субдомен, наравне с информацией о принадлежности к платформе – будут являться просто свойствами строки в вашем хранилище.
Также изменения затронут биллинг аккаунта и биллинг в партнерском кабинете.
Основные изменения будут касаться способов оплаты:
Если пользователем или интегратором будет произведен платеж по реквизитам или по ранее созданным счетам в рублях за kommo.com аккаунты – будет произведен возврат средств. Такая же история действует и для счетов в долларах за amocrm.ru аккаунты.
В партнерском кабинете на amocrm.ru будет заблокирована возможность оплатить .com аккаунты. В партнерском кабинете на kommo.com будет заблокирована возможность оплатить .ru аккаунты.
В данном разделе рассмотрим основные моменты и изменения в API и интеграциях. В целом, существенных изменений не произойдет, за исключением, описанного выше изменения домена аккаунта на глобальной платформе.
Один из самых главных вопросов – как узнать, к какой платформе принадлежит аккаунт?
Для всех Access Token, выпущенных с 27ого октября, эта информация содержится в токене. Так как токен является JWT токеном, вы можете распарсить его, например с помощью библиотеки https://github.com/lcobucci/jwt.
Понять, к какой площадке относится аккаунт можно через свойства base_domain.
Для global аккаунтов – это kommo.com, для ru аккаунтов – amocrm.ru. Данное свойство показывает, на какой именно платформе выпущен токен.
Пример кода на PHP, который позволит вам распарсить токен:
$configuration = Configuration::forUnsecuredSigner();
$jwtToken = $configuration->parser()->parse($accessToken->getToken());
$claims = $jwtToken->claims();
$baseDomain = $claims->get('base_domain');
$isGlobalAccount = $baseDomain === 'kommo.com';Также, у нас есть метод, который по Access Token может предоставить информацию об аккаунте, в том числе его принадлежность к платформе – https://www.kommo.com/oauth2/account/subdomain и https://www.amocrm.ru/oauth2/account/subdomain.
Если вы уже используете данный метод, или ваша интеграция работает с аккаунтами на нескольких платформах, мы предполагаем следующую схему взаимодействия, пока ваша интеграция не будет хранить информацию о принадлежности аккаунта платформе.
Раньше метод возвращал информацию о российских и глобальных аккаунтах на любом из доменов, теперь метод на https://www.amocrm.ru отдает актуальную информацию только о российских аккаунтах, через некоторое время он перестанет отдавать информацию о global аккаунтах. Метод на https://www.kommo.com и https://www.amocrm.com отдает актуальную информацию только о global аккаунтах, через некоторое время он перестанет отдавать информацию о российских аккаунтах.
Пока ваше приложение сейчас не хранит информацию о привязке аккаунта к платформе, в вашем приложении вы можете сделать запрос сначала на amocrm.ru, если не получили ответа или в ответе свойство top_level_domain имеет значение com – повторить запрос уже на kommo.com.
Мы настоятельно рекомендуем адаптировать приложение и добавить информацию о платформе аккаунта и делать 1 запрос в зависимости от платформы.
Пример, как можно сделать подобные вызовы с помощью библиотеки, которая, по-умолчанию стучится на amocrm.ru.
/** @var AmoCRMClientAmoCRMApiClient $apiClient */
try {
$accountInfo = $apiClient->getOAuthClient()->getAccountDomain($accessToken);
$isRuAccount = $accountInfo->getTopLevelDomain() === 'ru';
} catch (AmoCRMExceptionsAmoCRMApiErrorResponseException $e) {
$isRuAccount = false;
}
if (!$isRuAccount) {
try {
// Важно заменить базовый домен
$apiClient->getOAuthClient()->setBaseDomain('www.kommo.com');
$accountInfo = $apiClient->getOAuthClient()->getAccountDomain($accessToken);
} catch (AmoCRMExceptionsAmoCRMApiErrorResponseException $e) {
// account doesn't exist or token invalid
}
}
var_dump($accountInfo->getTopLevelDomain());При разделении проекта на amocrm.ru и kommo.com, все приватные интеграции будут доступны только на том проекте, которому принадлежит аккаунт, в котором создана приватная интеграция.
Публичные и отраслевые интеграции будут доступны на двух платформах. При применении изменений на одной платформе (новая версия, изменение статуса, изменение адреса перенаправления и тд), на другой платформе изменения будут подтягиваться с минимальными задержками.
client_uuid и client_secret для публичных интеграций будет одинаковым на всех платформах.
В данный момент датацентры аккаунтов на платформе amocrm.ru находятся в РФ, поэтому для самой оптимальной и быстрой работы с API мы рекомендуем использовать хостинги для ваших интеграций в РФ, чтобы обеспечить минимальные задержки между вашим и нашими дата-центрами.
Для аккаунтов на платформе kommo.com датацентры находятся в Северной Америке, поэтому для самой оптимальной и быстрой работы с API стоит учитывать географическое расположение вашего датацентра. Например, если ваш датацентр находится в России, то каждый запрос до global аккаунта будет занимать дополнительные 0.5-0.7 секунды из-за удаленности. Если же ваш датацентр будет также находиться в Северной Америке, то каждый запрос будет увеличиваться уже не более, чем на 0.2 секунды, но в большинстве случаев, не более, чем на 0.1 секунд.
Сейчас, при установке интеграции из маркетплейса, мы отправляем Webhook с кодом авторизации на указанный вами redirect_uri интеграции.
Вместе с данным вебхуком мы присылаем свойство referer, в значении которого находится ссылка на аккаунт вида subdomain.amocrm.ru или subdomain.amocrm.com.
Теперь для аккаунтов на глобал платформе в свойстве referer будет приходить значение subdomain.kommo.com.
Также мы добавили параметр platform. Он показывает, на какой платформе был установлен виджет, российской или глобальной. При установке из аккаунта на
amocrm.ru приходит значение 1, при установке из аккаунта на amocrm.com/kommo.com – значение 2.
Если вы работали с этим свойством – рекомендуем проверить, как именно вы его использовали, и если вы делали split/explode по ".amocrm.", то заменить эту логику и делать split по символу точки.
Сейчас лимиты на запросы считаются по связке субдомен + IP адрес.
Так как субдомены на российской и глобал платформах могут совпадать, появляется вопрос – будет ли изменена логика подсчета лимитов? Ответ – да, подсчет будет производится на каждой платформе независимо.
В данный момент вы можете продолжать использовать нашу библиотеку для работы с API.
Для её переключения для работы с аккаунтом, который находится на глобальной платформе, на kommo.com, вам нужно указать правильный домен для библиотеки перед вызовом методов API:
$apiClient->getOAuthClient()->setBaseDomain('www.kommo.com');
$apiClient->setAccountBaseDomain('subdomain.kommo.com');После данного вызова, запросы будут идти уже на глобальную платформу.
Мы рекомендуем создавать отдельные объекты библиотеки для работы с API для каждого отдельного аккаунта.
Изменения затронут и API чатов. Для аккаунтов на российской платформе – изменений не будет, запросы нужно также делать на хост amojo.amocrm.ru, для аккаунтов на глобальной платформе запросы нужно будет делать на хост amojo.kommo.com.
В данный момент запросы, отправленные на хост amojo.amocrm.com еще принимаются. Но в ближайшем будущем, запросы будут редиректиться на amojo.kommo.com с http кодом 308. Если ваше приложение не поддерживаем редиректы, рекомендуем поддержать новый домен и редиректы.
Ссылки на медиафайлы для глобал аккаунтов уже приходят с доменом kommo.com.
При этом в процессе регистрации каналов чатов изменений не будет, канал также будет регистрироваться и для российской, и для глобальной версии.
Если ваша интеграция содержит архив и делает запросы к сторонним ресурсам из интерфейса amoCRM/Kommo, вам нужно ознакомиться с пунктами ниже и адаптировать интеграцию по инструкции.
Если в вашей интеграции есть архив с виджетом, который работает в интерфейсе amoCRM, скорее всего, вы делаете запросы к себе на сервер.
Если это запросы не через proxy, а напрямую к вам на сервер, вам нужно проверить и убедиться, что ваш сервер отдает заголовки, что он принимает запросы от *.kommo.com.
Cross-Origin Resource Sharing (CORS) – то, как сервера определяют ограничения на выполнение запросов браузера с определенных ресурсов.
Поэтому, когда вы делаете запрос на сторонний ресурс из браузера, браузер делает "preflight" OPTIONS запрос, в ответе на который приходят заголовки Access-Control-Allow-Origin и другие.
Вам необходимо доработать ваше приложение, чтобы в заголовке Access-Control-Allow-Origin возвращался домен subdomain.kommo.com. Вы можете парсить http заголовок Origin и проверять, что домен заканчивается на kommo.com или amocrm.com и в таком случае возвращать заголовок Access-Control-Allow-Origin со значением заголовка Origin.
Наш пример на PHP:
<?php
declare(strict_types=1);
namespace SecurityMiddleware;
use IlluminateSupportStr;
use PsrHttpMessageResponseInterface;
use PsrHttpMessageServerRequestInterface;
use PsrHttpServerMiddlewareInterface;
use PsrHttpServerRequestHandlerInterface;
class CorsMiddleware implements MiddlewareInterface
{
protected $origins = [
'amocrm.com',
'kommo.com',
];
public function process(
ServerRequestInterface $request,
RequestHandlerInterface $delegate
): ResponseInterface
{
$response = $delegate->handle($request);
$origin = $request->getServerParams()['HTTP_ORIGIN'] ?? null;
if ($origin && Str::endsWith($origin, $this->origins)) {
$response = $response->withAddedHeader(
'Access-Control-Allow-Origin',
$origin
)->withAddedHeader(
'Access-Control-Allow-Credentials',
'true'
)->withAddedHeader(
'Access-Control-Allow-Headers',
'Content-Type, Accept, Authorization, Widget-Auth-Token'
)->withAddedHeader(
'Access-Control-Allow-Methods',
'POST, GET, PATCH, DELETE, OPTION',
);
}
return $response;
}
}
В связи с тем, что система теперь существует на разных платформах под разными брендами – использование константы, в которой содержится название бренда является неуместным и может вводить пользователей в заблуждение. Мы изменили название данной константы на APP, но для обратной совместимости, константа AMOCRM пока остается доступна.
Мы рекомендуем теперь использовать константу APP в js части виджета всех новых и обновляемых интеграций.
В процессе модерации и публикации интеграции не будет больших изменений. По-прежнему можно будет создать интеграцию в техническом российском аккаунте, чтобы она была доступна и в kommo.com маркетплейсе и наоборот. Для публикации интеграции в kommo.com маркетплейсе – нужно указать, что ваша интеграция поддерживает другие языки, кроме Русского, ваш сайт должен быть локализован, а вы должны оказывать поддержку клиентов на выбранных языках.
Все новые публичные интеграции и обновления существующих, в которых есть один из следующих языков: Английский, Испанский, Португальский – будут дополнительно проверяться на корректность работы на домене kommo.com.
Также для всех интеграций, будет уделяться внимание на использование константы APP вместо AMOCRM. В первое время, команда модерации, будет давать рекомендации заменить константу, но в будущем это станет требованием и поводом для отказа в публикации новой интеграции или обновления.
Мы рекомендуем начать использовать константу APP уже в ближайших обновлениях и во всех новых интеграциях, которые передаются на модерацию.