Перейти к содержимому
mybi connect — База знаний

Изменения в примечаниях (API v4)

Выгрузка данных из 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)**1DEAL_CREATED–2CONTACT_CREATED–3DEAL_STATUS_CHANGED–4COMMONcommon5ATTACHMENTattachment10CALL_INcall_in11CALL_OUTcall_out12COMPANY_CREATED–13TASK_RESULT–15amomail_message18targeting_in19targeting_out202224geolocation25SYSTEMservice_message32link_followed34extended_service_message102SMS_INsms_in103SMS_OUTsms_outmessage_cashier

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)цифровой кодсимвольный код**1DEAL_CREATEDlead_added2CONTACT_CREATEDcontact_added3DEAL_STATUS_CHANGEDlead_status_changed12COMPANY_CREATEDcompany_added

Тип примечания (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:

image3.png

Мы видим примечания с цифровыми идентификаторами 1 и 3, имеющие так же и символьные идентификаторы, а также примечание с идентификатором 15, у которого не было символьного идентификатора. Так же мы видим, что для примечания с идентификатором 1 заполнено поле text.

Переключив выгрузку на API v4, мы получим данные:

image2.png

по которым видно, что остался только один тип примечаний – amomail_message (цифровой идентификатор 15). Примечания же с идентификаторами 1 и 3 пропали, а точнее – переместились в события, таблица amocrm_leads_events:

image1.png

Пользователи, которые создавали источники ранее 16 ноября 2021 года, используют старую версию API, расширенная поддержка API v4 у них отключена. Начиная с 16 ноября 2021 года все вновь подключаемые источники amoCRM по умолчанию имеют включенную поддержку API v4 – это означает, что примечания выгружаются уже в новом виде:

image4.png

Для перехода на API v4 пользователям API v2 необходимо определиться с необходимостью выгрузки примечаний и, обратившись в поддержку сервиса myBI Connect, попросить переключить их на новый API v4, после чего все примечания либо будут удалены, либо сконвертированы в новый формат по выбору пользователя.

После того как все источники amoCRM будут переведены на новую версию API, устаревшие поля и таблицы будут удалены из баз данных.