Если у вас еще нет amoCRM
Создать прямо сейчасДля примера рассмотрим полный цикл получения доступа к данным, начиная от регистрации новой интеграции. При этом мы будем рассматривать прямую работу с API авторизации, но вы можете либо воспользоваться нашей готовой библиотекой на PHP для упрощения разработки, либо готовыми библиотеками сторонних вендоров, которые можно найти по ссылке.
Мы разрабатывали авторизацию, основываясь на протоколе oAuth 2.0, поэтому вы можете найти в открытых источниках много примеров и документацию, описывающих взаимодействие и логику выполнения запросов.
Все начинается с того, что вам необходимо зайти в раздел Интеграции того аккаунта, в котором вы будете осуществлять поддержку интеграции в будущем. Обратите внимание:
После нажатия на кнопку Создать Интеграцию, в появившейся форме, вам необходимо указать Название интеграции, выбрать требуемые доступы и указать описание. Также необходимо указать Redirect URI – url страницы получения токенов и загрузить логотип интеграции. Кроме того, можно указать url для хука об отключении интеграции – на него придет хук, когда интеграция будет отключена пользователем. Поля для хука об отключении является необязательным.
Кроме этих пунктов администраторам аккаунта, в котором создана интеграция, будут доступны: id интеграции, секретный ключ интеграции, код авторизации (после включения интеграции).
После заполнения полей вам необходимо нажать Сгенерировать ключ. После этого новая интеграция будет создана и на следующей странице модального окна будут отображены необходимые ключи.
Обратите внимание, что Secret key и Integration ID привязаны к интеграции и будут показаны только в вашем аккаунте разработчика.
Напомним, что это временный ключ, который действует только 20 минут и с его помощью вам необходимо в течении этого времени получить refresh token и access токен. Он является временным, т.к. может быть перехвачен, но в случае перехвата злоумышленник не сможет с ним ничего сделать, если вы не сообщите ему ключи приложения, известные только администраторам аккаунта, в котором создана интеграция.
Получить Authorization code можно тремя способами:
Вы можете упростить разработку при использовании способа получения ключа через GET-параметры, используя готовую Кнопку amoCRM.
Полная логика способа получения ключа через GET-параметры заключается в следующем:
При переданном GET-параметре mode со значением post_message в окно предоставление доступов – перенаправление произойдет в самом окне. Ниже рассмотрим пример общения окна предоставления доступов и основного окна с использованием функции postMessage.
Код ниже размещен в основном окне:
<script>
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();
}
</script>
Код ниже будет отдан в модальное окно вашим 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>
После отработки кода выше, основное окно узнает результат. Рекомендуем закрывать модальное окно автоматически, как это сделано в примере, чтобы у пользователя не возникла путаница в окнах.
Получив Authorization code, вам необходимо сделать запрос на специальный метод /oauth2/access_token, описанный ниже. В ответ вы получите пару Access и Refresh token, а также время в секундах, через которое токен истекает.
Access токен аналогичен ключу сессии. Его можно сохранить в приложении и использовать для запросов к API до истечения времени его жизни. Токен должен быть доступен только вашему приложению, поэтому не рекомендуется сохранять его в cookies браузера, открытых конфигурационных файлах и т. п.
POST /oauth2/access_token
| Параметр | Описание |
|---|---|
| client_id | ID интеграции |
| client_secret | Секрет интеграции |
| grant_type | Тип авторизационных данных (для кода авторизации – authorization_code) |
| code | Полученный код авторизации |
| redirect_uri | Redirect URI указанный в настройках интеграции |
| Параметр | Описание |
|---|---|
| token_type | Тип токена (Bearer) |
| expires_in | Время в секундах, показывающее через сколько токен истечет |
| access_token | Access токен |
| refresh_token | Refresh токен |
{
"client_id": "xxxx",
"client_secret": "xxxx",
"grant_type": "authorization_code",
"code": "xxxxxxx",
"redirect_uri": "https://test.test"
}
{
"token_type": "Bearer",
"expires_in": 86400,
"access_token": "xxxxxx",
"refresh_token": "xxxxx"
}
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
<?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 был также возвращен Refresh token. Он необходим для продолжения работы с API, по истечении срока действия Access токена, т.е. это довольно частая операция.
Refresh token имеет два существенных ограничения его жизни:
По истечении срока действия возможность получения Access токена по нему становится невозможной. Для обмена необходимо сделать запрос на специальный метод с действительным Refresh токеном. В ответ вы получите новый Access и Refresh токены.
POST /oauth2/access_token
| Параметр | Описание |
|---|---|
| client_id | ID интеграции |
| client_secret | Секрет интеграции |
| grant_type | Тип авторизационных данных (для refresh токена – refresh_token) |
| refresh_token | Refresh токен |
| redirect_uri | Redirect URI указанный в настройках интеграции |
| Параметр | Описание |
|---|---|
| token_type | Тип токена (Bearer) |
| expires_in | Время в секундах, показывающее через сколько токен истечет |
| access_token | Access токен |
| refresh_token | Refresh токен |
{
"client_id": "xxxx",
"client_secret": "xxxx",
"grant_type": "refresh_token",
"refresh_token": "xxxxx",
"redirect_uri": "https://test.test"
}
{
"token_type": "Bearer",
"expires_in": 86400,
"access_token": "xxxxxx",
"refresh_token": "xxxxx"
}
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
<?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']; //Через сколько действие токена истекает
C помощью полученного Access токена вы можете легко делать запросы к API приложения. Для этого потребуется немного изменить запросы, которые сейчас делаются к API.
Вам не нужно больше отправлять куки-файлы с каждым запросом, а также авторизовываться с параметрами USER_LOGIN и USER_HASH, вместо этого необходимо добавить заголовок Authorization: Bearer {access токен}.
<?php
$subdomain = 'test'; //Поддомен нужного аккаунта
$link = 'https://' . $subdomain . '.amocrm.ru/api/v2/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, отслеживать когда интеграция была отключена.
В ходе отработки всей вышеуказанной логики может возникать ряд исключений, которые необходимо обрабатывать, рассмотрим каждое из них: