Как добавить примечание в сделку AMOcrm через API

При работе с интеграцией сайта и CRM-системы AMOcrm часто возникает задача не только создать сделку, но и сразу добавить к ней текстовое примечание. В стандартном методе /api/v4/leads/complex нет возможности указать заметки внутри массива сделки. Разберём, как правильно решить эту задачу с помощью отдельного запроса.

Почему notes не работают в комплексном методе

Метод /api/v4/leads/complex предназначен для одновременного создания сделки, контакта и компании. Примечания к сделке - это отдельная сущность. Они не входят в структуру _embedded для leads. Поэтому попытка добавить ключ notes внутрь массива сделки игнорируется или вызывает ошибку.

Правильный алгоритм: два шага

Чтобы создать сделку с заметкой, выполните последовательно два запроса:

1. Создайте сделку через /api/v4/leads/complex (как в вашем исходном коде).
2. Добавьте примечание к уже существующей сделке через метод /api/v4/leads/{id}/notes.

Пример кода для добавления примечания

$leadId = 123456; // ID только что созданной сделки
$noteData = [
    [
        'entity_id' => $leadId,
        'note_type' => 'common',
        'params' => [
            'text' => 'Текст примечания 2'
        ]
    ]
];

$method = '/api/v4/leads/' . $leadId . '/notes';
// Выполните POST-запрос с $noteData

Типичные ошибки при добавлении заметок

• Неправильный URL: путь должен быть /api/v4/leads/{id}/notes, а не /api/v4/leads/complex.
• Отсутствие entity_id: каждый элемент массива заметок должен содержать entity_id (ID сделки).
• Неверный формат params: для типа common обязательно поле text внутри params.

Другие типы примечаний в AMOcrm

Кроме текстовых заметок (common) вы можете создавать:

• call_in - входящий звонок
• call_out - исходящий звонок
• sms_in / sms_out - SMS-сообщения
• service_message - служебные уведомления

Для каждого типа требуется свой набор параметров. Подробнее смотрите в официальной документации AMOcrm.

Оптимизация: один запрос или несколько

Если вам критично создать сделку и заметку одним запросом, это невозможно через стандартный REST API. Однако вы можете написать обёртку на стороне сервера, которая последовательно выполнит оба запроса и вернёт клиенту единый ответ. Такой подход не нарушает логику AMOcrm и позволяет сохранить атомарность операции на вашем уровне.

Используя описанный двухшаговый метод, вы легко добавите примечание к сделке. Главное - запоминать ID созданной сделки и отправлять заметки отдельным запросом.