API-документация по интеграции систем с информационной системой Udocs

Обновлено: 06.11.2026

Содержание

Общие сведения

Общий порядок формирования документа в ИС (информационной системе) Udocs:

  1. POST /api/client/auth/login — получение токена.
  2. GET /api/client/template/list — получение списка шаблонов, закреплённых за информационной системой.
  3. POST /api/client/document/exemplar — выбор одного из закреплённых шаблонов и получение соответствующего ему образца JSON.
  4. POST /api/client/document/create — создание документа; в ответе возвращаются поля документа guid и status.
  5. POST /api/client/document/access — получение одноразовой ссылки для просмотра и подписания документа, по которой пользователь перенаправляется в ИС Udocs.

ИС Udocs отправляет информационной системе, создавшей документ, уведомление о каждом действии с документом (каждом изменении его статуса). Для этого информационная система должна указать свой адрес для приёма уведомлений через POST /api/client/config/update (раздел 2, раздел 3).

Созданные документы можно получать списком, просматривать, скачивать и удалять через API из раздела 4.

Примечание. Во время тестирования необходимо включить в программе E-IMZO опцию «Режим разработчика» (“Dasturchi rejimi”).

Общие правила

Запросы и ответы передаются в формате JSON (Content-Type: application/json).

Во всех запросах, кроме входа (login), передаётся access_token, полученный в ответе на login, в следующем заголовке:

Authorization: Bearer <access_token>

Успешный ответ Udocs имеет следующую структуру:

Поле Тип Описание
success boolean true
data object Данные ответа
message string Текстовое сообщение

При ошибке возвращается success: false и поле errors вместо data:

{
  "success": false,
  "errors": {
    "signers.0.tin_pin": ["The signers.0.tin_pin field is required."]
  },
  "message": "Ma’lumotlar noto‘g‘ri kiritilgan yoki to‘ldirilmagan!"
}
HTTP-код Когда
200 Запрос выполнен
201 Документ создан (1.4, 5.1)
400 Запрос понят, но не может быть выполнен; причина — в message, errors пуст
401 Токен не передан, неверен или истёк
422 Ошибка проверки данных; в errors перечислены сообщения по каждому неверному полю

1. Порядок формирования и подписания документа

1.1. Получение токена доступа — Login

Информационная система отправляет в Udocs запрос с выданными ей учётными данными пользователя.

POST /api/client/auth/login
Content-Type: application/json

Тело запроса:

{
  "username": "foydalanuvchi",
  "password": "foydalanuvchi"
}

Ответ сервера:

{
  "success": true,
  "data": {
    "token": {
      "access_token": "eyJ0e...",
      "refresh_token": "",
      "expires_in": 1726706837000
    }
  },
  "message": "Successfully authorized"
}
Поле Описание
access_token Токен, передаваемый в заголовке Authorization: Bearer <access_token> последующих запросов
refresh_token Не используется, всегда пустой. После истечения токена выполните вход повторно
expires_in Время истечения срока действия токена (Unix-время в миллисекундах)

1.2. Получение списка шаблонов

Возвращает список шаблонов, закреплённых за информационной системой. Код шаблона из этого списка используется на следующих шагах.

GET /api/client/template/list
Authorization: Bearer <access_token>

Ответ сервера:

{
  "success": true,
  "data": {
    "templates": [
      {
        "name": "ariza",
        "description": "Udocs bilan integratsiya uchun ariza"
      }
    ]
  },
  "message": "Muvaffaqiyatli"
}
Поле Описание
templates[].name Код шаблона; передаётся как template на следующих шагах
templates[].description Название шаблона

1.3. Получение образца JSON документа

Возвращает образец JSON выбранного шаблона для создания документа. Запросить можно только шаблоны, закреплённые за вашей информационной системой.

POST /api/client/document/exemplar
Authorization: Bearer <access_token>
Content-Type: application/json

Тело запроса:

{
  "template": "ariza"
}

Ответ сервера:

