Выгрузка данных из amoCRM технически возможна как через устаревший API v2, так и через современный API v4. Исторически выгрузка осуществлялась через API v2, но использование новой версии позволит нам улучшить производительность выгрузки и расширить набор получаемых сведений. Одновременно с этим переход повлияет на структуру данных в хранилище и, как следствие, на отчеты. В данном материале мы рассмотрим изменения структуры примечаний.
При использовании API v2 примечания выгружаются по пяти типам сущностей в следующие таблицы:
- amocrm_leads_notes – примечания сделок;
- amocrm_contacts_notes – примечания контактов;
- amocrm_companies_notes – примечания компаний;
- amocrm_customers_notes – примечания покупателей;
- amocrm_tasks_notes – примечания задач.
Эти таблицы имеют одинаковую структуру:
- id – идентификатор записи;
- account_id – идентификатор подключенного аккаунта;
- leads_id / contacts_id / companies_id / customers_id / tasks_id – идентификатор сущности (внешний ключ);
- creator_id – внутренний идентификатор создавшего;
- responsible_id – внутренний идентификатор ответственного;
- note_id – внутренний идентификатор примечания;
- note_type – тип примечания;
- note_type_id – идентификатор типа примечания;
- created_at – дата создания;
- updated_at – дата изменения;
- text – текст примечания;
- params -дополнительные параметры.
Единственное отличие между таблицами – поле идентификатора сущности (внешний ключ для связи со справочником).
При переходе со старой версии API (v2) на новую (v4) в таблицы примечаний перестанут загружаться:
- note_type_id – цифровой идентификатор типа примечания. Он отсутствует в новом API и определить тип примечания будет возможно только по символьному идентификатору note_type;
- text – текст примечания. В тех случаях, когда текстовое примечание есть, оно будет выгружено в поле “Дополнительные параметры” (params) в формате JSON.
Кроме этого необходимо обратить внимание на то, что символьные значения идентификаторов примечаний (note_type) теперь хоть и будут присутствовать всегда, но изменятся:
| note_type_id (v2) | note_type (v2) | note_type (v4) |
| 1 | DEAL_CREATED | – |
| 2 | CONTACT_CREATED | – |
| 3 | DEAL_STATUS_CHANGED | – |
| 4 | COMMON | common |
| 5 | ATTACHMENT | attachment |
| 10 | CALL_IN | call_in |
| 11 | CALL_OUT | call_out |
| 12 | COMPANY_CREATED | – |
| 13 | TASK_RESULT | – |
| 15 | amomail_message | |
| 18 | targeting_in | |
| 19 | targeting_out | |
| 20 | ||
| 22 | ||
| 24 | geolocation | |
| 25 | SYSTEM | service_message |
| 32 | link_followed | |
| 34 | extended_service_message | |
| 102 | SMS_IN | sms_in |
| 103 | SMS_OUT | sms_out |
| message_cashier |
Выгрузка примечаний по задачам после перехода на новое API (v4) будет недоступна. Информация из поля “Результат задачи”, ранее выгружаемая в событие TASK_RESULT, в API v4 выгружается в таблицу amocrm_tasks, поле result.
В API v4 некоторые типы примечаний переведены в класс События. Для получения этих данных необходимо включить загрузку в таблицы amocrm_leads_events, amocrm_contacts_events, amocrm_companies_events. Ниже приведена таблица соответствия типов примечаний и событий:
| Тип примечания (v2) | Тип события (v4) | |
| цифровой код | символьный код | |
| 1 | DEAL_CREATED | lead_added |
| 2 | CONTACT_CREATED | contact_added |
| 3 | DEAL_STATUS_CHANGED | lead_status_changed |
| 12 | COMPANY_CREATED | company_added |
В качестве примера рассмотрим примечания, которые ранее были выгружены при помощи API v2:
Мы видим примечания с цифровыми идентификаторами 1 и 3, имеющие так же и символьные идентификаторы, а также примечание с идентификатором 15, у которого не было символьного идентификатора. Так же мы видим, что для примечания с идентификатором 1 заполнено поле text.
Переключив выгрузку на API v4, мы получим данные:
по которым видно, что остался только один тип примечаний – amomail_message (цифровой идентификатор 15). Примечания же с идентификаторами 1 и 3 пропали, а точнее – переместились в события, таблица amocrm_leads_events:
Пользователи, которые создавали источники ранее 16 ноября 2021 года, используют старую версию API, расширенная поддержка API v4 у них отключена. Начиная с 16 ноября 2021 года все вновь подключаемые источники amoCRM по умолчанию имеют включенную поддержку API v4 – это означает, что примечания выгружаются уже в новом виде:
Для перехода на API v4 пользователям API v2 необходимо определиться с необходимостью выгрузки примечаний и, обратившись в поддержку сервиса myBI Connect, попросить переключить их на новый API v4, после чего все примечания либо будут удалены, либо сконвертированы в новый формат по выбору пользователя.
После того как все источники amoCRM будут переведены на новую версию API, устаревшие поля и таблицы будут удалены из баз данных.