Пример по шагам

Для примера рассмотрим полный цикл получения доступа к данным, начиная от регистрации новой интеграции.
При этом мы будем рассматривать прямую работу с API авторизации, но вы можете либо воспользоваться нашей готовой библиотекой на PHP для упрощения разработки, либо готовыми библиотеками сторонних вендоров, которые можно найти по ссылке.

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

Оглавление

Регистрация приложения

Все начинается с того, что вам необходимо зайти в раздел "амоМаркет" того аккаунта, в котором вы будете осуществлять поддержку интеграции в будущем. Обратите внимание:

  • Именно за этим аккаунтом будет закреплена Интеграция.
    Это означает, что любой из администраторов этого аккаунта сможет управлять интеграцией и получит доступ к общим ключам приложения.
    Подробнее о терминах можно прочесть здесь.
    По сути этот аккаунт мы будем считать аккаунтом разработчика.
    Если вы разрабатываете публичную интеграции, необходимо ознакомиться с требованиями.
  • Для создания интеграции вам необходимо обладать правами администратора аккаунта
  • При подключении приватной интеграции на аккаунте который не является техническим, клиенту необходимо заполнить заявление на отказ от технической поддержки amoCRM. Техническая поддержка не сможет принять обращения по ошибкам системы для фиксации и исправлений на аккаунте где было подписано заявление. Данное ограничение не касается консультаций и вопросов по оплате. Приняв единожды данное соглашение, оно фиксируется в аккаунте amoCRM навсегда. Отозвать соглашение и вернуть аккаунт к прежнему состоянию возможности уже не будет.

Приватная интеграция

После нажатия на кнопку Создать Интеграцию, в появившейся форме, вам необходимо указать Название интеграции, выбрать требуемые доступы и указать описание.
Также необходимо указать Redirect URI – url страницы получения токенов и загрузить логотип интеграции.
Кроме того, есть возможность указать url для хука об отключении интеграции – на него придет хук, когда интеграция будет отключена пользователем. Поле для хука об отключении является необязательным.

Свойства интеграции:

  • Название интеграции (не более 255 символов) – отображается на странице интеграций, модальном окне для предоставления доступов, а также участвует в поиске по странице интеграций.
  • Описание интеграции (не более 65000 символов) – отображается в модальном окне интеграции в аккаунте пользователя. Допускается использование html верстки.
  • Ссылка для перенаправления – ссылка на ваш сайт, который будет обрабатывать работу с ключами. Важно, что домен должен быть защищен SSL сертификатом, если вы планируете использовать интеграцию более, чем в одном аккаунте.Просим обратить внимание на то, что мы не поддерживаем кириллические домены и кирилические домены, преобразованные с помощью паникода. Также мы периодически проверяем доступность домена, как обязательное условие для работы интеграции.
  • Ссылка для хука об отключении интеграции – на этот адрес будет отправлен GET-запрос при отключении интеграции пользователем. В запросе будет содержаться 2 параметра account_id и client_id.
  • Предоставить доступ – минимальный набор необходимых разрешений для работы интеграции. Подробнее про разрешения можно прочитать в статье.
  • Иконка интеграции (400х272 jpeg/jpg/png/gif) – отображается в списке интеграций, а также в окне запроса доступа у пользователя
  • Контроль дублей – галку необходимо ставить, если ваша интеграция поддерживает Контроль дублей. После установки галки, интеграция будет доступна в настройках контроля дублей.
  • Множественные источники – галку необходимо ставить, если ваша интеграция сама управляет источниками через API. Если галка установлена, amoCRM не будет создавать источники по-умолчанию, интеграция сама должна будет создать все необходимые ей источники.

Кроме этих пунктов, администраторам аккаунта, в котором создана интеграция, будут доступны: ID интеграции, секретный ключ интеграции, код авторизации (после включения интеграции).

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

Обратите внимание, что Secret key и Integration ID привязаны к интеграции и будут показаны только в вашем аккаунте разработчика.

Получение Authorization code


Напомним, что код авторизации является временным ключом, который действует только 20 минут.
C его помощью вам необходимо в течении этого времени получить refresh token и access токен.
Он является временным, т.к. может быть перехвачен, но в случае перехвата злоумышленник не сможет с ним ничего сделать, если вы не сообщите ему ключи приложения, известные только администраторам аккаунта, в котором создана интеграция.

