# Претензии

Претензия — это информация, которую участник размещает на ATI.SU, о нарушении его прав или условий договорённостей другим участником. Опубликованная Претензия видна участникам ATI.SU и попадает в Паспорт фирмы-ответчика.

Интеграционное API позволяет выставить претензию от имени пользователя вашей фирмы: загрузить документы, уточнить наименование юр. лица ответчика и создать саму претензию.

Все запросы выполняются с заголовком `Authorization: Bearer <access_token>`, токен выпускается по [инструкции по авторизации](https://ati.su/developers/raw/auth/auth-v2.md). Один токен соответствует одному пользователю: претензия публикуется от его имени и от имени его фирмы.

Идентификаторы в запросах и ответах — значения словарей претензий: типы претензий, типы документов, статусы, уровни. Списки значений отдают методы на странице [Словари для работы с претензиями](https://ati.su/developers/raw/api/dictionaries/claims.md).

## Порядок добавления претензии

1. Загрузите каждый документ отдельным запросом и соберите полученные `file_key`.
2. Если ответчик известен по коду ATI.SU, получите варианты наименования его юр. лица.
3. Создайте претензию, передав тип, стороны, сумму и собранные документы.

### Загрузка документа претензии

Загружает один файл документа претензии и возвращает его `file_key` для последующего создания претензии.

За один запрос загружается ровно один файл. Для каждого документа вызывайте метод отдельно и собирайте `file_key` в массив документов создаваемой претензии.

<a id="post-integration-v1-claims-documents-upload"></a>

Загрузка документа в плюшкин (внешние интеграторы)

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/gw/claims/integration/v1/claims/documents/upload' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: multipart/form-data; boundary=boundary'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/claims.openapi.json)

**Пример ответа (200)**

```json
{
  "file_key": "string"
}
```

**Описание полей ответа**
- `file_key` — Ключ файла в плюшкине

**Пример ответа (400)**

```json
{
  "error": "invalid_input_data",
  "reason": "Неверные входные данные."
}
```

**Описание полей ответа**
- `error` — Код ошибки
- `reason` — Описание ошибки


### Наименования юр. лиц ответчика

Возвращает известные наименования юр. лиц, связанных с указанным кодом фирмы в ATI.SU.

Метод вспомогательный: он помогает выбрать то наименование ответчика, которое затем передаётся при создании претензии.

<a id="get-integration-v1-claims-defendants"></a>

Получение имён ответчика из связанных фирм (внешние интеграторы)

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/gw/claims/integration/v1/claims/defendants?atiId=string' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/claims.openapi.json)

**Описание параметров запроса**
- `atiId (query, тип: string)` — Код фирмы ответчика в ATI.SU

**Пример ответа (200)**

```json
{
  "defendant_firms": [
    {
      "name": "string",
      "inn": "string"
    }
  ]
}
```

**Описание полей ответа**
- `defendant_firms` — Список связанных фирм ответчика
- `defendant_firms[].name` — Наименование связанной фирмы с формой собственности
- `defendant_firms[].inn` — ИНН связанной фирмы

**Пример ответа (400)**

```json
{
  "error": "invalid_input_data",
  "reason": "Неверные входные данные."
}
```

**Описание полей ответа**
- `error` — Код ошибки
- `reason` — Описание ошибки


### Создание претензии

Создаёт претензию с приложенными документами и публикует её от имени пользователя, которому принадлежит токен.

Набор обязательных документов зависит от типа претензии. Список обязательных документов для каждого типа Претензии определяется «[Положением о Претензиях](https://files.ati.su/static/front-files/claims-rules-policy.pdf)». Уровень созданной претензии система определяет сама по набору приложенных документов и возвращает в поле `claim_level`.

<a id="post-integration-v1-claims-add"></a>

Добавление новой претензии с прикрепленными документами для внешних интеграторов

**Пример запроса (curl):**

```bash
curl 'https://api.ati.su/gw/claims/integration/v1/claims/add' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "claim_type": {
    "claim_type": {
      "type_id": 0,
      "user_type": 0
    },
    "owner_firm": {
      "inn": "string"
    },
    "currency_id": 0,
    "total_sum": 0,
    "fail_to_pay_date": "1970-01-01T00:00:00Z",
    "substantiation": "string",
    "defendant_firm": {
      "ati_id": "string",
      "inn": "string",
      "city_name": "string",
      "ownership_id": 0,
      "firm_name": "string"
    },
    "document_files": [
      {
        "file_key": "string"
      }
    ]
  },
  "owner_firm": {
    "claim_type": {
      "type_id": 0,
      "user_type": 0
    },
    "owner_firm": {
      "inn": "string"
    },
    "currency_id": 0,
    "total_sum": 0,
    "fail_to_pay_date": "1970-01-01T00:00:00Z",
    "substantiation": "string",
    "defendant_firm": {
      "ati_id": "string",
      "inn": "string",
      "city_name": "string",
      "ownership_id": 0,
      "firm_name": "string"
    },
    "document_files": [
      {
        "file_key": "string"
      }
    ]
  },
  "currency_id": {
    "claim_type": {
      "type_id": 0,
      "user_type": 0
    },
    "owner_firm": {
      "inn": "string"
    },
    "currency_id": 0,
    "total_sum": 0,
    "fail_to_pay_date": "1970-01-01T00:00:00Z",
    "substantiation": "string",
    "defendant_firm": {
      "ati_id": "string",
      "inn": "string",
      "city_name": "string",
      "ownership_id": 0,
      "firm_name": "string"
    },
    "document_files": [
      {
        "file_key": "string"
      }
    ]
  },
  "total_sum": {
    "claim_type": {
      "type_id": 0,
      "user_type": 0
    },
    "owner_firm": {
      "inn": "string"
    },
    "currency_id": 0,
    "total_sum": 0,
    "fail_to_pay_date": "1970-01-01T00:00:00Z",
    "substantiation": "string",
    "defendant_firm": {
      "ati_id": "string",
      "inn": "string",
      "city_name": "string",
      "ownership_id": 0,
      "firm_name": "string"
    },
    "document_files": [
      {
        "file_key": "string"
      }
    ]
  },
  "fail_to_pay_date": {
    "claim_type": {
      "type_id": 0,
      "user_type": 0
    },
    "owner_firm": {
      "inn": "string"
    },
    "currency_id": 0,
    "total_sum": 0,
    "fail_to_pay_date": "1970-01-01T00:00:00Z",
    "substantiation": "string",
    "defendant_firm": {
      "ati_id": "string",
      "inn": "string",
      "city_name": "string",
      "ownership_id": 0,
      "firm_name": "string"
    },
    "document_files": [
      {
        "file_key": "string"
      }
    ]
  },
  "substantiation": {
    "claim_type": {
      "type_id": 0,
      "user_type": 0
    },
    "owner_firm": {
      "inn": "string"
    },
    "currency_id": 0,
    "total_sum": 0,
    "fail_to_pay_date": "1970-01-01T00:00:00Z",
    "substantiation": "string",
    "defendant_firm": {
      "ati_id": "string",
      "inn": "string",
      "city_name": "string",
      "ownership_id": 0,
      "firm_name": "string"
    },
    "document_files": [
      {
        "file_key": "string"
      }
    ]
  },
  "defendant_firm": {
    "claim_type": {
      "type_id": 0,
      "user_type": 0
    },
    "owner_firm": {
      "inn": "string"
    },
    "currency_id": 0,
    "total_sum": 0,
    "fail_to_pay_date": "1970-01-01T00:00:00Z",
    "substantiation": "string",
    "defendant_firm": {
      "ati_id": "string",
      "inn": "string",
      "city_name": "string",
      "ownership_id": 0,
      "firm_name": "string"
    },
    "document_files": [
      {
        "file_key": "string"
      }
    ]
  },
  "document_files": [
    {
      "file_key": "string"
    }
  ]
}'
```

**OpenAPI схема:** [JSON](https://ati.su/developers/raw/api/claims.openapi.json)

**Описание полей запроса**
- `claim_type` — DTO типа претензии
- `owner_firm` — Фирма истец
- `currency_id` — ID валюты выставляемой претензии
- `total_sum` — Сумма разногласий
- `fail_to_pay_date` — Дата наступления просрочки
- `substantiation` — Обоснование суммы претензии
- `defendant_firm` — Фирма ответчик
- `document_files` — Прикрепленные документы претензии
- `document_files[].file_key` — Ключ загруженного файла

**Пример ответа (200)**

```json
{
  "id": "00000000-0000-0000-0000-000000000000",
  "claim_level": 0
}
```

**Описание полей ответа**
- `id` — Идентификатор новой претензии
- `claim_level` — Уровень претензии (лайт / полная)

**Пример ответа (400)**

```json
{
  "error": "invalid_input_data",
  "reason": "Неверные входные данные."
}
```

**Описание полей ответа**
- `error` — Код ошибки
- `reason` — Описание ошибки
---

## llms.txt

Индекс ключевых страниц документации для LLM и AI-агентов доступен в [основном llms.txt](https://ati.su/developers/llms.txt).