Авторизация

Авторизация через API

Производит авторизацию пользователя в системе. Все методы API могут быть использованы только после авторизации.

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

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

URL метода
POST /private/api/auth.php

Параметры

ПараметрыОписание
USER_LOGIN
require
Логин пользователя. В качестве логина в системе используется e-mail.
USER_HASH
require
Ключ пользователя, который можно получить на странице редактирования профиля пользователя.

Метод может также принимать на вход необязательный GET параметр.

ПараметрыОписание
type Если type = json, то ответ будет приходить в виде json массива, вместо XML документа

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

ПараметрДанные
POST https://example.amocrm.ru/private/api/auth.php
POST DATAUSER_LOGIN=example@amocrm.com&
USER_HASH=c123ae456cd7891246bffb1e654abb9d

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

  1. <root>
  2.   <auth>true <!-- (или false в случае ошибки) --></auth>
  3. </root>

Пример интеграции

  1. #Массив с параметрами, которые нужно передать методом POST к API системы
  2. $user=array(
  3.   'USER_LOGIN'=>'test@testmail.com', #Ваш логин (электронная почта)
  4.  'USER_HASH'=>'7ebefd1d4741106a4daa0e0a673bba2e4dc16054' #Хэш для доступа к API (смотрите в профиле пользователя)
  5. );
  6. $subdomain='test'; #Наш аккаунт - поддомен
  7. #Формируем ссылку для запроса
  8. $link='https://'.$subdomain.'.amocrm.ru/private/api/auth.php?type=json';
  9. /* Нам необходимо инициировать запрос к серверу. Воспользуемся библиотекой cURL (поставляется в составе PHP). Вы также
  10. можете
  11. использовать и кроссплатформенную программу cURL, если вы не программируете на PHP. */
  12. $curl=curl_init(); #Сохраняем дескриптор сеанса cURL
  13. #Устанавливаем необходимые опции для сеанса cURL
  14. curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);
  15. curl_setopt($curl,CURLOPT_USERAGENT,'amoCRM-API-client/1.0');
  16. curl_setopt($curl,CURLOPT_URL,$link);
  17. curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');
  18. curl_setopt($curl,CURLOPT_POSTFIELDS,json_encode($user));
  19. curl_setopt($curl,CURLOPT_HTTPHEADER,array('Content-Type: application/json'));
  20. curl_setopt($curl,CURLOPT_HEADER,false);
  21. curl_setopt($curl,CURLOPT_COOKIEFILE,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  22. curl_setopt($curl,CURLOPT_COOKIEJAR,dirname(__FILE__).'/cookie.txt'); #PHP>5.3.6 dirname(__FILE__) -> __DIR__
  23. curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);
  24. curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);
  25. $out=curl_exec($curl); #Инициируем запрос к API и сохраняем ответ в переменную
  26. $code=curl_getinfo($curl,CURLINFO_HTTP_CODE); #Получим HTTP-код ответа сервера
  27. curl_close($curl); #Завершаем сеанс cURL
  28. /* Теперь мы можем обработать ответ, полученный от сервера. Это пример. Вы можете обработать данные своим способом. */
  29. $code=(int)$code;
  30. $errors=array(
  31.   301=>'Moved permanently',
  32.   400=>'Bad request',
  33.   401=>'Unauthorized',
  34.   403=>'Forbidden',
  35.   404=>'Not found',
  36.   500=>'Internal server error',
  37.   502=>'Bad gateway',
  38.   503=>'Service unavailable'
  39. );
  40. try
  41. {
  42.   #Если код ответа не равен 200 или 204 - возвращаем сообщение об ошибке
  43.  if($code!=200 && $code!=204)
  44.     throw new Exception(isset($errors[$code]) ? $errors[$code] : 'Undescribed error',$code);
  45. }
  46. catch(Exception $E)
  47. {
  48.   die('Ошибка: '.$E->getMessage().PHP_EOL.'Код ошибки: '.$E->getCode());
  49. }
  50. /*
  51.  Данные получаем в формате JSON, поэтому, для получения читаемых данных,
  52.  нам придётся перевести ответ в формат, понятный PHP
  53.  */
  54. $Response=json_decode($out,true);
  55. $Response=$Response['response'];
  56. if(isset($Response['auth'])) #Флаг авторизации доступен в свойстве "auth"
  57.  return 'Авторизация прошла успешно';
  58. return 'Авторизация не удалась';
Код ошибки HTTP код Описание
110 401 Unauthorized Общая ошибка авторизации. Неправильный логин или пароль.
111 401 Unauthorized Возникает после нескольких неудачных попыток авторизации. В этом случае нужно авторизоваться в аккаунте через браузер, введя код капчи.
112 401 Unauthorized Возникает, когда пользователь выключен в настройках аккаунта "Пользователи и права" или не состоит в аккаунте.
113 403 Forbidden Доступ к данному аккаунту запрещён с Вашего IP адреса. Возникает, когда в настройках безопасности аккаунта включена фильтрация доступа к API по "белому списку IP адресов".
101 401 Unauthorized Возникает в случае запроса к несуществующему аккаунту (субдомену).
401 401 Unauthorized Not Authorized. На сервере нет данных аккаунта. Нужно сделать запрос на другой сервер по переданному IP.

Описание ошибки 401 Not Authorized (на сервере нет данных аккаунта)

Возникает, когда аккаунт зарегистрирован на одном сервере, а запрос идет к другому серверу, на котором нет данных этого аккаунта. Чаще всего это бывает, когда аккаунт зарегистрирован на одном сервере, к примеру, на amocrm.ru, а запрос к API идет на другой сервер, к примеру на amocrm.com.
Для обеспечения бесперебойной работы проекта у нас используется не один, а несколько серверов, поэтому бывают ситуации, когда в ответе может вернуться HTTP-код 401 и error_code 401, даже на верные данные авторизации. В этот момент в ответе также будет передан верный IP сервера, на который должен быть произведен повторный запрос. Обратите внимание, что в таком случае клиентом должен быть передан тот же hostname, который использовался и при запросе, выдавшем 401 для верной работы сертификатов.

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

  1. {
  2.     response: {
  3.         error: "401 Not Authorized"
  4.         ip: "95.213.174.147"
  5.         domain: "example.amocrm.com"
  6.         auth: false
  7.         server_time: 1444448888
  8.         error_code: "401"
  9.     }
  10. }

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

Коды ошибок API