{
  "success": true,
  "data": {
    "document": {
      "template": "ariza",
      "data": {
        "name": {
          "type": "STRING",
          "description": "Tashkilot nomi"
        },
        "tin": {
          "type": "STRING",
          "description": "Tashkilot STIRi"
        },
        "date": {
          "type": "DATE",
          "description": "Ariza sanasi"
        },
        "servis_fee": {
          "type": "NUMBER",
          "description": "Udocs bilan integratsiya uchun bir martalik to‘lov"
        },
        "services": {
          "type": "TABLE",
          "description": "Udocs ATda taqdim etishi kerak bo‘lgan xizmatlar",
          "columns": {
            "num": {
              "type": "NUMBER",
              "description": "Tartib raqam"
            },
            "name": {
              "type": "STRING",
              "description": "Xizmat nomi"
            },
            "purpose": {
              "type": "STRING",
              "description": "Xizmatga ulanish uchun asos"
            }
          }
        },
        "responsibles": {
          "type": "LIST",
          "description": "Integratsiya bo‘yicha mas’ul shaxslar",
          "items": {
            "num": {
              "type": "NUMBER",
              "description": "Tartib raqam"
            },
            "full_name": {
              "type": "STRING",
              "description": "Mas’ulning to‘liq ismi"
            },
            "phone": {
              "type": "STRING",
              "description": "Bog‘lanish uchun telefon raqam"
            }
          }
        },
        "logo": {
          "type": "Image",
          "description": "Tashkilot logotipi",
          "source": "client",
          "required": false
        }
      }
    }
  },
  "message": "Muvaffaqiyatli"
}

Каждый ключ объекта data.document.data — имя поля документа, а его значение описывает тип поля (type) и его описание (description). При создании документа (1.4) значения передаются под теми же ключами:

Тип Значение Что передавать при создании документа
STRING Текст Строка, например "Raqamli taraqqiyot MCHJ"
NUMBER Число Число, например 174500
DATE Дата Строка вида DD.MM.YYYY, например "10.11.2024"
TABLE Таблица; её столбцы описаны в columns Массив объектов, каждый объект — строка таблицы
LIST Список; поля элементов описаны в items Массив объектов, каждый объект — элемент списка
Image Изображение Для source: "client" — строка data:image/png;base64,... или data:image/jpeg;base64,.... Изображения с source: "static" заполняет Udocs, их не передают

Примечания:

  • Столбец TABLE сам может быть TABLE (вложенная таблица). Его значение — массив строк внутри каждой строки родительской таблицы.
  • Изображение обязательно передаётся при required: true, иначе его можно не передавать. Размер изображения — до 2048 КБ и до 4000×4000 пикселей.

1.4. Создание документа

Документ создаётся на основе шаблона. document.data заполняется по образцу, полученному в разделе 1.3.

POST /api/client/document/create
Authorization: Bearer <access_token>
Content-Type: application/json

Тело запроса:

{
  "document": {
    "template": "ariza",
    "data": {
      "name": "Raqamli taraqqiyot MCHJ",
      "tin": "311128291",
      "date": "10.11.2024",
      "servis_fee": 174500,
      "services": [
        {
          "num": 1,
          "name": "Shablon asosida hujjat yaratish",
          "purpose": "Erkin shakldagi shartnoma tuzish"
        }
      ],
      "responsibles": [
        {
          "num": 1,
          "full_name": "Zaripboyev Anvar",
          "phone": "(99) 512-32-64"
        }
      ],
      "logo": "data:image/png;base64,iVBORw0KGgo..."
    }
  },
  "signers": [
    {
      "tin_pin": 311128291,
      "branch": "00001"
    },
    {
      "tin_pin": 204118319
    }
  ]
}
Поле Обязательное Описание
document.template Да Код шаблона
document.data Да Значения полей документа
signers Да Список подписантов в порядке подписания. Первый подписант — создатель (владелец) документа, остальные — контрагенты
signers[].tin_pin Да ИНН подписанта (ПИНФЛ для физических лиц), число
signers[].branch Нет Код филиала, строка из 5–8 цифр; указывается, если у организации есть филиал
signers[].trusted_signers Нет Лица, которые могут подписать вместо этого подписанта: [{"tin_pin": 123456789, "expires_at": "2026-12-31"}]

При создании документа значения полей проверяются:

  • поля NUMBER должны быть числами, поля DATE — корректной датой;
  • каждый ключ TABLE и LIST должен присутствовать (допускается пустой массив); каждый столбец / поле элемента в строке должен быть заполнен;
  • если у шаблона нет активной версии или шаблон не закреплён за вашей информационной системой, документ не создаётся.

