# Общие методы

Данные методы работают со всеми типами документов

## Содержание:

- [Поиск документов пользователя](#post-gw-tokugawa-v1-common_api-documents-search)
- [Перенос документов в папку «Архив» или «Корзина» либо восстановление из них](#post-gw-tokugawa-v1-common_api-documents-%7baction%7d)

#### Поиск документов пользователя

Позволяет получить и отфильтровать список документов пользователя.

Можно указывать в теле запроса фильтры, например, по типу и/или нахождению документа в определенном разделе (например, во «Входящих»).
По умолчанию документы из папок «Черновики», «Архив», и «Корзина» не возвращаются (для их получения нужно передать соответствующие параметры).

<a id="post-v1-common_api-documents-search"></a>

Ищет документы по всем системам (ЭДО) для текущего пользователя.

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

```bash
curl 'https://api.ati.su/gw/tokugawa/v1/common_api/documents/search' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "limit": 50,
  "updated_at__lt": "2024-01-15T10:30:00Z",
  "filters": {
    "query": "string",
    "type": "СЧФ",
    "status": "AWAITING_CONFIRMATION_SIGN",
    "contragent_ati_code": "^\\d+$",
    "edo_user": "string",
    "number": "string",
    "date_from": "1970-01-01",
    "date_to": "1970-01-01",
    "direction": "incoming",
    "is_deleted": false,
    "is_archived": false,
    "is_template": false
  }
}'
```

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

**Описание полей запроса**
- `limit` — Максимальное количество документов в ответе (от 1 до 100).
- `updated_at__lt` — Курсор пагинации: возвращаются документы, у которых `updated_at` строго меньше указанного значения (UTC).
- `filters` — Набор фильтров, применяемых к списку документов.
- `filters.type` — An enumeration.
- `filters.status` — An enumeration.
- `filters.edo_user` — ID участника ЭДО(текущего пользователя)
- `filters.number` — Номер документа
- `filters.direction` — An enumeration.

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

```json
{
  "total": 1250,
  "total_remaining": 1200,
  "result": [
    {
      "id": "string",
      "is_riak": false,
      "direction": "incoming",
      "number": "string",
      "date": "1970-01-01",
      "type": "УПД. Счет-фактура",
      "status": "string",
      "is_read": false,
      "updated_at": "1970-01-01T00:00:00.000Z",
      "contragent": {
        "ati_code": "string",
        "name": "string"
      },
      "comments": {
        "count": 0,
        "tail": {
          "name": "string",
          "text": "string",
          "timestamp": "1970-01-01T00:00:00.000Z"
        }
      },
      "flags": [
        "string"
      ],
      "highlight": "failure",
      "signs": {
        "user": {
          "title": "string",
          "valid_from": "string",
          "valid_until": "string"
        },
        "contragent": {
          "title": "string",
          "valid_from": "string",
          "valid_until": "string"
        }
      },
      "template_name": "string",
      "roaming_provider_id": "string",
      "file_extension": "string"
    }
  ]
}
```

**Описание полей ответа**
- `total` — Общее количество документов, удовлетворяющих фильтрам.
- `total_remaining` — Количество документов, оставшихся после текущей страницы (для пагинации по курсору `updated_at__lt`). 0 означает, что это последняя страница.
- `result` — Список документов на текущей странице.
- `result[].direction` — An enumeration.
- `result[].type` — An enumeration.
- `result[].highlight` — An enumeration.

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

```json
{
  "error": true,
  "detail": {
    "code": "unprocessable_entity",
    "description": "Ошибка обработки тела запроса."
  },
  "extra": [
    {
      "loc": [
        "string"
      ],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

**Описание полей ответа**
- `error` — Признак ошибки (всегда `true` в ответах 422).
- `detail` — Код и человекочитаемое описание ошибки.
- `detail.code` — Код ошибки валидации.
- `detail.description` — Человекочитаемое описание ошибки.
- `extra` — Список ошибок валидации pydantic по каждому невалидному полю.
- `extra[].loc` — Путь до невалидного поля в структуре запроса.
- `extra[].msg` — Человекочитаемое сообщение об ошибке.
- `extra[].type` — Тип ошибки валидации pydantic.


#### Перенос документов в папку «Архив» или «Корзина» либо восстановление из них

Переносит указанный документ в указанную папку либо восставливает из нее. Может принимать несколько документов за раз.

«Action» может принимать значения «trash», «archive», «restore_from_trash» или «restore_from_archive». При невозможности выполнения действия возвращается id документа(-ов), по которым действие не произведено.

<a id="post-v1-common_api-documents-{action}"></a>

Массово перемещает документы в корзину/архив или восстанавливает их.

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

```bash
curl 'https://api.ati.su/gw/tokugawa/v1/common_api/documents/archive' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '[
  "5f3c8e2a1b2c3d4e5f6a7b8c",
  "5f3c8e2a1b2c3d4e5f6a7b8d"
]'
```

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

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

```json
[
  "string"
]
```

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

```json
{
  "error": true,
  "detail": {
    "code": "unprocessable_entity",
    "description": "Ошибка обработки тела запроса."
  },
  "extra": [
    {
      "loc": [
        "string"
      ],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

**Описание полей ответа**
- `error` — Признак ошибки (всегда `true` в ответах 422).
- `detail` — Код и человекочитаемое описание ошибки.
- `detail.code` — Код ошибки валидации.
- `detail.description` — Человекочитаемое описание ошибки.
- `extra` — Список ошибок валидации pydantic по каждому невалидному полю.
- `extra[].loc` — Путь до невалидного поля в структуре запроса.
- `extra[].msg` — Человекочитаемое сообщение об ошибке.
- `extra[].type` — Тип ошибки валидации pydantic.