aatex-contragents - SKILL.md Agent Skill

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. Готово! Можешь использовать в заказах.