Node.js AmoCRM api connector
Изначально библиотека создавалась для внутреннего использования. Периодически, с внесением изменений в amocrm api, в интеграции появляются ошибки. Цель данного проекта помочь создать надежный, протестированный инструмент для работы с amocrm. 👌 Поддерживать его актуальным с помощью автотестов и сообщества. Автоматические тесты запускаются каждый день с использованием github actions.
Основная идея. Взаимодействие с api происходит с помощью двух объектов:
Integration
- объект создается на весь срок жизни приложения. Отвечает за методы интеграции в целом, а также обработку запросов со стороны amocrm.Client
- объект для взаимодействия с конкретной установкой интеграции для аккаунта. Например, для http сервера объект создается на каждый входящий запрос.
По аналогии с основным api, api чатов разделено на 2 части:
Channel
- отвечает за обработку вебхуков, а также установку чата для аккаунта.Chat
- экземпляр чата, установленный для аккаунта.
yarn add amocrm-connector
import { Integration, Client, Channel, Chat, MessageType } from 'amocrm-connector'
import token from './token.json'
;(async () => {
const integration = new Integration({
integrationId: 'integration id',
secretKey: 'secret key',
redirectUri: 'redirect uri'
})
const client = new Client({
integration,
subdomain: 'your_subdomain',
token
})
const channel = new Channel({
chatId: 'chat id',
chatSecret: 'chat secret',
title: 'channel title'
})
const chat = await channel.connect(client)
const result = await chat.addMessage({
date: new Date(),
// id беседы из вашей системы
conversationId: 'conversation-id',
sender: {
id: 'sender-id',
name: 'Имя клиента',
profile: {
phone: '0123456789'
}
},
id: 'message-id',
message: {
type: MessageType.Text,
text: 'Тест сообщения'
}
}
)
})()
Другие примеры смотрите в папке examples
Объект является экземпляром EventEmitter
, события описаны здесь
Объект является экземпляром EventEmitter
, события описаны здесь
Объект является экземпляром EventEmitter
, события описаны здесь
Подробно про AmoCRM реализацию OAuth2 авторизации в официальной документации Также можете посмотреть видео от создателей другой библиотеки https://github.com/UsefulWeb/AmoCRM.
Коротко, шаги:
- Регистрация вашей интеграции
- Переход пользователя по ссылке выдачи доступа пользователем вашему приложению. Ссылку получить можно
методом
integration.getOAuthLink
- Обработка запроса на redirect uri, для этого должен быть запущен ваш сервер. Необходимо вызвать (пример
для
express
)integration.processOAuthRedirect(req.query)
. integration
отправит в событиеsetup
объектclient
. Процедура авторизации завершена (токен уже получен) и можно пользоваться интеграцией.
Если в процессе использования вы обнаружили ошибку, расскажите о ней, откройте issue с подробным описанием. Спасибо за помощь в тестировании! 👍 Если у вас есть пожелания, также открывайте issue! 👀
- Покрыть все методы api
- Реализовать унифицированный механизм работы с сущностями (Leads, Contacts, Pipelines, Companies, Catalogs, ...)
- create(data: DTOWithId | DTOWithId[])
- find(type: typeof DTOWithId, findOptions)
- findOne(type: typeof DTOWithId, findOptionsOrId)
- update(data: DTOWithId | DTOWithId[])
- delete(data: DTOWithId | DTOWithId[])
- Валидация DTO
yarn build
сборка проектаyarn serve
запуск сервера для обработки запросов от amocrm. Необходима настройка окружения.yarn tunnel
создает туннель с использованием утилиты localtunnel. Необходима настройка окружения.yarn cypress
запуск cypress тестов, используется для проверки работы OAuth и автоматического получения токена. Необходимо:- Настроить окружение. Токен сохраняется в testing/token.json. Про настройку окружения ниже.
- Запустить сервер для обработки запросов от amocrm.
- Создать туннель с публичного адреса на ваш локальный сервер.
yarn cypress:open
запуск cypress тестов в интерактивном режиме. Необходима настройка окружения.yarn jest
запуск jest тестов. Для работы необходимо настроить окружение, а также токен в testing/token.json. Поэтому полезно сначала запустить cypress тест. [Пока тестов нет]yarn test
запуск cypress и jest тестов
Необходимо создать файл .evn.test
с переменными окружения в корне проекта. Для удобства можно воспользоваться
шаблоном .env.test.example
(здесь также описано для чего нужны переменные)
cp .env.test.example .env.test
Если у вас есть вопросы касательно разработки - пишите мне в телеграм @lybrus. 👈
Любая помощь в разработке и тестировании данного проекта приветствуется! 👍