Теги (Tags)

Теги доступны у сделок, контактов и компаний. Модель тега — Tag — содержит два поля: id и name.

from amocrm import Tag

Чтение тегов

При получении сущности из API теги автоматически парсятся из _embedded.tags:

lead = client.leads.get(42)

if lead.tags:
    for tag in lead.tags:
        print(tag.id, tag.name)

То же самое для контактов и компаний:

contact = client.contacts.get(10)
company = client.companies.get(5)

print(contact.tags)  # list[Tag] | None
print(company.tags)  # list[Tag] | None

Создание сущности с тегами

Передайте список Tag при создании. Для новых тегов достаточно указать только name — AmoCRM создаст тег автоматически:

from amocrm import Lead, Tag

lead = Lead(
    name="Новая сделка",
    price=50000,
    tags=[Tag(name="vip"), Tag(name="горячий")],
)
created = client.leads.create([lead])

Чтобы привязать существующий тег, передайте его id:

lead = Lead(
    name="Сделка с существующим тегом",
    tags=[Tag(id=12345)],
)
client.leads.create([lead])

Аналогично для контактов и компаний:

from amocrm import Contact, Company, Tag

contact = Contact(
    name="Иван Иванов",
    tags=[Tag(name="важный клиент")],
)
client.contacts.create([contact])

company = Company(
    name="ООО Ромашка",
    tags=[Tag(name="партнёр")],
)
client.companies.create([company])

Обновление тегов

Замена всех тегов

Присвойте новый список тегов и обновите сущность:

lead = client.leads.get(42)
lead.tags = [Tag(name="vip"), Tag(name="приоритет")]
client.leads.update_one(lead)

Добавление тега

Добавьте тег к существующему списку:

lead = client.leads.get(42)

if lead.tags is None:
    lead.tags = []

lead.tags.append(Tag(name="новый тег"))
client.leads.update_one(lead)

Удаление тега

Отфильтруйте нужный тег из списка:

lead = client.leads.get(42)

if lead.tags:
    lead.tags = [t for t in lead.tags if t.name != "горячий"]
    client.leads.update_one(lead)

Удаление всех тегов

Передайте пустой список:

lead = client.leads.get(42)
lead.tags = []
client.leads.update_one(lead)

Фильтрация по тегам

AmoCRM API позволяет фильтровать сущности по тегам через параметр filter:

# По ID тега
for lead in client.leads.list(filter={"tag_id": 12345}):
    print(lead.name)

# По нескольким тегам (OR)
for lead in client.leads.list(filter={"tag_id": [12345, 67890]}):
    print(lead.name)

Сериализация

При вызове to_dict() теги помещаются на верхний уровень словаря (а не в _embedded). Это соответствует формату AmoCRM API для операций записи:

lead = Lead(
    name="Сделка",
    tags=[Tag(name="vip")],
)
lead.to_dict()
# {"name": "Сделка", "tags": [{"name": "vip"}]}

Модель Tag

class amocrm.models.common.Tag(*, id=None, name=None)[исходный код]

Базовые классы: object

Тег сущности AmoCRM.

Переменные:

id (int | None) – Идентификатор тега.
name (str | None) – Название тега.

Параметры:

id (int | None)
name (str | None)

id: int | None = None

name: str | None = None

classmethod from_dict(data)[исходный код]

Создать экземпляр из словаря API.

Параметры:: data (dict[str, Any])
Тип результата:: Tag

to_dict()[исходный код]

Сериализовать в словарь, исключая поля со значением None.

Тип результата:: dict[str, Any]

__init__(*, id=None, name=None)

Параметры:

id (int | None)
name (str | None)

Тип результата:

None