Amocrm Api Control

---
name: amocrm-api-control
description: "Безопасная OAuth-авторизация amoCRM, чтение схемы аккаунта и сверка заявок по источнику, времени, статусу, ответственному и внешней ссылке."
---

# Управление amoCRM через программный интерфейс

## Если amoCRM не подключена

amoCRM необязательна. Для сверки продаж достаточно любой CRM-выгрузки (CSV, Excel, JSON) с источником, временем события, статусом, ответственным и внешней ссылкой: к файлу применяются те же правила сверки. Интеграцию и OAuth создавайте только по явной просьбе пользователя о доступе по API.

## Граница задачи

Навык предназначен для получения и обновления OAuth-токенов, чтения воронок, статусов и полей, а также сверки заявок. Любые изменения бизнес-данных требуют отдельного плана, точной области, подтверждения и чтения после записи.

## Перед созданием интеграции

1. Если для аккаунта уже есть закрытая интеграция, восстановить и использовать её, а не создавать вторую: лишняя интеграция повышает риск отказа в технической поддержке и разрастания учётных данных. Новая допустима только с записанной причиной, почему существующая непригодна, и подтверждением риска пользователем.
2. Создание закрытой интеграции в нетехническом аккаунте может иметь последствия для технической поддержки; покажи владельцу актуальное предупреждение из интерфейса amoCRM.
3. `redirect_uri` должен точно совпадать с адресом интеграции. Местный приёмник слушает только `127.0.0.1` и проверяет точные путь и `state`.
4. Доступ привязывается к ожидаемому аккаунту: запросами на чтение сверить вместе читаемое имя аккаунта, поддомен и идентификатор аккаунта. Одного названия мало: одинаковые названия, скопированные сеансы браузера и чужие закрытые интеграции тоже успешно авторизуются.
5. Откат и отзыв описываются на уровне токена: отозвать выданный токен, заменить локальную учётную запись или убрать текущую авторизацию приложения. Отключение всей интеграции — отдельное действие высокого влияния: от неё могут зависеть другие токены и процессы.

## Закрытые файлы

Все файлы интеграции, `state`, кода авторизации и токенов должны иметь права `0600`, а их папки — `0700`. Секрет, код и токен не передавай аргументом и не печатай.

Ожидаемая схема файла интеграции:

```json
{
  "subdomain": "ACCOUNT_SUBDOMAIN",
  "client_id": "PUBLIC_INTEGRATION_ID",
  "client_secret": "PRIVATE_INTEGRATION_SECRET",
  "redirect_uri": "EXACT_REGISTERED_REDIRECT_URI"
}
```

## Порядок OAuth

1. Создай случайное состояние и сохрани его в закрытом файле.
2. Запусти `scripts/amocrm_local_callback_server.py` с явными `--state-file` и `--output`.
3. Открой адрес согласия, содержащий тот же `state`.
4. Приёмник сохранит только код, а не полный адрес.
5. Запусти `scripts/exchange_amocrm_token.py` с `--integration-file`, `--authorization-code-file` и `--token-file`. Для обновления используй `--refresh` без файла кода.
6. После успешного первого обмена удали одноразовый файл кода.

## Чтение схемы и сверка

`scripts/fetch_amocrm_schema.py` проходит постраничную выдачу и сохраняет схему аккаунта в закрытой папке. Повтор той же страницы считается ошибкой.

Для сверки каждая строка обязана иметь поля:

- `source` — источник;
- `occurred_at` — время события;
- `status` — статус;
- `responsible` — ответственный;
- `external_link` — внешняя ссылка, используемая как ключ сопоставления.

Результат разделяет совпадение, расхождение и строку, присутствующую только во втором источнике.

## Сверка заявок: доказательства

При сверке внешних форм, выгрузок конструктора сайтов, меток UTM и CSV с amoCRM сначала сохраняются доказательства только на чтение:

1. Снимок схемы и счётчиков: аккаунт, воронка, статусы, поля заявки и контакта, «Неразобранное».
2. Точное окно времени, форма исходного файла, способ извлечения адреса и UTM, правило категорий.
3. Различие контактов, сделок, неразобранных заявок, дублей и пропавших заявок: карточка контакта сама по себе не доказывает, что заявка попала в нужную воронку.
4. Перед решением «новый или повторный клиент» — поиск дублей контактов по нормализованным телефону и почте и оценка всех связанных сделок, заметок и истории статусов.

Единица анализа для отчётов по менеджеру, первому менеджеру, новизне, источнику, выручке и статусу продажи — набор идентичности: дубли контактов, все связанные сделки, история смены статусов и ответственных, заметки, пометки удалённых и недоступных сделок.

Структурированные доказательства источника отделяются от подстрок и свободного текста. Название источника, фрагмент UTM или метка канала внутри комментария — кандидат, а не доказательство, пока не записаны поле, воронка, окно и порядок приоритета. Источники классифицируются явным порядком (UTM, referrer, поле источника, пометка интеграции, ручные заметки); записи без доказательства остаются `unknown`. В конце — контрольный подсчёт без фильтров по аккаунту или воронке: отбор, фильтр дублей и удалённых и граница дат не потеряли целевые заявки. Для перенесённой или переименованной воронки читаются и старая, и новая воронки за точный период.

