Amocrm где взять хэш для доступа к api
Let’s take a look at the full process of getting access to data, beginning from the registration of a new integration. While at it we will also discuss the direct work with authorization API, but you can use our premade PHP library to simplify development or premade libraries from other vendors, which you can find by following this link
We developed the authorization on the base of the oAuth 2.0 protocol, that’s why you can find in open source a lot of examples and documentation, that describes the logic of making requests.
Шаг 3. Настройка OAuth авторизации
Когда пользователь будет устанавливать наше приложение, система запросит доступ для приложения к определенным ресурсам аккаунта (скопам). После согласия пользователь будет перенаправлен на URL, указанный в Oauth настройках вашего приложения. В параметрах к запросу будет передан код авторизации, который в дальнейшем приложение сможет обменять на Access Token.
Копируем ссылку, переходим в настройки вашего приложения, в раздел "Oauth авторизация", вставляем ссылку на редирект и отмечаем любой скоп на ваш вкус. Сейчас это не принципиально. Жмем сохранить.
Возвращаемся в амо, и пробуем установить наше приложение
Видим, что ошибки больше нет. Приложение запрашивает доступ к скопам, которые мы выбрали в настройках приложения. Разрешаем.
Видим что нас перенаправило на webhook.site.
Дальше приложению нужно будет обменять код на access token.
6. Errors handler
When working with the logic above,some exceptions that need to be handled may appear, let’s take a look at all of them:
Механизм oAuth авторизации пришел на смену устаревшему механизму API-ключей пользователей. Новый механизм должен помочь разработчикам решить ряд задач, которые не решал старый. Основные задачи, которые вы можете решить с помощью механизма oAuth авторизации в amoCRM:
- Получить доступ к данным аккаунта в котором вы являетесь администратором “под собой”, используя упрощенную механику авторизации, без использования редиректов. Для простых задач – простые решения. и разрешения от пользователя amoCRM на доступ к данным его аккаунта в соответствии с запрошенными разрешениями.
- Регистрировать и авторизовывать пользователя в своем приложении на основе авторизации amoCRM, используя Кнопку входа amoCRM
- Загружать виджет в систему для использования в браузере.
Чтобы облегчить процесс интеграции, мы разработали библиотеку для авторизации. На текущий момент мы поддерживаем только написанную на PHP библиотеку, но, нам кажется, что просмотр исходных файлов может подсказать решения и разработчикам на других языках.
Что такое интеграция?
Чтобы ваше приложение/сервис смогли обращаться к API amoCRM, вам необходимо добавить интеграцию в разделе Интеграции в вашем аккаунте. После заполнения минимальной формы amoCRM сгенерирует и отобразит необходимые для авторизации ключи, которые вы сможете использовать в процессе авторизации.
Некоторые ключи являются уникальными для интеграции и будут видны всегда только в том аккаунте, в котором вы создадите эту интеграцию, а аккаунт будет считаться аккаунтом разработчика. При этом все администраторы данного аккаунта смогут редактировать данную интеграцию.
Именно после создания интеграции у нее появляются два уникальных именно для нее параметра. Они будут использоваться независимо от аккаунта, в котором она будет включаться: Secret key и Integration ID, которые в дальнейшем будут использоваться при работе с авторизацией.
Что такое виджет?
Виджет является дополнением интеграции и несет в себе архив с файлами, которые будут подгружены пользователю и будут выполняться в браузере клиента. Архив содержит набор изображений, необходимых для его отображения в разных местах системы, набор языковых файлов, которые необходимы виджету для работы. А также js-файлы, которые будут выполняться и файл manifest.json, в котором описаны основные параметры виджета.
Что такое установка?
Связь интеграции и конкретного аккаунта, в котором была включена интеграция. Интеграция – это отдельный объект. Он связан с аккаунтом разработчика, в котором создали интеграцию. Чтобы интеграция получила доступ к конкретному аккаунту, ее необходимо установить/включить в этом аккаунте.
Как только вы включаете интеграцию в конкретном аккаунте, у этой связки появляется временный идентификатор – Authorization code.
Что такое Authorization code?
Код авторизации необходим для первичного получения пары access и refresh токенов. Доступен в интерфейсе или через Redirect URI, если авторизация прошла через модальное окно предоставления доступов. Срок жизни кода – 20 минут. Этот код не является скрытым, т.е. пользователь может увидеть его в серверных запросов. Именно поэтому в рамках протокола oAuth 2.0 его необходимо обменять на ключи доступа Refresh и Access, используя известные только вам ключи приложения.
В рамках связки интеграция-аккаунт (т.е. установки) может быть несколько Authorization code и несколько связок Access token/Refresh token, т.к. интеграция в одном аккаунте может быть установлена разными администраторами аккаунта одновременно.
Что такое Access token?
Строка в стандарте JSON Web Token, которая позволяет обращаться к сервисам amoCRM от имени определенного пользователя. По сути является аналогом идентификатора сессии.
Каждый токен обязательно содержит:
- идентификатор пользователя, к которому привязан токен
- идентификатор приложения, к которому привязан токен
- набор действий, доступных приложению
- идентификатор аккаунта, к которому привязан токен
Токен имеет ограниченный срок жизни (1 сутки) и может быть получен с помощью кода авторизации или Refresh токена.
Что такое Refresh token?
Дополнительная строка, которая выдается вместе с токеном. Refresh токен используется для обновления access токена, время жизни которого истекает. Данный токен имеет срок жизни равный 3 месяцам, при каждом обновлении access token выдается новый refresh token.
Каждый раз по истечении сессии вы обновляете оба ключа, и старым ключем воспользоваться уже будет невозможно. Если пройдет 3 месяца, то мы считаем, что интеграция не используется и refresh token также будет отозван. Это значит, что пользователю, который предоставлял доступ, нужно будет предоставить доступ повторно.
Для примера рассмотрим полный цикл получения доступа к данным, начиная от регистрации новой интеграции.
При этом мы будем рассматривать прямую работу с API авторизации, но вы можете либо воспользоваться нашей готовой
библиотекой на PHP для упрощения разработки,
либо готовыми библиотеками сторонних вендоров, которые можно найти по ссылке.
Мы разрабатывали авторизацию, основываясь на протоколе oAuth 2.0,
поэтому вы можете найти в открытых источниках много примеров и документацию,
описывающих взаимодействие и логику выполнения запросов.
Оглавление
Все начинается с того, что вам необходимо зайти в раздел Интеграции того аккаунта,
в котором вы будете осуществлять поддержку интеграции в будущем. Обратите внимание:
- Именно за этим аккаунтом будет закреплена Интеграция.
Это означает, что любой из администраторов этого аккаунта сможет управлять интеграцией и получит доступ к общим ключам приложения.
Подробнее о терминах можно прочесть здесь.
По сути этот аккаунт мы будем считать аккаунтом разработчика.
Если вы разрабатываете публичную интеграции, необходимо ознакомиться с требованиями. - Для создания интеграции вам необходимо обладать правами администратора аккаунта
После нажатия на кнопку Создать Интеграцию, в появившейся форме, вам необходимо указать Название интеграции,
выбрать требуемые доступы и указать описание.
Также необходимо указать 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 привязаны к интеграции и будут показаны только в вашем аккаунте разработчика.
Информация о пользователе
Ответ придет в следующем JSON'e:
Возвращает информацию о пользователе >
Что дальше?
Далее предлагаем изучить туториал по разработке виджета, охватывающий все доступные функции API. Вы научитесь:
- разрабатывать ботов для директ переписок
- как настроить возможность приглашения бота в канал. Работа с упоминаниями
- cоздавать вкладку и объекты обсуждения
- разрабатывать виджеты для конструктора ботов
Либо можете сразу начать изучение доступных методов API.
Для публикации вашей интеграции (приложения или виджета) необходимо обратиться в техническую поддержку amo: написать в чат технической поддержки в вашем аккаунте или на наш адрес электронной почты support@amo.tm. В обращении укажите ваш ID партнёра, информацию об интеграции, её функционале и ID.
В рамках данного руководства вы научитесь:
- разрабатывать ботов для директ переписок
- как настроить возможность приглашения бота в канал. Работа с упоминаниями
- cоздавать вкладку и объекты обсуждения
- разрабатывать виджеты для конструктора ботов
Предполагается, что вы уже прошли "Быстрый старт" и обладаете навыками настройки приложения в amo - мессенджер. Все дальнейшие уроки будут основаны на приложении, которое вы создали на "Быстром страте".
Query Parameters
Query Parameters
Получение id полей
Получение идентификаторов полей, пользователей и всего остального реализовано через GET запросы. Подробнее можно ознакомиться в документации, а для наших целей я подготовил отдельный файл, нужные эти данные. Открываем файл get.php и добавляем в него:
Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
hash | yes | string | not yet implemented |
Response format
Status | Body | Description |
---|---|---|
200 | Success, contains user information | |
200 | Failure, problem+json | |
204 | empty | Сhanges are not applied |
Переходим к интеграции
Не буду приводить пример html формы, нужно обработать форму и передать в amo.php необходимые данные. Открываем amo.php и добавляем:
В самом начале у нас список переменных, куда необходимо передать данные из формы, например: $name = $_POST['name'];
В $pipeline_id необходимо записать id воронки, его можно получить из url crm:
Открываем раздел "Сделки", берем id открывшейся воронки (число в конце url), либо переключаемся на другую.
К $user_amo вернемся чуть позже. Заполняем остальные переменные.
Массив $data заполните информацией на свое усмотрение, согласно документации.
Обновление токена
Access token является временным и требует обновления.
Открываем файл access.php и добавляем следующее:
Если вы сохраняли данные предыдущего запроса в БД, пропишите получение их из БД (59-61 строки).
Создание нового пользователя
Требуемые права: - Управление структурой компании ( company:rw )
Вы можете добавлять новых сотрудников в компанию. Пользователем с таким email будет добавле в вашу компанию, а на его почту придет письмо с приглашением присоединиться.
Response format
Status | Body | Description |
---|---|---|
200 | Success, contains user information | |
200 | Failure, problem+json | |
204 | empty | User not found |
Изменение пользователя
Ответ придет в следующем JSON'e:
Возвращает информацию о пользователе >
user | type | Description |
---|---|---|
string | Контактный email | |
phone | string | Контактный телефон |
position | string | Должность |
1. Registration of an Application
It all begins with you going to Settings, Integrations of the account, in which you will support the integration in the future.
Please note: This account will be the main one for your Integration. It means that any administrator of that account can manage the integration and get access to the common keys of an application. You can check the terminology here. Such an account will be treated by us as a developer account.
To create an integration you need administrator rights on the account.
After clicking on the button Create Integration in the interface of the opened window you need to indicate the Integration name, select Allow access and indicate the Integration description. You also need to indicate the Redirect URl – url of the page of getting tokens and upload the logo of the Integration.
- Name of the Integration (Not more than 255 symbols) – displayed on the page of Integrations, the modal window of granted access and also in the search on the Integrations page.
- Description of the Integration (Not more than 65000 symbols) – displayed in the modal window of the integration. You can use HTML layout.
- Redirect URl – link your site, which will be working with keys. It’s important that the domain would be protected with an SSL certificate, if you plan to use the integration in more than one account. Also, we periodically check the accessibility of the domain, as required for the integration to work.
- Allow access – minimum set of required permissions for an integration to work. More details explained in this article here.
- Icon of the integration (400×272 jpeg/jpg/png/gif) – displayed in the integrations page and in the window for getting access from the user.
Except for these administrators of the account, in which the integration was created it will also have: ID of integration, Secret key of integration, Authorization code.
After filling out the form you’ll need to click on Generate key. After that the new integration will be created and on the next page of the modal window, you will see all the required keys.
Please note: The Secret key and Integration ID connected to the integration will show up only in your developer account.
Список пользователей
Ответ придет в следующем JSON'e:
Возвращает список пользователей аккаунта
Шаг 4. Обмен кода авторизации на access token
В данном руководстве мы напишем простое PHP приложение, которое обменяет код авторизации на access token и выведет его пользователю. После чего, через 15 секунд, закроет окно авторизации.
Создаем директорию для нашего приложения
Создаем приложение на heroku
Создаем локальный git репозиторий и добавляем репозиторий, который нам создал heroku
Папку vendor под игнор
Создадим файл amo_authorization.php, на который будет перенаправлен пользователь с кодом авторизации. Проинициализируем oauth клиент. clientId , clientSecret нужно взять из настроек нашего приложения
Комитим изменения и отправляем в репозиторий heroku.
Ждем когда задеплоится приложение на heroku.
Заходим в настройки нашего приложения, раздел Oauth авторизация. Прописываем redirect URL, который нам выдал heroku. Сохраняем.
Возвращаемся в амо - мессенджер, удаляем и заново устанавливаем наше приложение. Если все сделали правильно, видим наш access token
Получение Authorization code
Напомним, что код авторизации является временным ключом, который действует только 20 минут.
C его помощью вам необходимо в течении этого времени получить refresh token и access токен.
Он является временным, т.к. может быть перехвачен, но в случае перехвата злоумышленник не сможет с ним ничего сделать,
если вы не сообщите ему ключи приложения, известные только администраторам аккаунта, в котором создана интеграция.
Получить Authorization code можно тремя способами:
- Скопировать из модального окна установленной интеграции. Этот случай подойдет, если вам необходимо проинтегрировать только один аккаунт amoCRM. Подробнее можно прочитать в разделе Упрощенная авторизация.
- Если в вашей интеграции есть загруженный архив с виджетом, то при его установке вы получите Webhook на указанный в настройках интеграции Redirect URI.
- Получить код через адрес предоставления доступа интеграции. После предоставления доступоа, пользовать будет перенаправлен на указанный Redirect URI.
Вы можете упростить разработку при использовании способа получения ключа через GET-параметры, используя готовую Кнопку amoCRM.
Полная логика способа получения ключа через GET-параметры заключается в следующем:
Пример обработки авторизации, если был передан параметр post_message
При переданном GET-параметре mode со значением post_message в окно предоставление доступов – перенаправление произойдет в самом окне.
Ниже рассмотрим пример общения окна предоставления доступов и основного окна с использованием функции postMessage.
Код ниже размещен в основном окне:
Код ниже будет отдан в модальное окно вашим backend сервером при переходе на Redirect URI:
После отработки кода выше, основное окно узнает результат. Рекомендуем закрывать модальное окно автоматически,
как это сделано в примере, чтобы у пользователя не возникла путаница в окнах.
1. Registration of an Application
It all begins with you going to Settings, Integrations of the account, in which you will support the integration in the future.
Please note: This account will be the main one for your Integration. It means that any administrator of that account can manage the integration and get access to the common keys of an application. You can check the terminology here. Such an account will be treated by us as a developer account.
To create an integration you need administrator rights on the account.
After clicking on the button Create Integration in the interface of the opened window you need to indicate the Integration name, select Allow access and indicate the Integration description. You also need to indicate the Redirect URl – url of the page of getting tokens and upload the logo of the Integration.
- Name of the Integration (Not more than 255 symbols) – displayed on the page of Integrations, the modal window of granted access and also in the search on the Integrations page.
- Description of the Integration (Not more than 65000 symbols) – displayed in the modal window of the integration. You can use HTML layout.
- Redirect URl – link your site, which will be working with keys. It’s important that the domain would be protected with an SSL certificate, if you plan to use the integration in more than one account. Also, we periodically check the accessibility of the domain, as required for the integration to work.
- Allow access – minimum set of required permissions for an integration to work. More details explained in this article here.
- Icon of the integration (400×272 jpeg/jpg/png/gif) – displayed in the integrations page and in the window for getting access from the user.
Except for these administrators of the account, in which the integration was created it will also have: ID of integration, Secret key of integration, Authorization code.
After filling out the form you’ll need to click on Generate key. After that the new integration will be created and on the next page of the modal window, you will see all the required keys.
Please note: The Secret key and Integration ID connected to the integration will show up only in your developer account.
embed_subject/package.json
Встраивание чата в собственный продукт (closed beta)
В данном туториале мы разберем технологию встраивания чата амо в собственный продукт.
Общение в амо происходит в рамках "Команды". Поэтому для начала, нам нужно получить доступ к команде или создать новую. В этом туториале мы будем создавать новую команду.
Добавим в проект файл embed_subject.php .
Подключим amo PHP sdk
Напишем код, который создаст команду и сохранит ее ID в постоянное хранилище.
Далее для каждого пользователя вашей системы нужно создать профиль в амо. Профиль - это пользователь амо без авторизационных данных. Индентификатор профиля амо нужно будет закрепить за реальным пользователем вашей системы.
Напишем код, который будет создавать профиль и сохранять его идентификатор в постоянное хранилище.
Общение должно происходить в рамках чата. Мы создали специальный тип группового чата для интеграций - объект обсуждения (subject) .
Напишем код, который будет создавать объект обсуждения с одним единственным участником - профилем, который мы создали выше.
Мы создали команду, профиль и объект обсуждения. Теперь встроим виджет чата объекта обсуждения в наш интерфейс. Предположим, что в интерфейсе у нас авторизован пользователь, для которого мы создали профиль амо. Будем встраивать виджет от его лица.
Создадим папку embed_subject и структуру файлов для фронта
Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
name | yes | string (email) | Имя сотрудника. |
yes | string | Email сотрудника. | |
position | no | string | Должность в компаии |
phone | yes | string | Номер телефона сотрудника |
Идентифицировать access token
В ответ придет структура JSON
Получить user uuid, client uuid, company uuid, связанные с access token.
embed_subject/src/app.js
Подключим фронт в наш PHP скрипт
Или сразу развернуть пример на heroku
5. Requests to API by exchanging an access token
Example of a request to method account
Like this, you can make requests to all methods of API, for which a token has enough permissions.
Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
hash | yes | string | not yet implemented |
Создаем файлы интеграции
Создаем папку amo, например в корне сайта.
Файлы внутри:
amo.php
access.php
config.php
get.php
cookie.txt
tokens.txt
Названия могут быть произвольными.
Вывод
На этом все, если все сделано правильно, лиды будут приходить в неразобранное, создаваться контакт, подтягиваться в него имя, телефон, а также кастомные поля, utm метки, которые были указаны в $data и название компании.
Данное руководство описывает программный интерфейс (далее API) к amo | корпоративный мессенджер (далее amo - мессенджер).
Для регистрации необходимо:
Авторизуемся под учетной записью amo - мессенджера.
Заполним форму регистрацию партнера
Дождемся одобрения заявки. Как правило, заявка одобряется в течение 3-4 рабочих дней.
После одобрения заявки, нам откроется доступ к личному кабинету партнера.
В личном кабинете партнера доступно:
- Заключить партнерский договор
- Регистрировать аккаунты клиента. Тем самым закреплять клиента за собой.
- Оплачивать лицензию для клиента с партнерской скидкой
- Разрабатывать приложения для кастомизации фуникцонала amo - мессенджера
Response format
Status | Body | Description |
---|---|---|
200 | Success | |
401 | Invalid access token |
Response format
Status | Body | Description |
---|---|---|
200 | Success | |
200 | Failure, problem+json | |
204 | empty | User already deactivated |
Шаг 5. Получить контекст access token
В дальнейшей работе с API, помимо токена, нам понадобится информация о том, кто установил нашу интеграцию. Дополним наше PHP приложение, чтобы после получения access token мы сразу узнали user_id , company_id , client_id . Весь код будет выглядеть так:
Комитим изменения, пушим в репозиторий Heroku.
Переустанавливаем наше приложение в амо-мессенджере, теперь, помимо access token, мы получим его контекст, который сможем использовать в дальнейших запросах:
Вы можете развернуть код примера сразу на heroku
Query Parameters
Parameter | Required | Type | Description |
---|---|---|---|
hash | yes | string | not yet implemented |
Получение ключей
Открываем AmoCRM, заходим в Настройки > Интеграции.
Жмем "+ Создать интеграцию" и создаем внешнюю интеграцию.
Указываем ссылку на наш amo.php файл, ставим галочку предоставления доступа и вводим произвольное название и описание:
P.S. Перед сохранением прочтите этот раздел до конца
У нас появится 3 ключа и 20 минут, чтоб сделать следующее:
Открываем config.php и вписываем их туда:
Поддомен AmoCRM берем из url нашей CRM
В $redirect_uri не забудьте поменять свой домен сайта
Затем идем в файл auth.php и вставим следующее:
Тут мы отправляем запрос в AmoCRM для получения токенов. Токены сохраняются в файл (45-57 строки), вы можете сохранять их в БД.
IFrame
Значение поля iframe_url используется в клиентских приложения amo для предоставления дополнительной информации по объекту обсуждения. Контент по этой ссылке будет выведен в iframe (web версия) или WebView (мобильная).
Дополнительно к параметрам ссылки будут добавлены:
Параметр | Значение |
---|---|
user_id | Id пользователя, который просматривает ссылку |
account_id | Id аккаунта, в котором находится объект обсуждения |
expired_at | Дата unix когда истекает доступ по ссылке |
sig | Подпись ссылки. |
Подпись формируется из полного URL, отбрасывая только параметр sig . Ключом для подписи является секрет приложения. Алгоритм hmac_sha1 .
Шаг 2. Создание своего первого приложения
Управлять своими приложениями мы можем в разделе "Портал разработчика".
Клик на "Новое приложение" чтобы создать наше первое приложение. Введем название приложения и email для информационных рассылок. (Данные можно будет отредактировать)
Клик "Создать". Попадаем на экран настроек приложения.
Добавим иконку приложения
Переходим в раздел "Настройки аккаунта" -> "Интеграции"
Видим наше приложение. Установить его не получится, т.к мы не настроили OAuth авторизацию.
Обмен кода авторизации на access token и refresh token
Получив Authorization code, вам необходимо сделать запрос на специальный метод /oauth2/access_token, описанный ниже.
В ответ вы получите пару Access и Refresh token, а также время в секундах, через которое токен истекает.
AmoCRM одна из самых популярных CRM, при этом ее API один из самых странных, по моему субъективному мнению. Понадобилось передавать данные формы с сайта в crm. Использовать CRM Формы вместо своих дизайнерских не хочется. Было бы здорово открыть статейку в гугле, подставить ключ и не париться особо, но на удивление не нашел ни одной статьи с актуальной инфой, где-то версия api уже не актуальна, где-то вместо использования дефолтных полей контакта, создаются кастомные. В общем решил поделиться своим решением, для тех, кому сложно/лень вникать в их API.
В этой статье я буду создавать сделку в "Неразобранном", контакт и компанию.
embed_subject/src/index.html
2. Getting an Authorization code
Let us remind you that this is a key with a limited life-span (20 minutes) and with the help of it, you need to get a refresh token and access token before it’s lifespan runs out. It has a limited life-span because it can be stolen, but if stolen nothing can be done with it if the one who stole your Authorization code doesn’t have the keys of the application, that are known only to account administrators, in which the integration was created.
You can get the Authorization code in three ways:
- Copy from the modal window of the installed integration. This will work if you need to integrate only one account of amoCRM. Please check more on the question in Simplified Authorization.
- If your integration has a widget, then after installing it you will have a webhook sent to the Redirect URl
- Get the code after the user gets redirected to the Redirect URl
You can simplify development when getting a key via GET-parameters with the button amoCRM.
The full logic on how to get a key via GET-parameters is explained below:
- User, from which you need to get access from, on your site opens the link that you send to them Attention: It’s really important that for the user the whole process is understandable. When users click on the link, they need to understand that the request of the permissions will happen in their amoCRM account and they need to understand which integration they are trying to install.
That’s why we suggest that you use our branded button, a description of which you can find by this link Button.
Example of processing authorization, if a parameter post_message was sent
With sent GET-parameter mode with value post_message in the window to allow access – the redirect will happen in the same window. Below we will discuss examples of interaction between a modal window to allow access and main window using function postMessage.
The code below is from the main window:
Code below will be sent to the modal window from your backend server when the user gets to Redirect URl
After processing the code above, the main window will indicate the result.
We recommend closing the modal window automatically, how it was done in the example, this way users won’t get confused in windows.Создание объекта
Разработка директ-бота
Добавим нашей интеграции дополнительные скопы:
После изменения скопов, интеграцию нужно переустановить. Переходим в amo - мессенджер, удаляем и переустанавливаем интеграцию
Теперь в табе "Команда" нам будет доступен наш Бот.
Добавим ссылку и отметим галочкой событие messages
Создадим новый файл webhook.php и выведем в лог heroku тело запроса.
Закомитим правки, запушим. Дождемся сборки
Пропишем ссылку на вебхук в настройках приложения на портале разработчика
Снова напишем боту и посмотрим лог на стороне heroku
Подключим redis к нашему приложению на heroku
Добавим компонент predis/predis в менеджер зависимостей
Теперь доработаем скрипт, чтобы токен доступа писался в redis.
В скрипте обработки хука вытащим токен из редиса и запишем в лог
Закомитим правки, отправим в heroku и дождемся сборки
Теперь, переустановим приложение, чтобы токен сохранился в redis, и напишем боту.
Видим в логах наш токен.
Или сразу развернуть пример на heroku
4. Getting a new access token once it expires
From the previous section you may have noticed that with an Access token we get a Refresh token. It is required to continue working with API, when the action of the Access token is expiring, it’s pretty common action.
Refresh token has two duration limitations:
- The refresh token lifespan is 3 months. If an integration is not used in 3 months, no request was made to actualize the key, then the integration will lose access to data and it’s required to ask for permission from the user again.
- The refresh token can be changed only once. After sending it to the method and getting a new pair access token/refresh token the old refresh token becomes not actual. After getting the new refresh token you need to save it, otherwise, you’ll need to ask for permissions from the user again.
When the action lifespan expires, the possibility of getting an Access token from Refresh becomes impossible. To exchange it it is required to make a request on the special method with the actual Refresh token. In reply, you will get a new Access and Refresh tokens.
URL of the method
Parameter Description client_id Integration ID client_secret Secret of the integration grant_type Type of authorization data (for refresh token – refresh_token) refresh_token Refresh token redirect_uri Redirect URI indicated in integration settings Parameters of the reply
Parameter Description token_type Type of token (Bearer) expires_in Time in seconds, which shows in how much time the token will expire access_token Access token refresh_token Refresh token Example of a request
Example of a reply
Getting an Access token with Refresh token via bash
Getting an Access token with Authorization code via PHP
Response format
Status Body Description 200 Success, contains users information 200 Failure, problem+json 204 empty Users not found Деактивация пользователя
Деактивирует пользователя в аккаунте
3. Exchange of the Authorization Code to access token and refresh token
Parameter Description client_id Integration ID client_secret Secret of the integration grant_type Type of authorization data (for Authorization code – authorization_code) code Acquired code of authorization redirect_uri Redirect URI indicated in the integration settings Parameters of the reply
Parameter Description token_type Token type (Bearer) expires_in Time in seconds, which shows when the token will expire access_token Access token refresh_token Refresh token Example of a request
Example of a reply
Getting an access token with Authorization code via bash
Getting an access token with Authorization code via PHP
Читайте также: