# Aatex Contragents

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

- Skill: `awaik/aatex-contragents` (Agent Skill)
- Install (CLI): `npx skillmds@latest add awaik/aatex-contragents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/awaik/aatex-contragents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: awaik (https://skillmd.com/u/awaik)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/awaik/aatex-contragents

---


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

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

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

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

**Контрагент** — внешний партнёр организации. Это может быть:
- **Клиент** (покупатель) — покупает у вас
- **Поставщик** — поставляет комплектующие
- **Подрядчик** — выполняет работы

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

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

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