README

AmoCRM

Javascript библиотека для работы с AmoCRM

Данная версия библиотеки поддерживает OAuth авторизацию и использует адреса AmoCRM API v4.

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

Поддержка AmoCRM API v4
Поддержка OAuth
Поддержка метода PATCH
Расширенная информация об ответе (статус ответа, время ответа и т.д)

Если вам нужна поддержка AmoCRM API v2, используйте версии 1.x.x данного пакета.

Установка

npm install amocrm-js

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

Подключение возможно:

По заранее известному коду авторизации (например, с помощью упрощённой авторизации)
С помощью встроенного OAuth-сервера (см. пример ниже)

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

Я снял для вас отдельное видео, ознакомьтесь с основами работы нового протокола и библиотеки: https://youtu.be/eK7xYAbxJHo

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

Его можно получить с помощью упрощенной авторизации или самостоятельно написанного обработчика адреса интеграции (redirectUri).

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 за возможность протестировать библиотеку в стороннем проекте

Usage no npm install needed!