{"id":18594995,"url":"https://github.com/usefulweb/amocrm","last_synced_at":"2025-04-05T21:11:41.942Z","repository":{"id":37484630,"uuid":"69348381","full_name":"UsefulWeb/AmoCRM","owner":"UsefulWeb","description":"Javascript библиотека для работы с AmoCRM","archived":false,"fork":false,"pushed_at":"2024-04-10T08:31:12.000Z","size":3774,"stargazers_count":148,"open_issues_count":4,"forks_count":26,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-04-10T09:57:06.845Z","etag":null,"topics":["amo","amocrm","crm","javascript-amocrm"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UsefulWeb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2016-09-27T11:09:25.000Z","updated_at":"2024-05-13T18:20:13.978Z","dependencies_parsed_at":"2024-01-11T13:37:16.129Z","dependency_job_id":"ac3347a3-1662-4882-b317-018e30885f66","html_url":"https://github.com/UsefulWeb/AmoCRM","commit_stats":{"total_commits":200,"total_committers":5,"mean_commits":40.0,"dds":0.06499999999999995,"last_synced_commit":"6e396893ccef7a95c6a25afbd214b304f1336970"},"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UsefulWeb%2FAmoCRM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UsefulWeb%2FAmoCRM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UsefulWeb%2FAmoCRM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UsefulWeb%2FAmoCRM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UsefulWeb","download_url":"https://codeload.github.com/UsefulWeb/AmoCRM/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247399886,"owners_count":20932880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amo","amocrm","crm","javascript-amocrm"],"created_at":"2024-11-07T01:17:59.797Z","updated_at":"2025-04-05T21:11:41.910Z","avatar_url":"https://github.com/UsefulWeb.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# AmoCRM\n\n[![npm version](https://img.shields.io/npm/v/amocrm-js.svg?style=flat-square)](https://github.com/UsefulWeb/AmoCRM/stargazers)\n[![GitHub stars](https://img.shields.io/github/stars/UsefulWeb/AmoCRM)](https://github.com/UsefulWeb/AmoCRM/stargazers)\n[![GitHub license](https://img.shields.io/github/license/UsefulWeb/AmoCRM)](https://github.com/UsefulWeb/AmoCRM/blob/master/LICENSE)\n\nNodeJS библиотека для работы с AmoCRM.\n\nДокументация: https://usefulweb.github.io/AmoCRM\n\n__Не предназначена для Frontend приложений__\n\nПоддерживает OAuth авторизацию и использует адреса AmoCRM API v4.\n\nСделайте библиотеку самой популярной в Галактике - поставьте Star ★!\n\nПо вопросам, в том числе сотрудничества  [пишите мне в Telegram](https://t.me/neizerth).\n\n## Сообщество и вопросы\n\n[YouTube-плейлист по AmoCRM и библиотеке](https://www.youtube.com/playlist?list=PLcMMJHB8iEYmoNo5PnSjv8286zzMw4bdq)\n\nСделаем вместе пространство уютным :) \u003c3\n\n## Изменения в 3.x.x по сравнению с 2.x.x\n\n1. TypeScript исходная версия кода\n2. Подсветка синтаксиса на основе TS-интерфейсов\n3. Удобная передача GET-параметров\n4. Добавлен выброс ошибок приложения и API-запросов\n5. Добавлены новые события в компоненты приложения\n6. Возможность работы с сущностями через ООП\n7. Расширенная документация и примеры использования\n8. Сократился объем библиотеки\n\n## Установка\n\nnpm\n```\nnpm install amocrm-js\n```\n\nYarn\n```\nyarn add amocrm-js\n```\n\n## Использование\n\n```js\nconst { Client } = require('amocrm-js');\n```\n\n\nES6:\n\n```js\nimport { Client } from 'amocrm-js'\n```\n\n## Содержание\n\n1. [Подключение к CRM](#connection)\n2. [Запросы к порталу](#requests)\n3. [Основные методы](#request-methods)\n4. [Компоненты](#components)\n5. [Работа с событиями](#events)\n6. [Обработка ошибок](#errors)\n7. [Сохранение авторизации между сессиями](#session)\n8. [Переход с версии 2.x.x](#v2-migration)\n\n\u003ca id=\"connection\"\u003e\u003c/a\u003e\n## Подключение к CRM\n\nПодключение возможно:\n\n1. Через [долгосрочный токен](https://www.amocrm.ru/developers/content/oauth/step-by-step#%D0%94%D0%BE%D0%BB%D0%B3%D0%BE%D1%81%D1%80%D0%BE%D1%87%D0%BD%D1%8B%D0%B5-%D1%82%D0%BE%D0%BA%D0%B5%D0%BD%D1%8B)\n2. По заранее известному коду авторизации\n   (например, с помощью [упрощённой авторизации](https://www.amocrm.ru/developers/content/oauth/easy-auth))\n2. С помощью встроенного OAuth-сервера (см. пример ниже)\n\nПосле успешного подключения клиент автоматически получает новый токен\nпо истечению старого перед формированием запроса\n\n### Получение кода авторизацию\n\n1. С помощью [упрощённой авторизации](https://www.amocrm.ru/developers/content/oauth/easy-auth)\n2. С помощью встроенного сервера авторизации данной библиотеки\n3. Вручную\n\n### Процесс OAuth авторизации\n\n1. Авторзоваться на сайте AmoCRM\n2. Получить код авторизации\n3. Получить OAuth-токен по коду авторизации\n\n### Подключение по долгосрочному токену\n\n```js\nconst client = new Client({\n    // логин пользователя в портале, где адрес портала domain.amocrm.ru\n    domain: 'domain', // может быть указан полный домен вида domain.amocrm.ru, domain.amocrm.com\n    /* \n      Информация об интеграции (подробности подключения \n      описаны на https://www.amocrm.ru/developers/content/oauth/step-by-step)\n    */\n    auth: {\n      client_id: 'clientId', // ID интеграции\n      client_secret: 'clientSecret', // Секретный ключ\n      redirect_uri: 'redirectUri', // Ссылка для перенаправления\n      bearer: 'ltsToken', // долгосрочный токен\n    },\n});\n```\n\n### Подключение по коду авторизации (упрощенная авторизация)\n\nЕго можно получить с помощью упрощенной авторизации или самостоятельно написанного обработчика\nадреса интеграции (redirectUri).\n\n```js\nconst client = new Client({\n    // логин пользователя в портале, где адрес портала domain.amocrm.ru\n    domain: 'domain', // может быть указан полный домен вида domain.amocrm.ru, domain.amocrm.com\n    /* \n      Информация об интеграции (подробности подключения \n      описаны на https://www.amocrm.ru/developers/content/oauth/step-by-step)\n    */\n    auth: {\n      client_id: 'clientId', // ID интеграции\n      client_secret: 'clientSecret', // Секретный ключ\n      redirect_uri: 'redirectUri', // Ссылка для перенаправления\n      code: 'code', // Код для упрощённой авторизации, необязательный\n    },\n});\n```\n\n### Подключение через OAuth-сервер\n\nВ AmoCRM API код авторизации можно использовать __только один раз__ для получения\nтокена. Последующие запросы на получение токена будут выдавать ошибку.\n\nЧтобы облегчить процесс получения токена, в данный пакет встроен OAuth-сервер,\nкоторый может обрабатывать указанный адрес перенаправления. Сервер включает прослушивание по необходимости\nи закрывает соединение по получению кода авторизации.\n\nПример настройки без параметра *code*:\n\n```js\nconst client = new Client({\n    // логин пользователя в портале, где адрес портала domain.amocrm.ru\n    domain: 'domain', // может быть указан полный домен вида domain.amocrm.ru, domain.amocrm.com\n    /* \n      Информация об интеграции (подробности подключения \n      описаны на https://www.amocrm.ru/developers/content/oauth/step-by-step)\n    */\n    auth: {\n        client_id: 'clientId', // ID интеграции\n        client_secret: 'clientSecret', // Секретный ключ\n        redirect_uri: 'redirectUri', // Ссылка для перенаправления,\n        /*\n            Необязательный араметр состояния для проверки на корректность. \n            Используется встроенным сервером авторизации.\n            см. 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\n        */\n        state: 'state',\n        server: {\n            // порт, на котором запустится сервер авторизации\n            port: 3000\n        }\n    },\n});\n```\n\n#### Процесс авторизации:\n\n1. Сервер ожидает перехода пользователя по адресу: *crm.auth.getUrl(mode)*\n2. При успешном переходе пользователь перенаправляется на {redirectUri}, заданный в интеграции\n3. Сервер авторизации перехватывает запрос на {redirectUri}\n   (как это сделать, описано ниже), извлекает код авторизации и\n   с помощью *crm.auth.setCode(code)* автоматически получает токен для работы\n\n#### Использование в целях разработки\n\nОдин из простых способ разработки интеграции: библиотека-сервис [ngrok](https://ngrok.com).\nПакет перенаправляет трафик с вашего компьютера на заданный публичный IP, который можно задать в\nадресе интеграции.\n\n[Пример использования ngrok.](examples/javascript/00-oauth/001-get-token-with-server.js)\n\n#### Разработка на production-сервере\n\nДля работы сервера авторизации на «боевом» хостинге ему нужно выполнение условий:\n\n1. Публичный IP-адрес, на котором находится проект\n2. Порт сервера авторизации, указанный в настройках данной библиотеки (*auth.server.port*),\n   открыт для внешних подключений или работает прокси-переадресация в настройках виртуального хоста.\n\nПосле остаётся только заменить адрес {redirectUri} на адрес\nвашего хоста в настройках библиотеки и интеграции.\n\n```js\nconst client = new Client({\n // ...\n auth: {\n  // ...\n  redirect_uri: 'redirectUri',\n  server: {\n   port: 3001\n  }\n },\n});\n```\n\n\u003ca id=\"factories\"\u003e\u003c/a\u003e\n## Фабрики\n\nФабрики позволяют управлять порталом в ООП стиле.\n\n- Используйте готовые методы вместо API-адресов\n- Перебирайте сделки, контакты и пр. с помощью постраничной навигации\n\n```js\nconst lead = new client.Lead;\nlead.name = 'Евгений Иванов';\n\nawait lead.save();\n```\n\n```js\nconst lead = client.leads.getById(123);\nlead.name = 'Walter Scott';\nawait lead.save();\n```\n\n```js\nconst pagination = await client.leads.get({\n   order: 'created_at',\n});\nconst leads = pagination.getData();\nawait pagination.next();\n```\n\nВ настоящий момент библиотека поддерживает фабрики:\n\n- Сделки [[примеры работы]](./examples/javascript/01-leads)\n- Контакты [[примеры работы]](./examples/javascript/02-contacts)\n- Компании [[примеры работы]](./examples/javascript/03-companies)\n- Теги [[примеры работы]](./examples/javascript/04-tags)\n- Задачи [[примеры работы]](./examples/javascript/05-tasks)\n\n\u003ca id=\"requests\"\u003e\u003c/a\u003e\n## Запросы к порталу\n\nС указанием метода:\n\n```js\nconst result = await client.request.make('GET', '/api/v4/account');\n// возвращает тело ответа \nconsole.log(result.data);\n/* \n  Возвращает расширенную информацию об ответе - \n  экземпляр http.IncomingMessage:\n  https://nodejs.org/api/http.html#class-httpincomingmessage\n*/\nconsole.log(result.response);\n// к примеру, HTTP-статус ответа операции\nconsole.log(result.response.statusCode);\n```\n\n\u003ca id=\"request-methods\"\u003e\u003c/a\u003e\n## Методы *client.request*: GET, POST, PATCH\n\n### GET\n\n```js\nconst response = await client.request.get('/api/v4/contacts')\n```\n\n#### Передача параметров\n\nС помощью querystring:\n\n```js\nconst response = await client.request.get('/api/v4/contacts?with=version');\n```\n\nобъектом:\n```js\nconst response = await client.request.get('/api/v4/contacts', {\n with: 'version'\n});\n```\n\n### POST\n\n```js\nconst response = await client.request.post('/api/v4/contacts', [\n    {\n      name: \"Walter White\",\n      request_id: 143,\n      // другие поля ...\n    }\n  ]\n);\n```\n\n### PATCH\n\n```js\nconst response = await client.request.patch('/api/v4/leads', [\n     {\n       \"id\": 54886,\n       \"pipeline_id\": 47521,\n       \"status_id\": 143,\n       \"date_close\": 1589297221,\n       \"loss_reason_id\": 7323,\n       \"updated_by\": 0\n     }\n   ]\n )\n```\n\n\u003ca id=\"components\"\u003e\u003c/a\u003e\n## Компоненты\n\n### client.environment\n\nВ нём хранятся все переданные ранее настройки\n\n#### client.environment.get(path?)\n\nПолучить настройки, переданные конструктору Client\n\n```js\nconst { Client } = require('amocrm-js');\n\nconst client = new Client({\n    // логин пользователя в портале, где адрес портала domain.amocrm.ru\n    domain: 'domain', // может быть указан полный домен вида domain.amocrm.ru, domain.amocrm.com\n    /* \n      Информация об интеграции (подробности подключения \n      описаны на https://www.amocrm.ru/developers/content/oauth/step-by-step)\n    */\n    auth: {\n      client_id: 'clientId', // ID интеграции\n      client_secret: 'clientSecret', // Секретный ключ\n      redirect_uri: 'redirectUri', // Ссылка для перенаправления\n      code: 'code', // Код для упрощённой авторизации, необязательный\n      /*\n        Параметр состояния для проверки на корректность. Необязательный. Используется встроенным сервером авторизации\n        см. 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\n      */\n      state: 'state',\n    },\n});\n\nclient.environment.get(); // возвращает весь объект настроек\nclient.environment.get('domain'); // 'domain';\nclient.environment.get('auth.redirect_uri'); // 'redirectUri'\n```\n\n#### client.environment.set(path, value)\n\nУстанавливает новое значение в окружении\n\n```js\nclient.environment.set('auth.state', 'newsState');\n```\n\n### client.connection\n\n#### client.connection.connect()\n\nПолучает токен на основе (в зависимости от ситуации):\n1. Кода авторизации (config.auth.code)\n2. Старого токена, если он истёк (refresh_token)\n3. Кода авторизации, полученного с помощью перехода пользователя по ссылке. Использует встроенный сервер авторизации\n\n#### client.connection.update()\n\n#### События\n\n- check. Проверка\n- beforeConnect. Возникает перед началом соединения\n- connected. Успешное соединение\n- connectionError. Ошибка соединения\n- authServer:code. Успешное получение кода авторизации\n- authServer:listen. Начало работы сервера авторизации\n- authServer:close. Сервер авторизации завершает прослушивать сооб\n- authServer:serverError. Ошибка сервера авторизации\n\n```js\nclient.connection.on('connectionError', () =\u003e {\n    console.error('Произошла ошибка соединения');\n})\n```\n\n### client.auth\n\n#### client.auth.getUrl(mode)\n\nВозвращает адрес ссылки на портал AmoCRM, по которой должен перейти пользователь для получения кода авторизации.\n\nПараметр mode отвечает за обработку запроса на Redirect URI.\n1. _popup_ – окно авторизации будет закрыто, а переход на Redirect URI будет выполнен в основном окне.\n2. _post_message_ – перенаправление произойдет в окне, которое было открыто,\n   после обработки кода авторизации вам нужно закрыть окно\n\n#### client.auth.setCode(code)\n\nУстанавливает код авторизации и удаляет информацию о текущем токене. Желательно применять именно этот метод\nв сравнение с client.environment.set('auth.code');\n\n### client.token\n\n#### client.token.setValue(value)\n\nУстанавливает новое значение токена.\n\n#### client.token.getValue()\n\nВозвращает текущее значение токена.\n\n#### client.token.refresh()\n\nОбновляет токен по значению refresh_token текущего. Явно вызывать нет необходимости, так как\nпри каждом запросе идёт проверка токена на актуальность. Если время жизни токена истекло, этот метод\nбудет вызван автоматически.\n\nПосле обновления, токен автоматически устанавливается в приложении.\n\n#### client.token.fetch()\n\nПолучение токена по коду авторизации. После обновления, токен автоматически устанавливается в приложении.\n\n#### События\n\n- beforeChange. Возникает после получения по API токена и до того как он будет установлен в приложении\n- change. Возникает после установления нового значения в приложении\n- expirationCheck. Возникает при проверке актуальности токена\n- beforeFetch. Возникает перед попыткой получения токена по коду авторизации\n- fetch. Возникает после получения токена по коду авторизации\n- beforeRefresh. Возникает перед попыткой обновления токена по значению refresh_token текущего\n- refresh. Возникает после получения нового токена по значению refresh_token старого\n\n```js\nclient.token.on('change', () =\u003e {\n    console.error('Токен обновлён');\n})\n```\n\n\u003ca id=\"events\"\u003e\u003c/a\u003e\n## Работа с событиями \n\nКомпоненты Auth, Token, Connection унаследованы от класса\n[EventEmitter](https://nodejs.org/api/events.html). То есть они все поддерживают\nметоды подписки на события (on, off, removeAllListeners) и отписки от них, принятые в EventEmitter.\n\n\u003ca id=\"errors\"\u003e\u003c/a\u003e\n## Обработка ошибок \n\n- NO_JSON_RESPONSE. Пустой ответ\n- INVALID_JSON_RESPONSE. Некорректный JSON ответ\n- API_RESPONSE_ERROR. Ошибка в ответе по API\n- NO_TOKEN_AND_CODE. В настройках отсуствует код и не установлен токен\n- PATH_IS_EMPTY. Попытка вызвать client.environment.set без переданного пути\n- INVALID_PATH. Неверный путь при вызове client.environment.set\n- NO_AUTH_OPTIONS. Отсутствуют настройки config.auth\n- JSON_PARSE_ERROR. Ответ AmoCRM сформирован в неверном JSON формате\n\n\u003ca id=\"session\"\u003e\u003c/a\u003e\n## Сохранение авторизации между сессиями\n\nМожет быть полезным сохранять авторизацию между запусками приложения. Для этого есть событие `change`\nкомпонента client.token, в которое приходит новый токен при каждом сохранении.\n\nЭтот токен можно сохранять куда вам удобно (БД, файлы и тд). При инициализации соединения можно заранее установить токен для восстановления авторизации:\n`crm.token.setValue(currentToken)`\n\n[Пример реализации через сохранение в файл](./examples/javascript/00-common/01-session.js)\n\n\u003ca id=\"v2-migration\"\u003e\u003c/a\u003e\n## Переход с версии 2.x.x\n\n### Методы\n\n- client.connect -\u003e client.connection.connect\n- client.request(method, path, params, options) -\u003e client.request.make(method, path, params, options)\n- client.connection.getAuthUrl() -\u003e client.auth.getUrl()\n- client.connection.setState(state) -\u003e client.environment.set('auth.state', state)\n- client.connection.getState() -\u003e client.environment.get('auth.state')\n- client.connection.getToken() -\u003e client.token.getValue()\n- client.connection.setToken(token) -\u003e client.token.setValue(token)\n- client.connection.refreshToken() -\u003e client.token.refresh()\n\n#### client.connection.setCode(code)\n\nЗамена: client.auth.setCode(code)\n\nВызов этого метода в версии 2.x.x приводит к обновлению токена по только что заданному коду.\n\nВ текущей версии это происходит при последующем запросе к API. Старая версия эквивалентна:\n\n```js\nclient.auth.setCode(code);\nawait client.connection.connect();\n```\n\n### События\n\n- client.on('connection:beforeConnect') -\u003e client.connection.on('beforeConnect')\n- client.on('connection:beforeFetchToken') -\u003e client.token.on('beforeFetch')\n- client.on('connection:beforeRefreshToken') -\u003e client.token.on('beforeRefresh')\n- client.on('connection:checkToken') -\u003e client.token.on('expirationCheck')\n- client.on('connection:authError') -\u003e client.connection.on('connectionError')\n- client.on('connection:connected') -\u003e client.connection.on('connected')\n- client.on('connection:error') -\u003e client.connection.on('connectionError')\n- client.on('connection:newToken') -\u003e client.token.on('change')\n\n## Примеры\n\nОбщее:\n- [Сохранение сессии](./examples/javascript/00-common/01-session.js)\n- [Работа с сервером авторизации](./examples/javascript/00-oauth/001-get-token-with-server.js)\n\nРабота с фабриками:\n- Сделки [[примеры работы]](./examples/javascript/01-leads)\n- Контакты [[примеры работы]](./examples/javascript/02-contacts)\n- Компании [[примеры работы]](./examples/javascript/03-companies)\n- Теги [[примеры работы]](./examples/javascript/04-tags)\n- Задачи [[примеры работы]](./examples/javascript/05-tasks)\n\n## Доска почёта\n\nСпасибо @amorev, @maxism, @shuraman69, @korovenko-tatyana, @lotgyero, @capfsb, @templar820 за вклад в разработку этого проекта\n\nОтдельная благодарность @dmitrytemlead за возможность протестировать библиотеку в стороннем проекте\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusefulweb%2Famocrm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fusefulweb%2Famocrm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fusefulweb%2Famocrm/lists"}