const AmoCRM = require( 'amocrm-js' );

const crm = new AmoCRM({
    // логин пользователя в портале, где адрес портала domain.amocrm.ru
    domain: 'domain', // может быть указан полный домен вида domain.amocrm.ru, domain.amocrm.com
    /* 
      Информация об интеграции (подробности подключения 
      описаны на https://www.amocrm.ru/developers/content/oauth/step-by-step)
    */
    auth: {
      client_id: 'clientId', // ID интеграции
      client_secret: 'clientSecret', // Секретный ключ
      redirect_uri: 'redirectUri', // Ссылка для перенаправления
      code: 'code' // Код авторизации
    },
});

Встроенный OAuth-сервер

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

Чтобы облегчить процесс получения токена, в данный пакет встроен OAuth-сервер, который может обрабатывать указанный адрес перенаправления.

Пример настройки без параметра code:

const AmoCRM = require( 'amocrm-js' );

const crm = new AmoCRM({
    // логин пользователя в портале, где адрес портала domain.amocrm.ru
    domain: 'domain', // может быть указан полный домен вида domain.amocrm.ru, domain.amocrm.com
    /* 
      Информация об интеграции (подробности подключения 
      описаны на https://www.amocrm.ru/developers/content/oauth/step-by-step)
    */
    auth: {
      client_id: 'clientId', // ID интеграции
      client_secret: 'clientSecret', // Секретный ключ
      redirect_uri: 'redirectUri', // Ссылка для перенаправления,
      server: {
        // порт, на котором запустится сервер авторизации
        port: 3000
      }
    },
});

Как выглядит процесс авторизации:

Сервер ожидает перехода пользователя по адресу: crm.connection.getAuthUrl(mode)
При успешном переходе пользователь перенаправляется на {redirectUri}, заданный в интеграции
Сервер авторизации перехватывает запрос на {redirectUri} (как это сделать, описано ниже), извлекает код авторизации и с помощью crm.connection.setCode(code) автоматически получает токен для работы

Использование в целях разработки

Один из простых способ разработки интеграции: библиотека-сервис ngrok. Пакет перенаправляет трафик с вашего компьютера на заданный публичный IP, который можно задать в адресе интеграции.

После установки пакета:

Выполните в терминале команду: ngrok http 3001
Полученный в результат адрес вида https://311e923c5281.ngrok.io указываем в настройках интеграции AmoCRM
В настройках указываем номер порта (в нашем примере 3001) и полученный ngrok-адрес в {auth.redirect_uri}
Получаем адрес ссылке, по которой необходимо будет перейти через crm.connection.getAuthUrl()
Переходим по ссылке, после этого код автоматически установится и библиотека запросит новый токен

Пример настроек:

const crm = new AmoCRM({
    // ...
    auth: {
      // ...
      redirect_uri: 'https://311e923c5281.ngrok.io',
      server: {
        port: 3001
      }
    },
});

Разработка на production-сервере

Для работы сервера авторизации на «боевом» хостинге ему нужно выполнение условий:

Публичный IP-адрес, на котором находится проект
Порт сервера авторизации, указанный в настройках данной библиотеки (auth.server.port), открыт для внешних подключений или работает прокси-переадресация в настройках виртуального хоста.

После остаётся только заменить адрес {redirectUri} на адрес вашего хоста в настройках библиотеки и интеграции.

Запросы к порталу

С указанием метода:


const response = await crm.request( 'GET', '/api/v4/account' );
// возвращает тело ответа 
console.log( response.data );
/* 
  Возвращает расширенную информацию об ответе - 
  экземпляр http.ServerResponse:
  https://nodejs.org/api/http.html#http_class_http_serverresponse

*/
console.log( response.info );
// к примеру, HTTP-статус ответа операции
console.log( response.info.statusCode );

Методы crm.request: get, post, patch

const response = await crm.request.get( '/api/v4/contacts')

const response = await crm.request
    .post( '/api/v4/contacts', 
      [
        {
          name: "Walter White",
          request_id: 143,
          // другие поля ...
        }
      ]
    )

const response = await crm.request
  .patch( '/api/v4/leads',
    [
      {
        "id": 54886,
        "pipeline_id": 47521,
        "status_id": 143,
        "date_close": 1589297221,
        "loss_reason_id": 7323,
        "updated_by": 0
      }
    ]
  )

OAuth

Клиент автоматически получает новый токен по истечению старого (при необходимости).

Методы:

crm.connection.setCode(code) - устанавливает код авторизации и получает токен авторизации.
crm.connection.refreshToken() - получает новый токен на основе текущего (по полю refresh_token). Вызывается автоматически при необходимости обновления.
crm.connection.getAuthUrl(mode) - возвращает адрес ссылки, по которой должен перейти пользователь. Параметр mode отвечает за обработку запроса на Redirect URI. В случае popup – окно авторизации будет закрыто, а переход на Redirect URI будет выполнен в основном окне. В случае передачи значения post_message – перенаправление произойдет в окне, которое было открыто, после обработки кода авторизации вам нужно закрыть окно
crm.connection.setState(state) - задаёт произвольную строку состояния (используется для проверки подлинности во встроенном сервере авторизации)
crm.connection.getState(state) - возвращает строку состояния
crm.connection.getToken() - возвращает текущий токен авторизации
crm.connection.setToken( token ) - задаёт токен авторизации. Токен должен включать поле expires_at (timestamp, когда токен истечёт)

Работа с событиями

В настоящий момент доступны следующие события:

connection:beforeConnect
connection:beforeFetchToken
connection:beforeRefreshToken
connection:checkToken
connection:authError
connection:connected
connection:error
connection:newToken

Добавление обработчика:

crm.on( 'connection:error', () => console.log( 'Ошибка соединения' ));

Удаление обработчика:

const handler = () => console.log( 'Ошибка соединения' );
crm.on( 'connection:error', handler );

// удалить конкретный обработчик
crm.off( 'connection:error', handler );

// удалить все обработчики конкретного события
crm.off( 'connection:error' );

// удалить все обработчики всех событий
crm.off();

Сохранение авторизации между сессиями

Может быть полезным сохранять авторизацию между запусками приложения. Для этого есть событие connection:newToken, в которое приходит новый токен при каждом сохранении.

Этот токен можно сохранять куда вам удобно (БД, файлы и тд). При инициализации соединения можно заранее установить токен для восстановления авторизации: crm.connection.setToken( currentToken )

Ниже пример реализации через сохранение в файл token.json который лежит рядом со скриптом

  crm.on( 'connection:newToken', response => {
    fs.writeFileSync( './token.json', JSON.stringify( response.data ));
  });
  try {
    const currentToken = require( './token.json' );
    crm.connection.setToken( currentToken );
  } catch (e) {
    // Token file not found
  }

Доска почёта

Спасибо @amorev, @maxism за вклад в разработку этого проекта

Отдельная благодарность @dmitrytemlead за возможность протестировать библиотеку в стороннем проекте

Keywords

FAQs

What is amocrm-js?

Is amocrm-js popular?

Is amocrm-js well maintained?

Package last updated on 13 May 2022

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

amocrm-js

AmoCRM

Изменения в 2.x.x по сравнению с 1.x.x

Установка

Подключение к CRM

Что такое OAuth и как всё настроить?

Код авторизации известен