Получить Authorization code можно тремя способами:

  • Скопировать из модального окна установленной интеграции. Этот случай подойдет, если вам необходимо проинтегрировать только один аккаунт amoCRM. Подробнее можно прочитать в разделе Упрощенная авторизация.
  • Если в вашей интеграции есть загруженный архив с виджетом, то при его установке вы получите Webhook на указанный в настройках интеграции Redirect URI.
  • Получить код через адрес предоставления доступа интеграции. После предоставления доступа, пользовать будет перенаправлен на указанный Redirect URI.

Вы можете упростить разработку при использовании способа получения ключа через GET-параметры, используя готовую Кнопку amoCRM.

Полная логика способа получения ключа через GET-параметры заключается в следующем:

  • Пользователь, у которого вы хотите запросить доступ, находится у вас на сайте и может открыть предложенную вами ссылку.
    *Внимание: Очень важно, чтобы для пользователя весь процесс был максимально прозрачен и понятен. При клике на ссылку пользователь должен однозначно понимать следующее: произойдет запрос его доступов в его аккаунте amoCRM, какую интеграцию он включает.
    Именно поэтому мы предлагаем использовать нашу брендированную кнопку, описание которой вы можете найти на странице Кнопка amoCRM
  • Генерация ссылки, по которой должен перейти пользователь. Вам необходимо отправить пользователя на URL https://www.amocrm.ru/oauth?client_id={Integration ID}&state={параметр состояния, который будет возвращен вам на Redirect URI}&mode={popup или post_message}.
    Integration ID вам уже известен.
    state – это сгенерированный вами строковый параметр, возможно хеш.
    State нужен для того, чтобы при получении ответа от amoCRM, вы могли проверить его достоверность,
    сравнив отправленный ключ и полученный в результате, чтобы удостовериться в отсутствии подмены CSRF.
    Параметр mode отвечает за обработку запроса на Redirect URI. В случае popup – окно авторизации будет закрыто,
    а переход на Redirect URI будет выполнен в основном окне. В случае передачи значения post_message –
    перенаправление произойдет в окне, которое было открыто, после обработки кода авторизации вам нужно закрыть окно.
    Также можно сообщить информацию об успешности действия в основное окно с использованием функции postMessage.
  • Перейдя по ссылке, пользователь увидит логотип вашей интеграции, который вы загружали при ее создании, название, а также перечень доступов, которые запрашивает приложение.
    Открывать данную страницу мы советуем как модальное окно – в popup. Это позволит пользователю не терять контекста страницы, которая открыла popup.
    Окно предоставления доступов
  • В случае, если пользователь не авторизован – ему будет предложено авторизоваться в amoCRM, иначе пользователю будет дан выбор из аккаунтов, где он является администратором. Для приватных интеграций, список будет ограничен 1 аккаунтом.
  • После выбора аккаунта и нажатия кнопки Разрешить, интеграция будет установлена в выбранный аккаунт,
    а пользователь перенаправлен в модальном или основном окне, в зависимости от параметра mode,
    на указанный в настройках интеграции Redirect URI c GET-параметрами code, referer, state, from_widget, platform.
    Параметр code содержит Authorization code, параметр referer – адрес аккаунта пользователя, параметр state – строку,
    которую вы передавали при открытии окна, если строка не была передана, данный параметр возвращен не будет.
    Параметр platform показывает, на какой платформе был установлен виджет, российской или глобальной. При установке из аккаунта на
    amocrm.ru приходит значение 1, при установке из аккаунта на amocrm.com/kommo.com – значение 2.
    Если мы отправляем Webhook после установки виджета, то вам дополнительно придет GET-параметр from_widget
  • В случае, если пользователь нажмет кнопку Отказать приложению в доступе, он будет перенаправлен на Redirect URI с GET-параметром error=access_denied, а также GET-параметром state, если он был передан.

Пример обработки авторизации, если был передан параметр post_message

При переданном GET-параметре mode со значением post_message в окно предоставление доступов – перенаправление произойдет в самом окне.
Ниже рассмотрим пример общения окна предоставления доступов и основного окна с использованием функции postMessage.
Код ниже размещен в основном окне:

var popup;

auth();

// 1. Открывает окно предоставления доступов
function auth() {
  popup = window.open('https://www.amocrm.ru/oauth?client_id=XXX&state=XXX&mode=post_message', 'Предоставить доступ', 'scrollbars, status, resizable, width=750, height=580');
}

// 2. Регистрируем обработчика сообщений из popup окна
window.addEventListener('message', updateAuthInfo);

// 3. Функция обработчик, зарегистрированная выше
function updateAuthInfo(e) {
  if (e.data.error !== undefined) {
    console.log('Ошибка - ' + e.data.error)
  } else {
    console.log('Авторизация прошла')
  }

  // 4. Закрываем модальное окно
  popup.close();
}

Код ниже будет отдан в модальное окно вашим backend сервером при переходе на Redirect URI:

<!doctype html>
<html lang="en">
<head>
  <title>oAuth Postback</title>
  <script>
    //Передадим данные в родительское окно, набор данных определяете вы
    if(window.opener){
      window.opener.postMessage({'error': undefined, 'status': 'ok'}, "*");
    }
  </script>
</head>
</html>

После отработки кода выше, основное окно узнает результат. Рекомендуем закрывать модальное окно автоматически,
как это сделано в примере, чтобы у пользователя не возникла путаница в окнах.

Обмен кода авторизации на access token и refresh token


Получив Authorization code, вам необходимо сделать запрос на специальный метод /oauth2/access_token, описанный ниже.
В ответ вы получите пару Access и Refresh token, а также время в секундах, через которое токен истекает.

Access токен аналогичен ключу сессии. Его можно сохранить в приложении и использовать для запросов к API до истечения времени его жизни.
Токен должен быть доступен только вашему приложению, поэтому не рекомендуется сохранять его в cookies браузера,
открытых конфигурационных файлах и т. п.

Метод

POST /oauth2/access_token

Параметры запроса

Параметр Тип данных Описание
client_id string ID интеграции
client_secret string Секрет интеграции
grant_type string Тип авторизационных данных (для кода авторизации – authorization_code)
code string Полученный код авторизации
redirect_uri string Redirect URI указанный в настройках интеграции. Должен четко совпадать с тем, что указан в настройках

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

{
  "client_id": "xxxx",
  "client_secret": "xxxx",
  "grant_type": "authorization_code",
  "code": "xxxxxxx",
  "redirect_uri": "https://test.test"
}

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Запрос успешно обработан
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Параметр Тип данных Описание
token_type string Тип токена
expires_in int Через сколько истекает токен
access_token string Access Token в формате JWT
refresh_token string Refresh Token

Пример ответа

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "xxxxxx",
  "refresh_token": "xxxxx"
}

Получение Access токен по коду авторизации, реализация на bash

curl https://subdomain.amocrm.ru/oauth2/access_token -d \
'{"client_id":"xxx-xxx-xxx-xxx-xxx","client_secret":"xxxxxx","grant_type":"authorization_code","code":"xxxxxxxx","redirect_uri":"https://test.test/"}' \
-H 'Content-Type:application/json' \
-X POST

Получение Access токен по коду авторизации, реализация на PHP

<?php
$subdomain = 'test'; //Поддомен нужного аккаунта
$link = 'https://' . $subdomain . '.amocrm.ru/oauth2/access_token'; //Формируем URL для запроса

/** Соберем данные для запроса */
$data = [
    'client_id' => 'xxxx',
    'client_secret' => 'xxxx',
    'grant_type' => 'authorization_code',
    'code' => 'xxxxxx',
    'redirect_uri' => 'https://test.ru/',
];

/**
 * Нам необходимо инициировать запрос к серверу.
 * Воспользуемся библиотекой cURL (поставляется в составе PHP).
 * Вы также можете использовать и кроссплатформенную программу cURL, если вы не программируете на PHP.
 */
