AmoCRM api connector for Node.js
npm install amocrm-connectorИзначально библиотека создавалась для внутреннего использования. Периодически, с внесением изменений в amocrm api, в
интеграции появляются ошибки. Цель данного проекта помочь создать надежный, протестированный инструмент для работы с
amocrm. :ok_hand:
Поддерживать его актуальным с помощью автотестов и сообщества. Автоматические тесты запускаются каждый день с
использованием github actions.
Основная идея. Взаимодействие с api происходит с помощью двух объектов:
* Integration - объект создается на весь срок жизни приложения. Отвечает за методы интеграции в целом, а также обработку запросов со стороны amocrm.
* Client - объект для взаимодействия с конкретной установкой интеграции для аккаунта. Например, для http сервера объект создается на каждый входящий запрос.
По аналогии с основным api, api чатов разделено на 2 части:
* Channel - отвечает за обработку вебхуков, а также установку чата для аккаунта.
* Chat - экземпляр чата, установленный для аккаунта.
``shell`
yarn add amocrm-connector
`typescript
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, события описаны здесь
#### Методы
* getOAuthLink
* processOAuthRedirect
* on
* addListener
* removeListener
Объект является экземпляром EventEmitter, события описаны здесь
#### Методы
* tokenIsActual
* getToken
* request
* get
* post
* patch
* delete
* on
* addListener
* removeListener
#### Подсистемы
##### Аккаунт
###### Методы
* account.getAccountInfo
* account.getAmojoId
##### Звонки
###### Методы
Объект является экземпляром EventEmitter, события описаны здесь
#### Методы
* checkSignature
* request
* post
* delete
* connect
* disconnect
* processWebhook
* on
* removeListener
#### Методы
* addMessage
* deliveryStatus
* typing
Подробно про AmoCRM реализацию OAuth2 авторизации
в официальной документации
Также можете посмотреть видео от создателей другой
библиотеки https://github.com/UsefulWeb/AmoCRM.
Коротко, шаги:
1. Регистрация вашей интеграции
2. Переход пользователя по ссылке выдачи доступа пользователем вашему приложению. Ссылку получить можно
методом integration.getOAuthLinkexpress
3. Обработка запроса на redirect uri, для этого должен быть запущен ваш сервер. Необходимо вызвать (пример
для ) integration.processOAuthRedirect(req.query).integration
4. отправит в событие setup объект client. Процедура авторизации завершена (токен уже получен) и можно
пользоваться интеграцией.
Если в процессе использования вы обнаружили ошибку, расскажите о ней,
откройте issue с подробным описанием. Спасибо за помощь в
тестировании! :thumbsup: Если у вас есть пожелания, также
открывайте issue! :eyes:
* Покрыть все методы 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 и автоматического получения токена.yarn cypress:open
Необходимо:
* Настроить окружение. Токен сохраняется в testing/token.json. Про настройку окружения ниже.
* Запустить сервер для обработки запросов от amocrm.
* Создать туннель с публичного адреса на ваш локальный сервер.
* запуск cypress тестов в интерактивном режиме. Необходима настройка окружения.yarn jest
* запуск jest тестов. Для работы необходимо настроить окружение, а также токен в testing/token.json. Поэтомуyarn test
полезно сначала запустить cypress тест. [Пока тестов нет]
* запуск cypress и jest тестов
Необходимо создать файл .evn.test с переменными окружения в корне проекта. Для удобства можно воспользоваться.env.test.example
шаблоном (здесь также описано для чего нужны переменные)
`shell``
cp .env.test.example .env.test
Если у вас есть вопросы касательно разработки - пишите мне в телеграм @lybrus. :point_left:
Любая помощь в разработке и тестировании данного проекта приветствуется! :thumbsup: