aatex-contragents

name	aatex-contragents
description	CRM — работа с контрагентами (клиентами, поставщиками) в ЦУП ААТех. Применяй для "добавь клиента", "найди контрагента по ИНН", "обнови реквизиты", "создай из ЕГРЮЛ", "кто контактное лицо", "покажи клиентов". Контрагенты нужны обязательно при создании заказов (order type).

Работа с контрагентами (CRM)

Когда использовать

• Поиск контрагента по имени или ИНН
• Создание нового контрагента (вручную или из ЕГРЮЛ)
• Обновление реквизитов, банка, контактов
• Получение деталей для привязки к заказу
• Просмотр контактных лиц

Контрагент в ЦУП

Контрагент — внешний партнёр организации. Это может быть:

• Клиент (покупатель) — покупает у вас
• Поставщик — поставляет комплектующие
• Подрядчик — выполняет работы

Организация ≠ контрагент. Ваша организация — это «мы» (workspace). Контрагенты — это «они» (внешние).

Структура данных

{
  id: string,
  name: string,              // полное название
  shortName?: string,
  inn: string,               // ИНН (10 или 12 цифр, или казахский БИН/ИИН)
  kpp?: string,              // 9 цифр
  ogrn?: string,
  addresses?: { legal?, actual?, post? },
  contacts?: [
    { name, position, phone, email }
  ],
  bankDetails?: { bank, bik, account, correspondentAccount },
  managerId?: string,        // ответственный менеджер (user)
}

Инструменты

Инструмент	Параметры	Назначение
list_contragents	search?	Список (search — по имени/ИНН)
get_contragent	contragentId	Полные детали
create_contragent	name, inn, kpp?, ogrn?, shortName?, legalAddress?	Создать
update_contragent	contragentId, name?, ...	Обновить
search_contragent_by_inn	inn	Поиск в ЕГРЮЛ (только RU ИНН)

Сценарии

1. Найти контрагента

list_contragents(search="Ромашка")
→ массив с полями id, name, inn, shortName

Если нашёл несколько — уточни у пользователя по ИНН или контексту.

2. Создать из ЕГРЮЛ (самый надёжный способ)

1. search_contragent_by_inn(inn: "7707083893")
   → { name, shortName, legalAddress, kpp, ogrn, ... }
2. create_contragent(
     name: <из ЕГРЮЛ>,
     inn: "7707083893",
     kpp: <из ЕГРЮЛ>,
     ogrn: <из ЕГРЮЛ>,
     legalAddress: <из ЕГРЮЛ>
   )
   → contragentId

Преимущество: официальные данные из реестра, никаких опечаток.

3. Создать вручную

Для иностранных контрагентов (нет в ЕГРЮЛ) или без ИНН:

create_contragent(
  name: "Kazakh Supplier LLP",
  inn: "123456789012",   // БИН Казахстана — тоже валиден
  legalAddress: "Алматы, ..."
)

Поддержка иностранных: ИНН необязателен для казахских/иностранных, ЕГРЮЛ lookup работает только для российских 10/12-значных.

4. Обновить реквизиты

update_contragent(contragentId, {
  name: "Новое название",
  kpp: "7707XXXXX",
  legalAddress: "Новый адрес"
})

5. Показать контактные лица

get_contragent(contragentId)
→ { ..., contacts: [{name, position, phone, email}, ...] }

Индекс контакта важен для привязки к заказу — buyerContactPersonIndex в typeSpecificData заказа.

6. Проверка «есть ли контрагент»

Перед созданием заказа:

1. list_contragents(search="<название>")
2. Если массив пустой → search_contragent_by_inn → create_contragent
3. Если есть → используй существующий id

Важные нюансы

ИНН

• Российский юрлицо: 10 цифр
• Российский ИП / физлицо: 12 цифр
• Казахстан БИН: 12 цифр (по форме похож, но валидация другая)
• Без ИНН: допустимо для иностранных партнёров — передай пустую строку или не передавай

ЕГРЮЛ lookup

search_contragent_by_inn работает только для российских ИНН. Возвращает:

• name — полное официальное название
• shortName — короткое
• legalAddress — юр. адрес
• kpp, ogrn
• director — ФИО руководителя (если доступно)

Если ИНН не найден или ошибка API — предложи создать вручную.

Менеджер контрагента

У контрагента есть поле managerId — ответственный сотрудник. История смены менеджера: contragent_history.

Правила назначения:

• Любой участник может назначить себя, если контрагент свободен
• Переназначить/снять может только admin/owner

Менять через update_contragent — пока не поддерживается в MCP, используй UI.

Адреса

Поле addresses — объект с ключами legal, actual, post. В MCP create_contragent/update_contragent принимают только legalAddress (удобство), инструмент маппит его в { legal: legalAddress }.

Для полного управления адресами — UI.

Банковские реквизиты

Не поддерживаются напрямую в MCP create_contragent. Создай контрагента через MCP, затем добавь банк через UI.

Типичные ошибки

Ошибка	Причина
No company found for INN ...	ИНН не в ЕГРЮЛ или не российский
Contragent ... not found	Неправильный ID
INN is required	Забыл передать inn
Contragent with this INN exists	Дубликат — используй существующий

Связь с другими скиллами

• aatex-orders — контрагенты обязательны при создании заказа
• aatex-cards — update_card с typeSpecificData.buyerContragentId меняет контрагентов заказа

Пример диалога

Пользователь: «Добавь контрагента Газпром по ИНН 7736050003»

1. list_contragents(search="7736050003")
   → пусто (ещё не добавлен)
2. search_contragent_by_inn("7736050003")
   → { name: "ПАО ГАЗПРОМ", kpp: "997250001", ogrn: "1027700070518",
        legalAddress: "Москва, ул. Наметкина, 16" }
3. create_contragent(
     name: "ПАО ГАЗПРОМ",
     inn: "7736050003",
     kpp: "997250001",
     ogrn: "1027700070518",
     legalAddress: "Москва, ул. Наметкина, 16"
   )
   → contragentId = "cg_xyz..."
4. Готово! Можешь использовать в заказах.