CRM API: фоновые операции
Фоновые операции
| Метод | Путь | Scope | Назначение |
|---|---|---|---|
GET | /bulk-jobs | crm_bulk_manage | Массовые операции организации |
POST | /bulk-jobs | crm_bulk_manage | Поставить массовую операцию |
GET | /bulk-jobs/:id | crm_bulk_manage | Статус и ошибки по целям |
GET | /exports | crm_export_manage | Задания выгрузки |
POST | /exports | crm_export_manage | Запросить выгрузку |
GET | /exports/:id | crm_export_manage | Статус выгрузки и ссылка на файл |
Оба маршрута создания отвечают 202 Accepted и возвращают идентификатор задания — результат
забирается отдельным GET.
POST /bulk-jobs принимает до 10 000 целей за раз. Набор изменяемых полей ограничен: для сделок это
title, description, amount, currency, priority, ownerUuid, expectedCloseDate (при
action: "move" — только stageUuid и lostReasonCategoryUuid), для задач — status, priority,
assigneeUuid, dueDate, startAt, для клиентов — ownerUuid. Все цели должны принадлежать
организации приложения, иначе ответ 404. Idempotency-Key дедуплицирует и само задание: повтор
доставки не поставит вторую операцию на те же объекты.
Операция неатомарна: каждая цель обрабатывается отдельно, и GET /bulk-jobs/:id показывает счётчики
по статусам и до 100 последних ошибок.
GET /exports/:id отдаёт downloadUrl только после завершения; ссылка подписанная и живёт сутки
(downloadUrlExpiresInSeconds). Внутренние пути хранилища наружу не публикуются.
В POST /exports поле type принимает contacts, companies, company_contacts,
deal_contacts, deal_companies или deals. Связи сделок с компаниями выгружаются отдельным
типом deal_companies, чтобы одна сделка могла занимать несколько строк без дублирования её
собственных полей.
Задание из публичного API не привязывается к сотруднику: его автором остаётся приложение. Поэтому письмо о готовности выгрузки не отправляется — статус нужно опрашивать через API, а область видимости данных равна всей организации, так как у приложения нет отдела и «своих» объектов.
Импорт CRM из файла
| Метод | Путь | Scope | Назначение |
|---|---|---|---|
GET | /imports | crm_import_manage | Импорты организации |
POST | /imports | crm_import_manage | Загрузить файл (multipart, file) |
GET | /imports/:id | crm_import_manage | Состояние импорта |
POST | /imports/:id/preview | crm_import_manage | Колонки файла и доступные поля |
POST | /imports/:id/start | crm_import_manage | Запустить с маппингом колонок |
POST | /imports/:id/cancel | crm_import_manage | Отменить импорт |
Порядок работы: загрузили файл (CSV или XLSX, до 25 МБ) → получили preview с колонками →
отправили start с mapping и dedupPolicy → следите за status через GET /imports/:id.
Загрузка файла ничего не меняет в CRM: строки применяются только после start.
При загрузке передайте entityType: contacts, companies, company_contacts, deal_contacts
или deal_companies. Для deal_companies обязательны сопоставления dealUuid и companyUuid;
необязательное isPrimary отмечает основную компанию сделки.
Импорты из Bitrix24 и amoCRM публичным API не открываются — они настраиваются в кабинете вместе с самой интеграцией.
Вложения
| Метод | Путь | Scope | Назначение |
|---|---|---|---|
GET | /deals|tasks/:id/files | crm_*_read + crm_files_read | Список вложений |
POST | /deals|tasks/:id/files | crm_*_write + crm_files_write | Прикрепить файлы |
DELETE | /deals|tasks/:id/files/:fileId | crm_*_write + crm_files_write | Открепить файл |
Загрузка — multipart/form-data, поле files, до 10 файлов по 10 МБ за запрос. expectedVersion
передаётся в query и относится к самой сделке или задаче: прикрепление и открепление поднимают её
версию. Если часть файлов не загрузилась, успешные всё равно сохраняются, а проблемные перечислены
в meta.failed.
Ссылки в ответе подписанные и не содержат путей в хранилище. Открепление убирает файл у объекта, но не удаляет его из хранилища: тот же файл может быть прикреплён к другой сущности.