$curl = curl_init(); //Сохраняем дескриптор сеанса cURL
/** Устанавливаем необходимые опции для сеанса cURL  */
curl_setopt($curl,CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-oAuth-client/1.0');
curl_setopt($curl,CURLOPT_URL, $link);
curl_setopt($curl,CURLOPT_HTTPHEADER,['Content-Type:application/json']);
curl_setopt($curl,CURLOPT_HEADER, false);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER, 1);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST, 2);
$out = curl_exec($curl); //Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
/** Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code = (int)$code;
$errors = [
    400 => 'Bad request',
    401 => 'Unauthorized',
    403 => 'Forbidden',
    404 => 'Not found',
    500 => 'Internal server error',
    502 => 'Bad gateway',
    503 => 'Service unavailable',
];

try
{
    /** Если код ответа не успешный - возвращаем сообщение об ошибке  */
    if ($code < 200 || $code > 204) {
        throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undefined error', $code);
    }
}
catch(\Exception $e)
{
    die('Ошибка: ' . $e->getMessage() . PHP_EOL . 'Код ошибки: ' . $e->getCode());
}

/**
 * Данные получаем в формате JSON, поэтому, для получения читаемых данных,
 * нам придётся перевести ответ в формат, понятный PHP
 */
$response = json_decode($out, true);

$access_token = $response['access_token']; //Access токен
$refresh_token = $response['refresh_token']; //Refresh токен
$token_type = $response['token_type']; //Тип токена
$expires_in = $response['expires_in']; //Через сколько действие токена истекает

Получение нового access token по его истечении

Из предыдущего пункта вы заметили, что вместе с Access token был также возвращен Refresh token.
Он необходим для продолжения работы с API, по истечении срока действия Access токена, т.е. это довольно частая операция.

Refresh token имеет два существенных ограничения его жизни:

  • Refresh токен действует всего 3 месяца. Если интеграция не используется в течение 3 месяцев,
    не было ни одного запроса на актуализацию ключа, то интеграция потеряет доступ к данным и будем необходимо повторно
    запрашивать разрешение у пользователя на доступ к его аккаунту
  • Refresh token можно обменять только один раз.
    После отправки его в метод и получения новой пары access token/refresh token старый refresh token становится не актуальным.
    И после получения нового refresh token его необходимо обязательно сохранить, иначе придется вновь перезапрашивать доступ у пользователя.

По истечении срока действия возможность получения Access токена по нему становится невозможной.
Для обмена необходимо сделать запрос на специальный метод с действительным Refresh токеном.
В ответ вы получите новый Access и Refresh токены.

Метод

POST /oauth2/access_token

Параметры запроса

Параметр Тип данных Описание
client_id string ID интеграции
client_secret string Секрет интеграции
grant_type string Тип авторизационных данных (для кода авторизации – refresh_token)
refresh_token string Refresh токен
redirect_uri string Redirect URI указанный в настройках интеграции. Должен четко совпадать с тем, что указан в настройках

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

{
  "client_id": "xxxx",
  "client_secret": "xxxx",
  "grant_type": "refresh_token",
  "refresh_token": "xxxxx",
  "redirect_uri": "https://test.test"
}

Заголовок типа данных при успешном результате

Content-Type: application/json

Заголовок типа данных при ошибке

Content-Type: application/json

HTTP коды ответа

Код ответа Условие
200 Запрос успешно обработан
400 Переданы некорректные данные. Подробности доступны в теле ответа

Параметры ответа

Параметр Тип данных Описание
token_type string Тип токена
expires_in int Через сколько истекает токен
access_token string Access Token в формате JWT
refresh_token string Refresh Token

Пример ответа

{
  "token_type": "Bearer",
  "expires_in": 86400,
  "access_token": "xxxxxx",
  "refresh_token": "xxxxx"
}

Получение Access токен по Refresh токену, реализация на bash

curl https://subdomain.amocrm.ru/oauth2/access_token -d \
'{"client_id":"xxx-xxx-xxx-xxx-xxx","client_secret":"xxxxxx","grant_type":"refresh_token","refresh_token":"xxxxxxxx","redirect_uri":"https://test.test/"}' \
-H 'Content-Type:application/json' \
-X POST

Получение Access токен по коду авторизации, реализация на PHP

<?php
$subdomain = 'test'; //Поддомен нужного аккаунта
$link = 'https://' . $subdomain . '.amocrm.ru/oauth2/access_token'; //Формируем URL для запроса

