Добавление тега к сделке в AMO CRM: пошаговая инструкция и частые ошибки

При интеграции с AMO CRM через API разработчики часто сталкиваются с проблемой добавления тегов к сделкам. В этой статье мы разберём корректный способ добавления тега, типичные ошибки и дадим готовый пример кода на PHP.

Почему ваш код не работает: основные ошибки

В исходном примере используется неверный метод HTTP и структура данных. Чтобы добавить тег к существующей сделке, нужно отправлять PATCH запрос, а не POST. Кроме того, массив тегов передаётся в неправильном формате.

Ошибка 1: неверный HTTP-метод

Для обновления сделки (добавления тега) используется метод PATCH, а не POST. POST применяется только для создания новых сущностей.

Ошибка 2: неправильная структура JSON

Теги в AMO CRM v4 передаются внутри объекта _embedded в виде массива объектов с полем name. Поле tags больше не используется - оно заменено на _embedded['tags'].

Правильный способ добавления тега к сделке через API

Для корректного добавления тега используйте следующий алгоритм:

• Выполните PATCH запрос к эндпоинту /api/v4/leads/{id}.
• Передайте тело запроса в формате JSON с правильной структурой.
• Убедитесь, что у тега нет дубликатов - API не создаст повторный тег с таким же именем.

Пример кода на PHP (cURL)

$leadId = 123456; // ID сделки
$tagName = 'Пример тега';
$subdomain = 'ваш_поддомен';
$accessToken = 'ваш_токен';

$data = [
    '_embedded' => [
        'tags' => [
            ['name' => $tagName]
        ]
    ]
];

$ch = curl_init("https://{$subdomain}.amocrm.ru/api/v4/leads/{$leadId}");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $accessToken,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpCode === 200) {
    echo 'Тег успешно добавлен';
} else {
    echo 'Ошибка: ' . $response;
}

Дополнительные рекомендации по работе с тегами в AMO CRM

При использовании API AMO CRM учитывайте следующие нюансы:

• Множественные теги: можно передать сразу несколько тегов в массиве tags.
• Удаление тегов: для удаления всех тегов передайте пустой массив tags.
• Лимиты: API имеет ограничение на количество запросов - 10 запросов в секунду на аккаунт.
• Обработка ошибок: всегда проверяйте HTTP-код ответа и тело ошибки для отладки.

Частые вопросы по добавлению тегов в AMO CRM

Ниже мы собрали ответы на вопросы, которые чаще всего задают разработчики при интеграции с AMO CRM.

Как добавить тег через API v2?

В API v2 теги добавляются через поле tags как строка с разделителями. Например: 'tags' => 'тег1,тег2'. Однако рекомендуется использовать API v4, так как v2 считается устаревшей.

Можно ли добавить тег без перезаписи существующих?

Да, при PATCH запросе существующие теги сохраняются, а новые добавляются к ним. Если нужно заменить все теги, используйте PUT запрос.

Что делать, если API возвращает ошибку 400?

Проверьте структуру JSON: убедитесь, что поле _embedded обязательно присутствует и массив tags содержит объекты с полем name. Также проверьте, что ID сделки существует и токен доступа актуален.