CRM API: ресурсы

← CRM API: начало работы

Контакты, компании, сделки и задачи#

Пути в таблицах указаны относительно базового URL. Все mutation-маршруты требуют Idempotency-Key.

crm_contact_data_read/write, crm_amounts_read/write и crm_custom_fields_read/manage применяются дополнительно к scope ресурса. Без read-scope защищённые значения исключаются или маскируются; для записи соответствующих полей нужен write/manage-scope.

Компании сделки#

В POST /deals, PATCH /deals/:id и upsert-командах компании передаются упорядоченным массивом ссылок companies. Каждая ссылка содержит ровно один ключ: UUID id или externalId текущего приложения. Первая компания становится основной.

{
  "companies": [
    { "id": "2c3902fc-5f60-4d49-ab04-313597436a3c" },
    { "externalId": "company-from-erp-42" }
  ]
}

В PATCH отсутствие companies не меняет связи, а null или пустой массив очищают их. Дубли ссылок отклоняются. Для обычной сделки после изменения должна остаться хотя бы одна компания или один контакт.

Ответ сделки содержит упорядоченные companyIds и подробные связи companies. Одиночного верхнеуровневого companyId в контракте сделки нет.

{
  "companyIds": [
    "2c3902fc-5f60-4d49-ab04-313597436a3c",
    "85a87511-a8a4-48ee-a7ee-e6fc88546d1d"
  ],
  "companies": [
    {
      "companyId": "2c3902fc-5f60-4d49-ab04-313597436a3c",
      "isPrimary": true
    },
    {
      "companyId": "85a87511-a8a4-48ee-a7ee-e6fc88546d1d",
      "isPrimary": false
    }
  ]
}

Batch возвращает результат каждого элемента отдельно. Частичный успех не означает, что весь batch применён одинаково; проверяйте status, data или error каждого элемента. POST */batch/get — операция чтения и единственное POST-исключение в этих таблицах, для которого Idempotency-Key не нужен.

Слияние и удаление контактов и компаний#

merge/preview возвращает requiredResolutions — список конфликтных полей. Все они должны быть разрешены в fieldResolutions при commit, иначе ответ 422. Commit требует expectedPrimaryVersion и expectedSecondaryVersion.

Если externalId этого приложения есть у обоих клиентов, commit отвечает 409 external_id_conflict. Передайте externalIdConflictResolution: "keep_primary", чтобы оставить ключ основного клиента; ключ присоединённого станет tombstone и будет отвечать 410. Когда конфликта нет, externalId дубля переносится на основной объект.

delete/commit принимает mode: anonymize стирает персональные данные, сохраняя объект и ссылки на него, full удаляет клиента и превращает его externalId в tombstone. После анонимизации GET /contacts/:id отвечает 410 resource_deleted — объект существует для связей, но перестаёт быть ресурсом API.

Теги ресурсов#

Набор заменяется целиком: точечных add/remove нет, потому что они не идемпотентны при повторной доставке. PUT требует expectedVersion самого ресурса и поднимает его версию, если набор изменился. Теги указываются по UUID либо по externalId текущего приложения.

Вложенные ресурсы сделки#

Любое изменение вложенного ресурса поднимает версию самой сделки: интеграции синхронизируют сделку целиком, и без этого их копия расходилась бы с сервером незаметно. Количество и деньги в позициях передаются decimal-строками — числа с плавающей точкой теряют точность на суммах.

Лента событий неизменяема, поэтому её курсор идёт по createdAt, а не по updatedAt.

Чек-листы задачи#

Удаление чек-листа снимает его пункты каскадом. Изменение любого пункта поднимает версию задачи.

Поиск и аналитика#

Поиск принимает q длиной 2–200 символов, types=contact,company,deal,task, cursor и limit от 1 до 50 (по умолчанию 20). Результаты каждого типа появляются только при наличии соответствующего crm_*_read. Поиск по контактам включается только с crm_contacts_read, по дополнительным полям — с crm_custom_fields_read. Телефоны и email раскрываются только с crm_contact_data_read.

Analytics принимает ISO-даты startDate/endDate и UUID-фильтры pipelineId, ownerId, contactId, companyId, tagId. Без crm_amounts_read денежные показатели маскируются; без crm_operators_read исключаются manager leaderboard и связанный insight. Поле meta.redacted перечисляет применённые проекции.

Audit log#

Доступны фильтры resourceType, action, applicationId, cursor и limit до 100. Одного crm_audit_read недостаточно для чтения любого содержимого: API возвращает только типы ресурсов, для которых у приложения есть соответствующий read-scope. Контакты, суммы и дополнительные поля редактируются по их scopes; UUID пользователя-актора выдаётся только с crm_operators_read.