AmoCRM api connector
Node.jsИзначально библиотека создавалась для внутреннего использования. Периодически, с внесением изменений в amocrm api, в
интеграции появляются ошибки. Цель данного проекта помочь создать надежный, протестированный инструмент для работы с
amocrm.
Описание
Основная идея. Взаимодействие с api происходит с помощью двух объектов:
-
Integration
- объект создается на весь срок жизни приложения. Отвечает за методы интеграции в целом, а также обработку запросов со стороны amocrm. -
Client
- объект для взаимодействия с конкретной установкой интеграции для аккаунта. Например, для http сервера объект создается на каждый входящий запрос.
Api чатов
По аналогии с основным 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
Документация
Integration
Объект является экземпляром EventEmitter
, события описаны здесь
Методы
Client
Объект является экземпляром EventEmitter
, события описаны здесь
Методы
Подсистемы
Аккаунт
Методы
Channel
Объект является экземпляром EventEmitter
, события описаны здесь
Методы
Chat
Методы
Авторизация
Подробно про AmoCRM реализацию OAuth2 авторизации в официальной документации Также можете посмотреть видео от создателей другой библиотеки https://github.com/UsefulWeb/AmoCRM.
Коротко, шаги:
- Регистрация вашей интеграции
- Переход пользователя по ссылке выдачи доступа пользователем вашему приложению. Ссылку получить можно
методом
integration.getOAuthLink
- Обработка запроса на redirect uri, для этого должен быть запущен ваш сервер. Необходимо вызвать (пример
для
express
)integration.processOAuthRedirect(req.query)
. -
integration
отправит в событиеsetup
объектclient
. Процедура авторизации завершена (токен уже получен) и можно пользоваться интеграцией.
Ошибки и пожелания
Если в процессе использования вы обнаружили ошибку, расскажите о ней,
откройте 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.
Любая помощь в разработке и тестировании данного проекта приветствуется!