/** Соберем данные для запроса */
$data = [
    'client_id' => 'xxxx',
    'client_secret' => 'xxxx',
    'grant_type' => 'refresh_token',
    'refresh_token' => 'xxxxxx',
    'redirect_uri' => 'https://test.ru/',
];

/**
 * Нам необходимо инициировать запрос к серверу.
 * Воспользуемся библиотекой cURL (поставляется в составе PHP).
 * Вы также можете использовать и кроссплатформенную программу cURL, если вы не программируете на PHP.
 */
$curl = curl_init(); //Сохраняем дескриптор сеанса cURL
/** Устанавливаем необходимые опции для сеанса cURL  */
curl_setopt($curl,CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-oAuth-client/1.0');
curl_setopt($curl,CURLOPT_URL, $link);
curl_setopt($curl,CURLOPT_HTTPHEADER,['Content-Type:application/json']);
curl_setopt($curl,CURLOPT_HEADER, false);
curl_setopt($curl,CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl,CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER, 1);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST, 2);
$out = curl_exec($curl); //Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
/** Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code = (int)$code;
$errors = [
    400 => 'Bad request',
    401 => 'Unauthorized',
    403 => 'Forbidden',
    404 => 'Not found',
    500 => 'Internal server error',
    502 => 'Bad gateway',
    503 => 'Service unavailable',
];

try
{
    /** Если код ответа не успешный - возвращаем сообщение об ошибке  */
    if ($code < 200 || $code > 204) {
        throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undefined error', $code);
    }
}
catch(\Exception $e)
{
    die('Ошибка: ' . $e->getMessage() . PHP_EOL . 'Код ошибки: ' . $e->getCode());
}

/**
 * Данные получаем в формате JSON, поэтому, для получения читаемых данных,
 * нам придётся перевести ответ в формат, понятный PHP
 */
$response = json_decode($out, true);

$access_token = $response['access_token']; //Access токен
$refresh_token = $response['refresh_token']; //Refresh токен
$token_type = $response['token_type']; //Тип токена
$expires_in = $response['expires_in']; //Через сколько действие токена истекает

Долгосрочные токены

В феврале 2024 мы добавили возможность создавать долгосрочные токены для внешних и приватных интеграций.

Для создания необходимо перейти на вкладку "Ключи", нажать кнопку "Сгенерировать токен", выбрать дату окончания действия токена и скопировать токен. После того, как токен создан, вы увидете его только один раз, поэтому его необходимо скопировать.


Важно отметить, что подобные токены подойдут для небольших интеграций, которые разрабатываются под конкретный аккаунт.
Срок действия токена пользователь выбирает сам и он действует от 1 дня до 5 лет. Кроме этого, во вкладке "Выданные доступы" долгосрочные токены имеют не только дату выдачи, но и дату окончания действия, но вы всегда можете отозвать сами нажав на кнопку "Отозвать доступ".

Долгосрочные токены не имеют refresh_token и поэтому не требуют обмена и не требуют написания логики, которая будет следить за актуальностью токенов.

Запросы к API с передачей access token

C помощью полученного Access токена вы можете легко делать запросы к API приложения.

Вам не нужно отправлять куки-файлы с каждым запросом, также вам нужно добавить заголовок Authorization: Bearer {access токен} во все ваши запросы к API amoCRM.

Пример запроса к методу account

<?php
$subdomain = 'test'; //Поддомен нужного аккаунта
$link = 'https://' . $subdomain . '.amocrm.ru/api/v4/account'; //Формируем URL для запроса
/** Получаем access_token из вашего хранилища */
$access_token = 'xxxx';
/** Формируем заголовки */
$headers = [
    'Authorization: Bearer ' . $access_token
];
/**
 * Нам необходимо инициировать запрос к серверу.
 * Воспользуемся библиотекой cURL (поставляется в составе PHP).
 * Вы также можете использовать и кроссплатформенную программу cURL, если вы не программируете на PHP.
 */