Ответ сервера (HTTP 201):

{
  "success": true,
  "data": {
    "document": {
      "guid": "b498e2d6-e71f-4951-8f92-c22617a2d2f1",
      "status": "created"
    }
  },
  "message": "Muvaffaqiyatli"
}

Важно. Документ подписывается в той последовательности подписантов, которую информационная система указала в массиве signers тела запроса. Если шаблон настроен на подписание в произвольном порядке, контрагенты могут подписывать в любом порядке.

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

Документ подписывается на странице подписания клиентских документов ИС Udocs или в личном кабинете пользователя.

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

POST /api/client/document/access
Authorization: Bearer <access_token>
Content-Type: application/json

Тело запроса:

{
  "guid": "b498e2d6-e71f-4951-8f92-c22617a2d2f1",
  "tin_pin": "311128291",
  "redirect_url": "https://joriy.uz"
}
Поле Обязательное Описание
guid Да Идентификатор документа (из ответа 1.4)
tin_pin Да ИНН подписанта; должен быть одним из подписантов документа, иначе возвращается ошибка
redirect_url Да Адрес информационной системы, на который пользователь возвращается со страницы подписания
disable Нет Скрывает одну кнопку действия на странице подписания: accept, reject или cancel

Ответ сервера:

{
  "success": true,
  "data": {
    "url": "<адрес страницы подписания>/b498e2d6-e71f-4951-8f92-c22617a2d2f1?token=...&redirect_url=https%3A%2F%2Fjoriy.uz&host_url=..."
  },
  "message": "Muvaffaqiyatli"
}

data.url — одноразовая ссылка на страницу подписания. Пользователь перенаправляется по этой ссылке.

Рекомендация. Не сохраняйте ссылку на страницу подписания: запрашивайте новую у Udocs каждый раз, когда пользователь нажимает кнопку подписания. Ссылка ограничена по сроку действия и количеству использований.

Только просмотр. Чтобы показать документ без кнопок подписания, получите ссылку на просмотр:

POST /api/client/document/view
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "guid": "b498e2d6-e71f-4951-8f92-c22617a2d2f1",
  "redirect_url": "https://joriy.uz"
}

Ответ имеет тот же вид: data.url — ссылка на страницу просмотра. redirect_url необязателен.

1.6. Статусы документа в системе

Статус (status) Описание
created Документ создан; создатель его ещё не подписал
process Создатель (или один из контрагентов) подписал, остальные подписанты ещё не подписали
accepted Документ подписан всеми подписантами
rejected Контрагент отклонил документ
cancelled Создатель отменил документ после его подписания
revoked Создатель отозвал уже принятый документ
deleted Создатель удалил документ до его подписания. Этот статус приходит только в уведомлении (раздел 2); документ больше недоступен

Обычный порядок: created → process → accepted (или rejected). Если подписант только один — создатель, документ переходит из created сразу в accepted.

2. Обновление статуса документа в других системах (уведомления)

Когда с документом выполняется действие (например, контрагент принимает или отклоняет его, либо создатель отменяет), ИС Udocs отправляет уведомление информационной системе, создавшей документ. Благодаря этому статус документа в Udocs и в подключённой информационной системе совпадает.

Для получения уведомлений информационная система обязана зарегистрировать в Udocs свой API-адрес (раздел 3).

ИС Udocs отправляет на зарегистрированный информационной системой адрес следующий запрос:

POST <адрес, зарегистрированный информационной системой>
Content-Type: application/json

Заголовок авторизации передаётся в соответствии с auth_type, выбранным информационной системой в разделе 3.

Тело запроса:

{
  "document": {
    "guid": "4e197072-62f0-47f4-aa2c-078403bbdd50",
    "status": "rejected",
    "template": "ariza"
  },
  "signer": {
    "tin_pin": "311128291",
    "branch": "00001",
    "action": "reject",
    "note": "Yoqmadi",
    "signed_at": "2024-02-10 15:45:00"
  }
}
Поле Описание
document.guid Идентификатор документа
document.status Новый статус документа (1.6)
document.template Шаблон документа
signer.tin_pin ИНН подписанта, выполнившего действие
signer.branch Код филиала; может быть null
signer.action Выполненное действие (см. таблицу ниже)
signer.note Причина отклонения или отзыва. Заполняется только при отклонении или отзыве документа, в остальных случаях — null
signer.signed_at Время подписания (выполнения действия) в формате YYYY-MM-DD HH:MM:SS
signer.deleted_at Только в уведомлении delete: время удаления в формате YYYY-MM-DD HH:MM:SS

