amocrm-api-control

Управление 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. Секрет, код и токен не передавай аргументом и не печатай.

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

{
  "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); сырые адреса и параметры запросов остаются только в закрытых доказательствах.

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

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