# Неформализованные документы

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

:::caution
**_Список поддерживаемых типов документов:_**

- акт
- доверенность
- договор
- заказ
- заказ (табличный вид)
- заявка (к договору)
- заявка к договору (табличный вид)
- поручение экспедитору
- счет
- другой
  :::

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

- [Последовательность вызовов для отправки документа с подписанием](#schema)
- [Создание и редактирование документа](#post-v1.0-atidocs-documents-)
- [Прикрепление вложения к документу](#post-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-attachments-)
- [Отправка документа](#put-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-send-)
- [Экспорт документа для подписания](#post-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-export-)
- [Подписание документа](#put-v1.0-atidocs-documents-%7bdoc_id%7d-sign-)
- [Добавление комментария к документу](#post-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-comments-)
- [Отзыв документа](#put-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-revoke-)
- [Получение документа](#get-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-)
- [Одобрить документ](#put-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-approve-)
- [Отклонить документ](#put-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-decline-)
- [Скачать вложение к документу (тело документа)](#get-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-attachments-%7battachment_id%7d-)
- [Скачать zip-архив документа с вложениями и подписями](#get-v1.0-atidocs-documents-%7bdoc_id%7d-zip_archive-)
- [Список неформализованных документов в АТИ-Доках](#doctypes)

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

В данном случае действия выполняются от лица отправителя

1. [Создание документа](<(#post-v1.0-atidocs-documents-)>)
2. [Прикрепление вложения к документу](#post-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-attachments-)
3. [Отправка документа](#put-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-send-)

Если вы хотите отправить документ с подписанием, то после нужно выполнить дополнительные действия:

4. [Экспорт документа для подписания](#post-gw-atidocs-api-2.0-documents-%7bdoc_id%7d-export-)
5. Формирование подписи (выполняется на вашей стороне)
6. [Подписание документа](#put-v1.0-atidocs-documents-%7bdoc_id%7d-sign-)

#### Создание и редактирование документа

Позволяет создать черновик документа или обновить существующий документ. В методе передаётся общая метаинформация о документе. Список доступных `doctype` указан в [разделе](https://ati.su/developers/raw/api/doki/informal.md#doctypes).

<a id="post-v1.0-atidocs-documents-"></a>

Создание и/или сохранение документа

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

```bash
curl 'https://api.ati.su/v1.0/atidocs/documents/' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "date": "1970-01-01",
  "doc_recipient_contact": "string",
  "doc_request": false,
  "doc_sender_contact": "string",
  "doctype": "акт",
  "id": "string",
  "number": "string",
  "xmlBody": "string"
}'
```

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

**Описание полей запроса**
- `date` — Дата документа
- `doc_recipient_contact` — Код пользователя в ATI.SU в формате .
- `doc_request` — Флаг запроса решения для документа. Если это поле не передается, то для новых документов запрос решения остается без изменений. Если это передается, то в документе для флага будет использовано переданное значение.
- `doc_sender_contact` — Код пользователя в ATI.SU в формате .
- `doctype` — Тип документа
- `id` — Идентификатор документа
- `number` — Номер документа
- `xmlBody` — Тело документа в формате xml, в виде строки

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

```json
{
  "ok": true,
  "result": "12345676554321"
}
```

**Описание полей ответа**
- `result` — Идентификатор документа


#### Прикрепление вложения к документу

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

<a id="post-gw-atidocs-api-2.0-documents-{doc_id}-attachments-"></a>

Сохранить вложение

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

```bash
curl 'https://api.ati.su/gw/atidocs/api/2.0/documents/string/attachments/' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: multipart/form-data; boundary=boundary'
```

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

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

```json
{
  "ok": false,
  "result": "string"
}
```

**Описание полей ответа**
- `result` — id документа

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

```json
{
  "error": "not_found",
  "reason": "Объект не найден"
}
```


#### Отправка документа

Предполагается, что документ уже сохранен и имеет приложенное вложение.

<a id="put-gw-atidocs-api-2.0-documents-{doc_id}-send-"></a>

Отправить документ

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

```bash
curl 'https://api.ati.su/gw/atidocs/api/2.0/documents/string/send/?receiver=string' \
  -X 'PUT' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

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

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

```json
{
  "ok": false,
  "result": "string"
}
```

**Описание полей ответа**
- `result` — id документа

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

```json
{
  "error": "document_no_receiver",
  "reason": "Не найден аккаунт получателя"
}
```


#### Экспорт документа для подписания

Получает тело документа в виде строки, которая подходит для подписания.

<a id="post-gw-atidocs-api-2.0-documents-{doc_id}-export-"></a>

Экспорт документа для подписи

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

```bash
curl 'https://api.ati.su/gw/atidocs/api/2.0/documents/string/export/' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

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

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

```json
{
  "ok": false,
  "result": "string"
}
```

**Описание полей ответа**
- `result` — id документа

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

```json
{
  "error": true,
  "reason": "Документ не найден"
}
```


#### Подписание документа

При помощи криптографических инструментов подписывает строку, которую вернул метод экспорта.
При подписании сервер выполняет проверку подписи: сертификат клиента должен
быть выдан доверенным УЦ.

Поле «sign» может быть представлено в одном из двух форматов:
- base64-строка, которая представляет собой подпись документа 
- бинарный файл, который содержит подпись документа

Если документ требовал решения, то документ автоматически одобряется.

[Более подробная информация про процесс подписания](https://ati.su/developers/raw/api/doki/signing.md)

<a id="put-v1.0-atidocs-documents-{doc_id}-sign-"></a>

Подписание документа

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

```bash
curl 'https://api.ati.su/v1.0/atidocs/documents/string/sign/' \
  -X 'PUT' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: multipart/form-data; boundary=boundary' \
  --data-raw '{
  "sign": "string"
}'
```

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

**Описание полей запроса**
- `sign` — Подпись документа в виде base64-строки

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

```json
{
  "ok": true,
  "result": "12345676554321"
}
```

**Описание полей ответа**
- `result` — Идентификатор документа

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

```json
{
  "error": "bad_request",
  "reason": "Ошибка в запросе"
}
```

**Описание полей ответа**
- `error` — Код ошибки
- `reason` — Описание ошибки и возможная причина


#### Добавление комментария к документу

Позволяет загрузить как текст, так и файл. Обязательное условие: текст/файл должен пересылаться как «multipart/form-data». При загрузке файлов применяются общие ограничения по типу поддерживаемых файлов. Размер файла не должен превышать 10 Мб.

<a id="post-gw-atidocs-api-2.0-documents-{doc_id}-comments-"></a>

Оставить комментарий к документу

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

```bash
curl 'https://api.ati.su/gw/atidocs/api/2.0/documents/string/comments/' \
  -X 'POST' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: multipart/form-data; boundary=boundary'
```

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

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

```json
{
  "timestamp": "2020-02-26T15:24:00.000Z",
  "text": "string",
  "has_attachments": false,
  "attachment": {
    "id": "95a971edb0994372aa6b76a9e1be8bdb",
    "size": 429939,
    "name": "Книга новичка АТИ.pdf",
    "mimetype": "application/pdf"
  },
  "user": {
    "id": "765044.0",
    "fn": "wefwef_1!"
  }
}
```

**Описание полей ответа**
- `text` — Текст сообщения
- `attachment` — Данные вложения
- `attachment.size` — Размер файла
- `attachment.name` — Название файла
- `user` — Данные пользователя
- `user.id` — ati id
- `user.fn` — Имя юзера

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

```json
{
  "error": "bad_request",
  "reason": "Нельзя отправить пустой комментарий"
}
```


#### Отзыв документа

Метод доступен отправителю. После отзыва документ «пропадает» у получателя и переносится в папку «Черновики».
Отозвать можно только отправленный документ.

<a id="put-gw-atidocs-api-2.0-documents-{doc_id}-revoke-"></a>

Отозвать отправленный документ и сделать его черновиком

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

```bash
curl 'https://api.ati.su/gw/atidocs/api/2.0/documents/string/revoke/' \
  -X 'PUT' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

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

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

```json
{
  "ok": false,
  "result": "string"
}
```

**Описание полей ответа**
- `result` — id документа

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

```json
{
  "error": true,
  "reason": "Не указана причина отзыва документа"
}
```


#### Получение документа

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

<a id="get-gw-atidocs-api-2.0-documents-{doc_id}-"></a>

Получение документа

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

```bash
curl 'https://api.ati.su/gw/atidocs/api/2.0/documents/string/' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

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

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

```json
{
  "ok": true,
  "result": {
    "doctype": "Тип документа",
    "sender": {
      "ati_id": "0",
      "name": "Имя",
      "user": {
        "ati_id": "0",
        "name": "Имя пользователя",
        "department_id": "0"
      },
      "status": "Статус документа",
      "inn": ""
    },
    "receiver": {
      "ati_id": "0",
      "name": "Имя",
      "user": {
        "ati_id": "0",
        "name": "Имя пользователя",
        "department_id": "0"
      },
      "status": "Статус документа"
    },
    "file": {
      "mimetype": "application/vnd.ati-docs.xml",
      "name": "000.xml",
      "xml_template": "order",
      "timestamp": "2022-06-30T12:44:30Z",
      "size": 9659,
      "id": "00000"
    },
    "id": "00000",
    "date": "2022-06-30",
    "number": "1",
    "updated": "2022-06-30T12:44:28Z",
    "fix_price": {
      "id": "00000",
      "link": "",
      "original_owner": "0",
      "contact_1": "0",
      "contact_2": "",
      "document_creator": "0"
    },
    "flags": [
      "is_sent",
      "is_waiting",
      "can_be_deleted",
      "can_be_archived",
      "can_be_signed",
      "can_be_declined",
      "can_be_revoked",
      "can_be_templated"
    ]
  }
}
```

**Описание полей ответа**
- `result.doctype` — Тип документа
- `result.sender` — Отправитель документа
- `result.sender.ati_id` — Идентификатор фирмы в ATI.SU (код в АТИ)
- `result.sender.name` — Название фирмы
- `result.sender.user.ati_id` — Идентификатор фирмы и контакта
- `result.sender.user.name` — Название контакта
- `result.receiver` — Получатель документа
- `result.receiver.ati_id` — Идентификатор фирмы в ATI.SU (код в АТИ)
- `result.receiver.name` — Название фирмы
- `result.receiver.user.ati_id` — Идентификатор фирмы и контакта
- `result.receiver.user.name` — Название контакта
- `result.file.mimetype` — mimetype файла
- `result.file.name` — Имя файла
- `result.file.timestamp` — Дата и время загрузки файла
- `result.file.size` — Размер файла в байтах
- `result.file.id` — Идентификатор файла
- `result.id` — Идентификатор документа
- `result.number` — Номер документа
- `result.updated` — Дата и время последнего обновления документа
- `result.fix_price` — Информация о прикрепленном заказе
- `result.fix_price.id` — Идентификатор заказа
- `result.fix_price.link` — Ссылка на заказ
- `result.flags` — Флаги документа сообщающие о доступных действиях

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

```json
{
  "error": false,
  "reason": "Документ не найден"
}
```


#### Одобрить документ

Метод доступен получателю. Одобрить можно только документ, ожидающий решения.

<a id="put-gw-atidocs-api-2.0-documents-{doc_id}-approve-"></a>

Одобрить документ

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

```bash
curl 'https://api.ati.su/gw/atidocs/api/2.0/documents/string/approve/' \
  -X 'PUT' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

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

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

```json
{
  "ok": false,
  "result": "string"
}
```

**Описание полей ответа**
- `result` — id документа

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

```json
{
  "error": "document_can_not_be_approved",
  "reason": "Документ не может быть одобрен"
}
```


#### Отклонить документ

Метод доступен получателю. Отклонить можно только документ, ожидающий решения.

<a id="put-gw-atidocs-api-2.0-documents-{doc_id}-decline-"></a>

Отклонить документ

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

```bash
curl 'https://api.ati.su/gw/atidocs/api/2.0/documents/string/decline/' \
  -X 'PUT' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "reason": "string"
}'
```

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

**Описание полей запроса**
- `reason` — Текст комментария

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

```json
{
  "ok": false,
  "result": "string"
}
```

**Описание полей ответа**
- `result` — id документа

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

```json
{
  "error": "document_can_not_be_changed",
  "reason": "Документ невозможно изменить, так как вторая сторона приняла по нему решение. Обновите страницу, чтобы продолжить работу"
}
```


#### Скачать вложение к документу (тело документа)

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

<a id="get-gw-atidocs-api-2.0-documents-{doc_id}-attachments-{attachment_id}-"></a>

Получить вложение по id документа

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

```bash
curl 'https://api.ati.su/gw/atidocs/api/2.0/documents/string/attachments/string/' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

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

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

```json
{}
```

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

```json
{
  "error": "not_found",
  "reason": "Документ не найден"
}
```


#### Скачать zip-архив документа с вложениями и подписями

Позволяет скачать zip-архив документа, только если у документа есть подпись хотя бы с одной стороны.

<a id="get-v1.0-atidocs-documents-{doc_id}-zip_archive-"></a>

Скачать zip-архив документа с вложениями и подписями

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

```bash
curl 'https://api.ati.su/v1.0/atidocs/documents/string/zip_archive/' \
  -X 'GET' \
  -H 'Authorization: Bearer {authorizationToken}' \
  -H 'Content-Type: application/json'
```

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

## llms.txt

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