Значения signer.action:

Значение document.status после действия Описание
sign process или accepted Создатель подписал
accept process или accepted Контрагент подписал и принял
reject rejected Контрагент отклонил
cancel cancelled Создатель отменил (только после подписания создателем)
revoke revoked Создатель отозвал принятый документ
delete deleted Создатель удалил документ (удалить можно только неподписанный документ в статусе created)

Примечание. После sign или accept статус равен process, пока остаются неподписавшие подписанты, и accepted, когда подписали все.

Ответ информационной системы: Udocs принимает любой ответ с HTTP-кодом 2xx (200–299); тело ответа может быть любым. Любой другой код, превышение времени ожидания или ошибка соединения считаются неудачной доставкой.

2.1. Повторная отправка уведомлений

Udocs сохраняет каждое отправленное уведомление. Неудачная доставка автоматически не повторяется; когда ваша система снова доступна, запросите повторную отправку:

POST /api/client/document/sync
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "guid": "4e197072-62f0-47f4-aa2c-078403bbdd50"
}

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

POST /api/client/document/retry
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "guid": "4e197072-62f0-47f4-aa2c-078403bbdd50"
}

Повторно отправляет уведомление о последнем действии с документом. Возвращает ошибку, если документ ещё никто не подписал.

Оба запроса отвечают "success": true с пустым data; сами уведомления отправляются в фоне.

3. Дополнительные настройки

Задаёт адрес для приёма уведомлений и способ авторизации, который Udocs использует при обращении к нему.

POST /api/client/config/update
Authorization: Bearer <access_token>
Content-Type: application/json

Тело запроса:

{
  "url": "https://joriy.uz",
  "auth_type": 3,
  "header_key": "TOKEN",
  "token": "<API_KEY>"
}

Ответ сервера — сохранённые настройки возвращаются в том виде, в котором были отправлены:

{
  "success": true,
  "data": {
    "url": "https://joriy.uz",
    "auth_type": 3,
    "header_key": "TOKEN",
    "token": "<API_KEY>"
  },
  "message": "Muvaffaqiyatli"
}
Поле Когда нужно Описание
url Всегда Адрес для приёма уведомлений
auth_type Всегда Тип авторизации (см. таблицу ниже)
username auth_type = 1 Имя пользователя
password auth_type = 1 Пароль
token auth_type = 2 или 3 Токен или значение API-ключа
header_key auth_type = 3 Имя заголовка, в котором передаётся API-ключ
auth_type Тип Необходимые поля Заголовок, который отправляет Udocs
0 Открытый (без авторизации) — —
1 Базовый (Basic Auth) username, password Authorization: Basic <base64(username:password)>
2 Bearer token Authorization: Bearer <token>
3 По ключу (API key) header_key, token <header_key>: <token>

auth_type: 0 — Открытый

{
  "url": "https://joriy.uz",
  "auth_type": 0
}

auth_type: 1 — Базовый (Basic Auth)

{
  "url": "https://joriy.uz",
  "auth_type": 1,
  "username": "foydalanuvchi",
  "password": "foydalanuvchi"
}

auth_type: 2 — Bearer

{
  "url": "https://joriy.uz",
  "auth_type": 2,
  "token": "eyJ0e..."
}

Передавайте токен без префикса Bearer — Udocs добавляет его сам.

auth_type: 3 — По ключу (API key)

{
  "url": "https://joriy.uz",
  "auth_type": 3,
  "header_key": "TOKEN",
  "token": "<API_KEY>"
}

4. Работа с документами

Все запросы этого раздела требуют заголовка Authorization: Bearer <access_token>.

Список созданных документов

GET /api/client/documents?from_date=2026-11-01&to_date=2026-11-30&page=1
Параметр Обязательный Описание
from_date Нет Созданные начиная с этой даты, YYYY-MM-DD
to_date Нет Созданные по эту дату включительно, YYYY-MM-DD
page Нет Номер страницы; 20 документов на странице

Возвращает документы, созданные вашей информационной системой, постранично: в data.documents.data — документы (guid, status, created_at и другие поля), а в data.documents также current_page, last_page, per_page и total.