Удалённые и недоступные сделки не превращаются в ноль: `deleted_inaccessible`, `unknown_missing_amount`, `confirmed_zero`, `not_sale` или `out_of_scope`. Агрегат выручки, повторности или менеджера, зависящий от неразрешённых удалённых сделок, остаётся заблокированным или помечается неразрешённым.

Пустые тела, пробелы пагинации, сбои авторизации и неожиданные ответы не в JSON записываются как отдельные состояния ответа. В сводках для пользователя — человекочитаемые названия воронок, статусов и источников; служебные номера — только для технического аудита.

Для анализа воронки или статусов учитывается история смены статусов, а не только текущее членство: сделки, вошедшие в воронку, покинувшие её или проигранные в окне, входят в аудит, даже если их уже не видно в воронке. Раздельно хранятся прямые свидетельства ответа клиента, внутренние заметки, текущее и историческое состояние потери, критерий суммы продажи и пустые причины; пустая причина не превращается в названную.

## Массовые чтения и блокировки

Перед тысячами чтений по контактам или сделкам проверить, нет ли в официальном API массового или связывающего метода с пагинацией, и применять его после сверки с небольшой выборкой отдельных чтений. Долгие чтения устойчивы к обрыву: после каждой идемпотентной партии сохраняются последняя подтверждённая страница или курсор, контрольная сумма партии, путь результата и состояние ответа. Медленный живой запрос не повторяется вслепую, второй исполнитель на ту же страницу не запускается; после остановки работа продолжается с последней подтверждённой партии.

Ответы amoCRM — сигналы безопасности: `429` требует паузы и сохранения прогресса; первый `403` или блокировка аккаунта останавливает очередь исполнителей без повторов и без смены сетевой идентичности. Сохраняются последняя успешная единица, класс заблокированного метода, прогресс и одно безопасное чтение состояния аккаунта.

## Корпус коммуникаций и идентичность события

До скачивания или расшифровки проверить поверхности источников: заметки, комментарии к задачам, метаданные звонков, записи, письма, мессенджеры и телефония — отдельные источники. Наличие ссылок и коротких заметок не доказывает покрытия чатов и записей: доказать скачиваемый источник, способ доступа, период и что отсутствует. Заранее оценить число звонков, длительность и объём диска; докачка с манифестами, контрольными суммами и прогрессом по источнику. Получение источника и локальная расшифровка — разные слои сбоев; после докачки производные журналы, таблицы, манифесты и кэши сверяются с итоговым исходом по каждому звонку.

Предполагаемому `created_at` не доверять, пока не доказано поведение фильтра на конкретном методе: сохранить проверенный серверный фильтр и локально исключить записи вне окна. Если пользователь сузил корпус, широкая выгрузка останавливается, а свои артефакты вне области убираются. Событие звонка, скачанный файл, задание расшифровки и связь со сделкой — разные идентичности: несколько событий могут ссылаться на один файл; контакт не определяет единственную сделку; при нескольких возможных сделках хранятся кандидаты и явная неоднозначность. Для постоянного сборщика снимок истории отделяется от изменяющегося потока: вместо фиксированных дат — явный контракт синхронизации (поле изменения, курсор, часовой пояс и точность, перекрытие); отсутствие записи на одной странице не доказывает её удаления.

## Аудитории и ретаргетинг

Перед выбором аудитории по профессии проверить поля контакта и сделки в схеме аккаунта и записать, где хранится профессия и как разрешаются конфликты. Пустое поле не доказывает отсутствия профессиональной связи; профессия сделки не распространяется на всех связанных людей без доказательств. Назначение каждого телефонного поля сохраняется при нормализации и дедупликации; если частные номера исключены, нормализованный номер исключается по всей выгрузке. Подходящая аудитория не даёт права на её выгрузку в рекламную систему — это отдельное разрешение.

Для ретаргетинга источник истины — воронка, статус и идентификаторы сделки и контакта; передаются хешированные почты и телефоны партиями или используется встроенная синхронизация платформы. Для связки «воронка и статус → аудитория» сначала проверить встроенную интеграцию amoCRM с нужной площадкой. Для ВКонтакте поведение описано в справке amoCRM: контакт «Активен», пока сделка в заданном этапе, и становится «Неактивным», когда сделка уходит из этапа или пользователь скрывает рекламу; повторным входом в этап из «Неактивного» не возвращается. Для Яндекс Аудиторий и других площадок правила переходов проверяются по их собственной документации и на тестовой сделке, а не переносятся с ВКонтакте. Логика добавления и удаления описывается по каждому переходу статуса, с дедупликацией и повторным входом.

## Отчёты по этапам и полям

Использовать уже подтверждённый API amoCRM; не требовать входа у поставщика форм, если API покрывает нужные доказательства. Сохранённые исходные журналы форм — для независимой проверки дублей и доставки; недоступное свежее покрытие форм помечается отдельно. Перед признанием отчёта готовым построитель выполняется целиком на сохранённой полной выборке: проверка синтаксиса не ловит конфликтов имён и несоответствий схемы. Служебные и трекинговые поля скрываются без учёта регистра и написания (`referer` и `referrer`); сырые адреса и параметры запросов остаются только в закрытых доказательствах.

## Граница публикации

Не публикуй поддомены аккаунтов, учётные данные, токены, контакты, заявки, домены и местные пути. Для испытаний используй только синтетические данные.