$curl = curl_init(); //Сохраняем дескриптор сеанса cURL
/** Устанавливаем необходимые опции для сеанса cURL  */
curl_setopt($curl,CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-oAuth-client/1.0');
curl_setopt($curl,CURLOPT_URL, $link);
curl_setopt($curl,CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl,CURLOPT_HEADER, false);
curl_setopt($curl,CURLOPT_SSL_VERIFYPEER, 1);
curl_setopt($curl,CURLOPT_SSL_VERIFYHOST, 2);
$out = curl_exec($curl); //Инициируем запрос к API и сохраняем ответ в переменную
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);
/** Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
$code = (int)$code;
$errors = [
    400 => 'Bad request',
    401 => 'Unauthorized',
    403 => 'Forbidden',
    404 => 'Not found',
    500 => 'Internal server error',
    502 => 'Bad gateway',
    503 => 'Service unavailable',
];

try
{
    /** Если код ответа не успешный - возвращаем сообщение об ошибке  */
    if ($code < 200 || $code > 204) {
        throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undefined error', $code);
    }
} catch(\Exception $e)
{
    die('Ошибка: ' . $e->getMessage() . PHP_EOL . 'Код ошибки: ' . $e->getCode());
}

Подобным образом можно делать запросы ко всем методам API, на которые у токена хватает прав.
Токен имеет права пользователя, который предоставил доступ.

Хук об отключении интеграции

Начиная с ноября 2021 года, вы можете указать адрес, на который будет отправлен запрос, когда интеграция будет отключена.
После получения хука вы сможете остановить интеграцию, ограничить запросы к аккаунту, в котором произошло отключение.

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

Проверка подлинности хука

Что бы удостоверится, что хук действительно пришел от amoCRM, а не от злоумышлеников,
рекомендуется проверять подпись хука, передаваемую в GET-параметре signature,
а так же id oauth-клиента интеграции, передаваемый в GET-параметре client_uuid.
В качестве подписи хука передается HMAC, сообщением является конкатенация id oauth-клиента интеграции
с id аккаунта, для которого отзывается токен, ключем – секретный ключ oauth-клиента интеграции, алгоритм шифровния – sha256.

Пример кода для проверки подлинности
<?php
// id oauth-клиента интеграции
$clientId = 'xxx';
// секретный ключ oauth-клиента интеграции
$clientSecret = 'xxx';

if (empty($_GET['client_uuid']) || empty($_GET['signature']) || empty($_GET['account_id'])) {
    throw new \HttpInvalidParamException('Wrong hook format');
}

$hookClientId = $_GET['client_uuid'];
$hookSignature = $_GET['signature'];
$hookAccountId = (int) $_GET['account_id'];

if ($clientId !== $hookClientId) {
    throw new \Exception('Invalid hook signature');
}

if (!hash_equals(
    hash_hmac('sha256', sprintf('%s|%s', $clientId, $hookAccountId), $clientSecret),
    $hookSignature
)) {
    throw new \Exception('Invalid hook signature');
}
// проверка подлинности пройденна, можно вызывать вашу логику обработки хука

Обработка ошибок

В ходе отработки всей вышеуказанной логики может возникать ряд исключений, которые необходимо обрабатывать, рассмотрим каждое из них:

  • Если пользователь не дал разрешение на доступ к аккаунту, в случае использования кнопки amoCRM, будет вызвана функция,
    которая передана в одном из параметров. Подробней можно прочесть в разделе Кнопка amoCRM.
    Если же страница была открыта не кнопкой, то в случае отказа будет произведен редирект на Redirect URI c GET-параметром error=access_denied.
  • Если администратор аккаунта деактивировал установку интеграции, то выданные ей access_token будут отозваны.
    При обращении к API вы получите HTTP код 401.
    Для продолжения работы интеграции интегратору необходимо снова получить авторизацию для его интеграции у пользователя.
  • Если вы не записали актуальный refresh token, он был утерян, либо прошло более 3 месяцев,
    то для возобновления работы интеграции вам опять необходимо пройти процесс авторизации приложения.
  • Если вами были утеряны основные ключи интеграции или вы случайно их опубликовали,
    то вы можете обновить секретный ключ в модальном окне интеграции в аккаунте, где она была создана.
    После обновления Secret Key интеграции вам необходимо обновить секретный ключ в конфигурациях ваших интеграциях.

Смотрите также

Библиотека
Кнопка на сайт