Сведения о документе

GET /api/client/documents/{guid}

{
  "success": true,
  "data": {
    "guid": "b498e2d6-e71f-4951-8f92-c22617a2d2f1",
    "status": "process",
    "data": { "name": "Raqamli taraqqiyot MCHJ", "...": "..." },
    "signers": [
      { "tin_pin": "311128291", "name": "RAQAMLI TARAQQIYOT MCHJ", "signerResult": "accept" },
      { "tin_pin": "204118319", "name": "...", "signerResult": "unsigned" }
    ],
    "type": { "code": "clientDocuments", "name": "..." },
    "template": { "name": "ariza", "title": "...", "category": "...", "type": "..." },
    "created_at": "10.11.2024 15:45:00"
  },
  "message": "Muvaffaqiyatli"
}

data — данные документа, переданные при создании. signers[].signerResult равен unsigned, пока подписант не выполнил действие, затем — действие подписанта.

История подписания

GET /api/client/documents/{guid}/steps

{
  "success": true,
  "data": {
    "document": {
      "guid": "b498e2d6-e71f-4951-8f92-c22617a2d2f1",
      "status": "accepted",
      "steps": [
        { "signer": "RAQAMLI TARAQQIYOT MCHJ", "tin_pin": "311128291", "signed_at": "2024-11-10 15:45:00", "action": "sign" },
        { "signer": "...", "tin_pin": "204118319", "signed_at": "2024-11-11 09:12:30", "action": "accept" }
      ],
      "created_at": "2024-11-10 15:40:00"
    }
  },
  "message": "Muvaffaqiyatli"
}

steps[].action принимает значения signer.action из раздела 2.

Файлы документа

GET /api/client/documents/{guid}/pdf
GET /api/client/documents/{guid}/pdf?signers=1
GET /api/client/documents/{guid}/word

pdf возвращает сам PDF-файл. С signers=1 в PDF добавляются подписи и QR-код. word возвращает JSON: в data.file — Word-файл в кодировке base64.

Удаление документа

DELETE /api/client/documents/{guid}

Удалить можно только документ в статусе created (ещё не подписанный). После удаления Udocs отправляет уведомление delete (раздел 2).

Справочник статусов

GET /api/client/document/statuses

Возвращает data.statuses — значения статусов документов, используемые в Udocs.

5. Прочие API

5.1. Создание документа (формат v2)

Альтернативный формат 1.4: значения полей передаются прямо в document, создатель указывается отдельно в owner, а номер и дату документа можно задать в default.

Образец для шаблона:

GET /api/client/document/example?template=ariza
Authorization: Bearer <access_token>

Ответ содержит образец тела запроса для этого шаблона: template, default, document (примерные значения полей), owner, signers и images (для каждого клиентского изображения: размер, обязательность, допустимые типы и ограничения). Замените template.code в образце на код вашего шаблона.

Создание:

POST /api/client/v2/document/create
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "template": { "code": "ariza" },
  "default": { "number": "TSH-101", "date": "2024-11-10" },
  "document": {
    "name": "Raqamli taraqqiyot MCHJ",
    "date": "10.11.2024",
    "services": [{ "num": 1, "name": "Shablon asosida hujjat yaratish", "purpose": "Erkin shakldagi shartnoma tuzish" }]
  },
  "owner": { "tin_pin": 311128291, "branch": "00001" },
  "signers": [{ "tin_pin": 204118319 }]
}
Поле Обязательное Описание
template.code Да Код шаблона
default.number Нет Номер документа
default.date Нет Дата документа
document Да Значения полей документа (правила те же, что для document.data в 1.4)
owner.tin_pin, owner.branch Да / Нет Создатель (владелец) документа
signers[].tin_pin, signers[].branch Да / Нет Контрагенты в порядке подписания

Ответ такой же, как в 1.4 (HTTP 201).

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

POST /api/client/document/retry-facture
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "contract_number": "12/2024"
}

Только для информационных систем, подключённых к уведомлениям по счёт-фактурам: повторно отправляет уведомление о счёт-фактуре с этим номером договора.

5.3. Подписание через API (устарело)

POST /api/client/document/sign устарел. Документы подписываются на странице подписания Udocs (1.5).

Использованная литература и источники

API документация — UDOCS