NodeJS библиотека для работы с AmoCRM.
Документация: https://usefulweb.github.io/AmoCRM
Не предназначена для Frontend приложений
Поддерживает OAuth авторизацию и использует адреса AmoCRM API v4.
Сделайте библиотеку самой популярной в Галактике - поставьте Star ★!
По вопросам, в том числе сотрудничества пишите мне в Telegram.
YouTube-плейлист по AmoCRM и библиотеке
Сделаем вместе пространство уютным :) <3
- TypeScript исходная версия кода
- Подсветка синтаксиса на основе TS-интерфейсов
- Удобная передача GET-параметров
- Добавлен выброс ошибок приложения и API-запросов
- Добавлены новые события в компоненты приложения
- Возможность работы с сущностями через ООП
- Расширенная документация и примеры использования
- Сократился объем библиотеки
npm
npm install amocrm-js
Yarn
yarn add amocrm-js
const { Client } = require('amocrm-js');ES6:
import { Client } from 'amocrm-js'- Подключение к CRM
- Запросы к порталу
- Основные методы
- Компоненты
- Работа с событиями
- Обработка ошибок
- Сохранение авторизации между сессиями
- Переход с версии 2.x.x
Подключение возможно:
- Через долгосрочный токен
- По заранее известному коду авторизации (например, с помощью упрощённой авторизации)
- С помощью встроенного OAuth-сервера (см. пример ниже)
После успешного подключения клиент автоматически получает новый токен по истечению старого перед формированием запроса
- С помощью упрощённой авторизации
- С помощью встроенного сервера авторизации данной библиотеки
- Вручную
- Авторзоваться на сайте AmoCRM
- Получить код авторизации
- Получить OAuth-токен по коду авторизации
const client = new Client({
// логин пользователя в портале, где адрес портала 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', // Ссылка для перенаправления
bearer: 'ltsToken', // долгосрочный токен
},
});Его можно получить с помощью упрощенной авторизации или самостоятельно написанного обработчика адреса интеграции (redirectUri).
const client = new Client({
// логин пользователя в портале, где адрес портала 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', // Код для упрощённой авторизации, необязательный
},
});В AmoCRM API код авторизации можно использовать только один раз для получения токена. Последующие запросы на получение токена будут выдавать ошибку.
Чтобы облегчить процесс получения токена, в данный пакет встроен OAuth-сервер, который может обрабатывать указанный адрес перенаправления. Сервер включает прослушивание по необходимости и закрывает соединение по получению кода авторизации.
Пример настройки без параметра code:
const client = new Client({
// логин пользователя в портале, где адрес портала 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', // Ссылка для перенаправления,
/*
Необязательный араметр состояния для проверки на корректность.
Используется встроенным сервером авторизации.
см. https://www.amocrm.ru/developers/content/oauth/step-by-step#%D0%9F%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-Authorization-code
*/
state: 'state',
server: {
// порт, на котором запустится сервер авторизации
port: 3000
}
},
});- Сервер ожидает перехода пользователя по адресу: crm.auth.getUrl(mode)
- При успешном переходе пользователь перенаправляется на {redirectUri}, заданный в интеграции
- Сервер авторизации перехватывает запрос на {redirectUri} (как это сделать, описано ниже), извлекает код авторизации и с помощью crm.auth.setCode(code) автоматически получает токен для работы
Один из простых способ разработки интеграции: библиотека-сервис ngrok. Пакет перенаправляет трафик с вашего компьютера на заданный публичный IP, который можно задать в адресе интеграции.
Для работы сервера авторизации на «боевом» хостинге ему нужно выполнение условий:
- Публичный IP-адрес, на котором находится проект
- Порт сервера авторизации, указанный в настройках данной библиотеки (auth.server.port), открыт для внешних подключений или работает прокси-переадресация в настройках виртуального хоста.
После остаётся только заменить адрес {redirectUri} на адрес вашего хоста в настройках библиотеки и интеграции.
const client = new Client({
// ...
auth: {
// ...
redirect_uri: 'redirectUri',
server: {
port: 3001
}
},
});Фабрики позволяют управлять порталом в ООП стиле.
- Используйте готовые методы вместо API-адресов
- Перебирайте сделки, контакты и пр. с помощью постраничной навигации
const lead = new client.Lead;
lead.name = 'Евгений Иванов';
await lead.save();const lead = client.leads.getById(123);
lead.name = 'Walter Scott';
await lead.save();const pagination = await client.leads.get({
order: 'created_at',
});
const leads = pagination.getData();
await pagination.next();В настоящий момент библиотека поддерживает фабрики:
- Сделки [примеры работы]
- Контакты [примеры работы]
- Компании [примеры работы]
- Теги [примеры работы]
- Задачи [примеры работы]
С указанием метода:
const result = await client.request.make('GET', '/api/v4/account');
// возвращает тело ответа
console.log(result.data);
/*
Возвращает расширенную информацию об ответе -
экземпляр http.IncomingMessage:
https://nodejs.org/api/http.html#class-httpincomingmessage
*/
console.log(result.response);
// к примеру, HTTP-статус ответа операции
console.log(result.response.statusCode);const response = await client.request.get('/api/v4/contacts')С помощью querystring:
const response = await client.request.get('/api/v4/contacts?with=version');объектом:
const response = await client.request.get('/api/v4/contacts', {
with: 'version'
});const response = await client.request.post('/api/v4/contacts', [
{
name: "Walter White",
request_id: 143,
// другие поля ...
}
]
);const response = await client.request.patch('/api/v4/leads', [
{
"id": 54886,
"pipeline_id": 47521,
"status_id": 143,
"date_close": 1589297221,
"loss_reason_id": 7323,
"updated_by": 0
}
]
)В нём хранятся все переданные ранее настройки
Получить настройки, переданные конструктору Client
const { Client } = require('amocrm-js');
const client = new Client({
// логин пользователя в портале, где адрес портала 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', // Код для упрощённой авторизации, необязательный
/*
Параметр состояния для проверки на корректность. Необязательный. Используется встроенным сервером авторизации
см. https://www.amocrm.ru/developers/content/oauth/step-by-step#%D0%9F%D0%BE%D0%BB%D1%83%D1%87%D0%B5%D0%BD%D0%B8%D0%B5-Authorization-code
*/
state: 'state',
},
});
client.environment.get(); // возвращает весь объект настроек
client.environment.get('domain'); // 'domain';
client.environment.get('auth.redirect_uri'); // 'redirectUri'Устанавливает новое значение в окружении
client.environment.set('auth.state', 'newsState');Получает токен на основе (в зависимости от ситуации):
- Кода авторизации (config.auth.code)
- Старого токена, если он истёк (refresh_token)
- Кода авторизации, полученного с помощью перехода пользователя по ссылке. Использует встроенный сервер авторизации
- check. Проверка
- beforeConnect. Возникает перед началом соединения
- connected. Успешное соединение
- connectionError. Ошибка соединения
- authServer:code. Успешное получение кода авторизации
- authServer:listen. Начало работы сервера авторизации
- authServer:close. Сервер авторизации завершает прослушивать сооб
- authServer:serverError. Ошибка сервера авторизации
client.connection.on('connectionError', () => {
console.error('Произошла ошибка соединения');
})Возвращает адрес ссылки на портал AmoCRM, по которой должен перейти пользователь для получения кода авторизации.
Параметр mode отвечает за обработку запроса на Redirect URI.
- popup – окно авторизации будет закрыто, а переход на Redirect URI будет выполнен в основном окне.
- post_message – перенаправление произойдет в окне, которое было открыто, после обработки кода авторизации вам нужно закрыть окно
Устанавливает код авторизации и удаляет информацию о текущем токене. Желательно применять именно этот метод в сравнение с client.environment.set('auth.code');
Устанавливает новое значение токена.
Возвращает текущее значение токена.
Обновляет токен по значению refresh_token текущего. Явно вызывать нет необходимости, так как при каждом запросе идёт проверка токена на актуальность. Если время жизни токена истекло, этот метод будет вызван автоматически.
После обновления, токен автоматически устанавливается в приложении.
Получение токена по коду авторизации. После обновления, токен автоматически устанавливается в приложении.
- beforeChange. Возникает после получения по API токена и до того как он будет установлен в приложении
- change. Возникает после установления нового значения в приложении
- expirationCheck. Возникает при проверке актуальности токена
- beforeFetch. Возникает перед попыткой получения токена по коду авторизации
- fetch. Возникает после получения токена по коду авторизации
- beforeRefresh. Возникает перед попыткой обновления токена по значению refresh_token текущего
- refresh. Возникает после получения нового токена по значению refresh_token старого
client.token.on('change', () => {
console.error('Токен обновлён');
})Компоненты Auth, Token, Connection унаследованы от класса EventEmitter. То есть они все поддерживают методы подписки на события (on, off, removeAllListeners) и отписки от них, принятые в EventEmitter.
- NO_JSON_RESPONSE. Пустой ответ
- INVALID_JSON_RESPONSE. Некорректный JSON ответ
- API_RESPONSE_ERROR. Ошибка в ответе по API
- NO_TOKEN_AND_CODE. В настройках отсуствует код и не установлен токен
- PATH_IS_EMPTY. Попытка вызвать client.environment.set без переданного пути
- INVALID_PATH. Неверный путь при вызове client.environment.set
- NO_AUTH_OPTIONS. Отсутствуют настройки config.auth
- JSON_PARSE_ERROR. Ответ AmoCRM сформирован в неверном JSON формате
Может быть полезным сохранять авторизацию между запусками приложения. Для этого есть событие change
компонента client.token, в которое приходит новый токен при каждом сохранении.
Этот токен можно сохранять куда вам удобно (БД, файлы и тд). При инициализации соединения можно заранее установить токен для восстановления авторизации:
crm.token.setValue(currentToken)
Пример реализации через сохранение в файл
- client.connect -> client.connection.connect
- client.request(method, path, params, options) -> client.request.make(method, path, params, options)
- client.connection.getAuthUrl() -> client.auth.getUrl()
- client.connection.setState(state) -> client.environment.set('auth.state', state)
- client.connection.getState() -> client.environment.get('auth.state')
- client.connection.getToken() -> client.token.getValue()
- client.connection.setToken(token) -> client.token.setValue(token)
- client.connection.refreshToken() -> client.token.refresh()
Замена: client.auth.setCode(code)
Вызов этого метода в версии 2.x.x приводит к обновлению токена по только что заданному коду.
В текущей версии это происходит при последующем запросе к API. Старая версия эквивалентна:
client.auth.setCode(code);
await client.connection.connect();- client.on('connection:beforeConnect') -> client.connection.on('beforeConnect')
- client.on('connection:beforeFetchToken') -> client.token.on('beforeFetch')
- client.on('connection:beforeRefreshToken') -> client.token.on('beforeRefresh')
- client.on('connection:checkToken') -> client.token.on('expirationCheck')
- client.on('connection:authError') -> client.connection.on('connectionError')
- client.on('connection:connected') -> client.connection.on('connected')
- client.on('connection:error') -> client.connection.on('connectionError')
- client.on('connection:newToken') -> client.token.on('change')
Общее:
Работа с фабриками:
- Сделки [примеры работы]
- Контакты [примеры работы]
- Компании [примеры работы]
- Теги [примеры работы]
- Задачи [примеры работы]
Спасибо @amorev, @maxism, @shuraman69, @korovenko-tatyana, @lotgyero, @capfsb, @templar820 за вклад в разработку этого проекта
Отдельная благодарность @dmitrytemlead за возможность протестировать библиотеку в стороннем проекте
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent