API — integratorlar uchun
O'z tizimingizdan (skript, ERP, EDO) Muhrdor serverida ERI bilan imzolang — bitta hujjat yoki 200 tagacha partiya. Kalit HSM dan chiqmaydi va sizga berilmaydi: sizning xizmat akkauntingiz kalit egasi imzolagan huquq akti doirasida, aktda nomlangan saytlar va hujjat turlari uchun imzolaydi. Har imzo kalit egasining audit jurnalida «API» belgisi bilan.
- Mashina o'qiydigan shartnoma:
GET https://muhrdor.uz/api/v1/openapi.json(repo dadocs/api/openapi-integrators.json) - To'liq ma'lumotnoma (har endpoint, maydonlar): reference.md
- Xatolar katalogi: errors.md
- Tayyor misol (faqat Python stdlib):
examples/muhrdor_sign.py - Sim formati batafsil:
docs/protocols/api-v1-service-account.md
1. Tayyorgarlik (bir marta)
- Xizmat akkaunti. Muhrdor panelida (ERI bilan tasdiqlangan akkaunt) → «API kalitlari» → nom yozing → «Yaratish».
client_id(sa_…) vaclient_secretchiqadi — secret faqat shu oynada, bir marta. Uni skript sozlamasiga (muhit o'zgaruvchisi) saqlang, kodga emas. - Akt.
client_idni kalit egasiga yuboring (masalan, mijoz korxona rahbariga). U panelda «Huquqlar → Huquq berish → Xizmat akkaunti (client_id)» → «Topish» (sizning akkaunt nomingiz va ismingizni ko'radi) → sayt(lar) va hujjat turlari → muddat → «Aktni imzolash». Xizmat akkauntiga «barcha saytlar» berilmaydi: har sayt aktda nomlanadi. - Tekshiring:
GET /api/v1/client/credentialskalitniaccess: "grant"va akt doirasi bilan ko'rsatadi.
2. Tez boshlash
export MUHRDOR_CLIENT_ID=sa_... export MUHRDOR_CLIENT_SECRET=... python examples/muhrdor_sign.py --site my.soliq.uz --credential <credential_id> hisobot.xml # -> hisobot.xml.p7b va "hisobot.xml: <audit_ref>"
curl bilan:
TOKEN=$(curl -s https://muhrdor.uz/api/v1/token -H 'Content-Type: application/json' \
-d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$MUHRDOR_CLIENT_ID\",\"client_secret\":\"$MUHRDOR_CLIENT_SECRET\"}" \
| jq -r .access_token)
curl -s https://muhrdor.uz/api/v1/client/credentials -H "Authorization: Bearer $TOKEN"
curl -s https://muhrdor.uz/api/v1/signatures/sign -H "Authorization: Bearer $TOKEN" \
-H 'Idempotency-Key: hisobot-2026-09-0001' -H 'Content-Type: application/json' \
-d '{"credential_id":"…","site":"my.soliq.uz","documents":[{"content_b64":"…","external_ref":"hisobot-9"}]}'3. Qadamlar
- Token —
POST /api/v1/token{grant_type: "client_credentials", client_id, client_secret}→access_token, 1 soat. Refresh yo'q: 401 kelsa yangisini oling. Har so'rovga yangi token olmang (soatiga 30 ta chegara). - Kalitlar —
GET /api/v1/client/credentials:credential_idva akt doirasi. - Imzolash —
POST /api/v1/signatures/sign:site— hujjat qaysi sayt uchun (aktda bo'lishi shart);documents[]— 1..200, jami 5 MiB;content_b64,detached(sukuttrue— PKCS#7 da kontent yo'q;false— kontent ichida),external_ref— sizning hujjat raqamingiz (≤64,A-Z a-z 0-9 . _ : / -), javobda qaytadi va jurnalda saqlanadi;Idempotency-Keymajburiy — har yangi so'rovga yangi kalit (masalan UUID). Javob:results[i]—pkcs7_b64(DER PKCS#7, E-IMZO shakli),audit_ref,doc_class,external_ref; rad etilgan hujjatdaerror.
- Natija keyin —
GET /api/v1/signatures/{audit_ref}?credential_id=<kalit>: imzo qismlari va PKCS#7 xeshi (PKCS#7 ning o'zi serverda saqlanmaydi —.p7bni o'zingiz saqlang).
4. Qayta yuborish — ikki marta imzolamaslik
Tarmoq uzildi, javob kelmadi — xuddi shu Idempotency-Key va xuddi shu tana bilan qayta yuboring: 10 daqiqa ichida server birinchi javobni qaytaradi, ikkinchi imzo bo'lmaydi.
409 request_in_progress— birinchisi hali ishlayapti: bir soniyadan keyin shu kalit bilan.422 idempotency_mismatch— bu kalit boshqa tana uchun ishlatilgan: yangi so'rov — yangi kalit.429 too_many_requests—Retry-Aftersoniya kuting.502 signing_failed+retryable: true— shu kalit bilan bir marta qayta.403 policy_denied— qayta yubormang: akt yetmaydi (reason— sabab).
5. Saytlar va hujjat turlari
Hujjat turi (doc_class) kontentdan aniqlanadi. Akt doc_kinds da nomlagan turlar o'tadi.
| Sayt | Turlar |
|---|---|
my.soliq.uz | hisobot, login |
didox.uz | factura, qabul, hujjat, login |
xt-xarid.uz | hash32 |
my.it-park.uz | login |
Boshqa XML/JSON — tuzilma turi (xml:<ildiz element>, json:<xesh>): kalit egasi uni aktda aniq yozsa o'tadi. Tanilmagan kontent — UNCLASSIFIED_CONTENT. Qaysi tur kerakligini bilish: rad javobining detail i va kalit egasining panelidagi «Rad etilgan so'rovlar» turini ko'rsatadi — egasi uni aktga qo'shadi. Yangi sayt — Muhrdor adapteri kerak (bizga yozing).
6. Chegaralar
| Nima | Chegara |
|---|---|
| Token | 1 soat; soatiga 30 ta (har client_id) |
| Bitta so'rov | 200 hujjat, jami 5 MiB |
| Imzo tezligi | daqiqasiga 600 hujjat (har xizmat akkaunti; server sozlamasi) |
| Idempotentlik oynasi | 10 daqiqa |
| Faol xizmat akkauntlari | 10 ta (har shaxs) |
7. Maxfiylik va jurnal
Hujjat mazmuni saqlanmaydi. Jurnalda: kontent va imzolangan atributlar xeshi, hujjat turi, sayt, page_url (query siz), hujjat raqami/davri (sayt maydonlari xaritasidan, summasiz), sizning external_ref, akt havolasi, client: "api". external_ref ga shaxsiy ma'lumot (JSHSHIR, ism) yozmang — bu identifikator.
8. Xavfsizlik
- Secret faqat yaratish yoki «Secretni yangilash» paytida ko'rinadi; yo'qolsa — yangilang (eski secret va tokenlar darhol o'ladi).
- Akkaunt keraksiz bo'lsa — «O'chirish» (qaytarilmas). Kalit egasi aktni istalgan vaqt bekor qiladi — keyingi so'rov rad etiladi.
- API tokeni odam endpointlarini ochmaydi: faqat token,
client/*vasignatures/*.
Подписывайте ЭЦП на сервере Muhrdor из своей системы (скрипт, ERP, ЭДО) — один документ или пакет до 200. Ключ не покидает HSM и вам не выдаётся: ваш сервисный аккаунт подписывает в рамках акта о предоставлении права, подписанного владельцем ключа, для сайтов и типов документов, названных в акте. Каждая подпись — в журнале аудита владельца ключа с отметкой «API».
- Машиночитаемый контракт:
GET https://muhrdor.uz/api/v1/openapi.json(в репозиторииdocs/api/openapi-integrators.json) - Полный справочник (каждый endpoint, поля): reference.md
- Каталог ошибок: errors.md
- Готовый пример (только Python stdlib):
examples/muhrdor_sign.py - Формат обмена подробно:
docs/protocols/api-v1-service-account.md
1. Подготовка (один раз)
- Сервисный аккаунт. В панели Muhrdor (аккаунт, подтверждённый ЭЦП) → «API-ключи» → введите название → «Создать». Появятся
client_id(sa_…) иclient_secret— секрет только в этом окне, один раз. Сохраните его в настройках скрипта (переменная окружения), не в коде. - Акт. Отправьте
client_idвладельцу ключа (например, руководителю компании-клиента). Он в панели: «Права → Выдать право → Сервисный аккаунт (client_id)» → «Найти» (увидит название вашего аккаунта и ваше имя) → сайт(ы) и типы документов → срок → «Подписать акт». Сервисному аккаунту «все сайты» не выдаются: каждый сайт называется в акте. - Проверьте:
GET /api/v1/client/credentialsпоказывает ключ сaccess: "grant"и областью действия акта.
2. Быстрый старт
export MUHRDOR_CLIENT_ID=sa_... export MUHRDOR_CLIENT_SECRET=... python examples/muhrdor_sign.py --site my.soliq.uz --credential <credential_id> hisobot.xml # -> hisobot.xml.p7b va "hisobot.xml: <audit_ref>"
С помощью curl:
TOKEN=$(curl -s https://muhrdor.uz/api/v1/token -H 'Content-Type: application/json' \
-d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$MUHRDOR_CLIENT_ID\",\"client_secret\":\"$MUHRDOR_CLIENT_SECRET\"}" \
| jq -r .access_token)
curl -s https://muhrdor.uz/api/v1/client/credentials -H "Authorization: Bearer $TOKEN"
curl -s https://muhrdor.uz/api/v1/signatures/sign -H "Authorization: Bearer $TOKEN" \
-H 'Idempotency-Key: hisobot-2026-09-0001' -H 'Content-Type: application/json' \
-d '{"credential_id":"…","site":"my.soliq.uz","documents":[{"content_b64":"…","external_ref":"hisobot-9"}]}'3. Шаги
- Токен —
POST /api/v1/token{grant_type: "client_credentials", client_id, client_secret}→access_token, 1 час. Refresh нет: при 401 получите новый. Не получайте новый токен на каждый запрос (лимит 30 в час). - Ключи —
GET /api/v1/client/credentials:credential_idи область действия акта. - Подписание —
POST /api/v1/signatures/sign:site— для какого сайта документ (должен быть в акте);documents[]— 1..200, всего 5 MiB;content_b64,detached(по умолчаниюtrue— в PKCS#7 нет контента;false— контент внутри),external_ref— ваш номер документа (≤64,A-Z a-z 0-9 . _ : / -), возвращается в ответе и сохраняется в журнале;Idempotency-Keyобязателен — для каждого нового запроса новый ключ (например, UUID). Ответ:results[i]—pkcs7_b64(DER PKCS#7, форма E-IMZO),audit_ref,doc_class,external_ref; у отклонённого документа —error.
- Результат позже —
GET /api/v1/signatures/{audit_ref}?credential_id=<kalit>: части подписи и хеш PKCS#7 (сам PKCS#7 на сервере не хранится —.p7bсохраняйте сами).
4. Повторная отправка — не подписать дважды
Сеть оборвалась, ответ не пришёл — отправьте повторно с тем же Idempotency-Key и тем же телом: в течение 10 минут сервер вернёт первый ответ, второй подписи не будет.
409 request_in_progress— первый ещё выполняется: через секунду с тем же ключом.422 idempotency_mismatch— этот ключ использован для другого тела: новый запрос — новый ключ.429 too_many_requests— подождитеRetry-Afterсекунд.502 signing_failed+retryable: true— один раз повторите с тем же ключом.403 policy_denied— не повторяйте: акта недостаточно (reason— причина).
5. Сайты и типы документов
Тип документа (doc_class) определяется по контенту. Проходят типы, названные актом в doc_kinds.
| Сайт | Типы |
|---|---|
my.soliq.uz | hisobot, login |
didox.uz | factura, qabul, hujjat, login |
xt-xarid.uz | hash32 |
my.it-park.uz | login |
Другой XML/JSON — структурный тип (xml:<ildiz element>, json:<xesh>): проходит, если владелец ключа явно указал его в акте. Нераспознанный контент — UNCLASSIFIED_CONTENT. Как узнать, какой тип нужен: detail в ответе об отказе и «Отклонённые запросы» в панели владельца ключа показывают тип — владелец добавляет его в акт. Новый сайт — нужен адаптер Muhrdor (напишите нам).
6. Лимиты
| Что | Лимит |
|---|---|
| Токен | 1 час; 30 в час (на каждый client_id) |
| Один запрос | 200 документов, всего 5 MiB |
| Скорость подписания | 600 документов в минуту (на каждый сервисный аккаунт; настройка сервера) |
| Окно идемпотентности | 10 минут |
| Активные сервисные аккаунты | 10 (на каждого человека) |
7. Конфиденциальность и журнал
Содержимое документов не хранится. В журнале: хеш контента и подписанных атрибутов, тип документа, сайт, page_url (без query), номер/период документа (из карты полей сайта, без сумм), ваш external_ref, ссылка на акт, client: "api". Не пишите в external_ref персональные данные (ПИНФЛ, имя) — это идентификатор.
8. Безопасность
- Секрет виден только при создании или при «Обновить секрет»; если он потерян — обновите (старый секрет и токены сразу перестают действовать).
- Если аккаунт не нужен — «Удалить» (необратимо). Владелец ключа отзывает акт в любое время — следующий запрос будет отклонён.
- Токен API не открывает endpoint'ы для людей: только токен,
client/*иsignatures/*.
Sign with a qualified electronic signature (ERI) on the Muhrdor server from your own system - a script, an ERP, an EDO - one document or a batch of up to 200. The key never leaves the HSM and is never given to you: your service account signs within a grant act the key owner signed, for the sites and document kinds the act names. Every signature is in the key owner's audit journal, marked "API".
- Machine-readable contract:
GET https://muhrdor.uz/api/v1/openapi.json(in the repository:docs/api/openapi-integrators.json) - Full reference (every endpoint and field, Uzbek): reference.md
- Error catalogue: errors.md
- A ready example (Python standard library only):
examples/muhrdor_sign.py - Wire format in detail (Uzbek):
docs/protocols/api-v1-service-account.md
1. Setup (once)
- Service account. In the Muhrdor panel (an ERI-attested account) → "API kalitlari" → a name → "Yaratish". You get a
client_id(sa_…) and aclient_secret- the secret is shown once, in that dialog. Keep it in your script's configuration (an environment variable), not in code. - Act. Send the
client_idto the key owner (for instance your client company's director). In the panel they choose "Huquqlar → Huquq berish → Xizmat akkaunti (client_id)" → "Topish" (they see your account's name and your name) → site(s) and document kinds → period → "Aktni imzolash". A service account never gets "all sites": each site is named in the act. - Check:
GET /api/v1/client/credentialslists the key withaccess: "grant"and the act's scope.
2. Quick start
export MUHRDOR_CLIENT_ID=sa_... export MUHRDOR_CLIENT_SECRET=... python examples/muhrdor_sign.py --site my.soliq.uz --credential <credential_id> report.xml # -> report.xml.p7b and "report.xml: <audit_ref>"
With curl:
TOKEN=$(curl -s https://muhrdor.uz/api/v1/token -H 'Content-Type: application/json' \
-d "{\"grant_type\":\"client_credentials\",\"client_id\":\"$MUHRDOR_CLIENT_ID\",\"client_secret\":\"$MUHRDOR_CLIENT_SECRET\"}" \
| jq -r .access_token)
curl -s https://muhrdor.uz/api/v1/client/credentials -H "Authorization: Bearer $TOKEN"
curl -s https://muhrdor.uz/api/v1/signatures/sign -H "Authorization: Bearer $TOKEN" \
-H 'Idempotency-Key: report-2026-09-0001' -H 'Content-Type: application/json' \
-d '{"credential_id":"…","site":"my.soliq.uz","documents":[{"content_b64":"…","external_ref":"report-9"}]}'3. Steps
- Token —
POST /api/v1/token{grant_type: "client_credentials", client_id, client_secret}→access_token, valid one hour. No refresh token: on 401 get a new one. Do not fetch a token per request (30 an hour per client). - Keys —
GET /api/v1/client/credentials:credential_idand the act's scope. - Sign —
POST /api/v1/signatures/sign:site— the site the documents are for (the act must name it);documents[]— 1..200, 5 MiB in all;content_b64,detached(defaulttrue- no content inside the PKCS#7;false- content embedded),external_ref— your own document id (≤64,A-Z a-z 0-9 . _ : / -), echoed back and kept in the journal;Idempotency-Keyis required — a new key for each new request (a UUID, say). Answer:results[i]—pkcs7_b64(DER PKCS#7, the E-IMZO shape),audit_ref,doc_class,external_ref; a refused document haserrorinstead.
- The result later —
GET /api/v1/signatures/{audit_ref}?credential_id=<key>: the signature parts and the PKCS#7 hash (the PKCS#7 itself is not stored on the server - keep your.p7b).
4. Retrying without signing twice
The connection dropped and no answer came: send again with the same Idempotency-Key and the same body. Within ten minutes the server returns the first answer; nothing is signed twice.
409 request_in_progress— the first one is still running: retry in a second with the same key.422 idempotency_mismatch— the key was used for another body: a new request needs a new key.429 too_many_requests— waitRetry-Afterseconds.502 signing_failedwithretryable: true— retry once with the same key.403 policy_denied— do not retry: the act does not cover it (reasonsays why).
5. Sites and document kinds
The document kind (doc_class) is recognised from the content. Kinds the act names in doc_kinds pass.
| Site | Kinds |
|---|---|
my.soliq.uz | hisobot (report), login |
didox.uz | factura (invoice), qabul (acceptance), hujjat (document), login |
xt-xarid.uz | hash32 |
my.it-park.uz | login |
Other XML/JSON is a structural kind (xml:<root element>, json:<digest>): it passes when the key owner names it in the act. Unrecognised content is UNCLASSIFIED_CONTENT. To learn which kind a document is: the refusal's detail and the key owner's panel ("Rad etilgan so'rovlar") show it, and the owner adds it to the act. A new site needs a Muhrdor adapter - write to us.
6. Limits
| What | Limit |
|---|---|
| Token | one hour; 30 an hour per client_id |
| One request | 200 documents, 5 MiB in all |
| Signing rate | 600 documents a minute per service account (a server setting) |
| Idempotency window | ten minutes |
| Active service accounts | ten per person |
7. Privacy and the journal
Document content is not stored. The journal keeps: hashes of the content and of the signed attributes, the document kind, the site, page_url (without the query), the document's number and period (from the site's field map, no amounts), your external_ref, the act reference and client: "api". Do not put personal data (a JSHSHIR, a name) in external_ref - it is an id.
8. Security
- The secret is visible only when the account is created or on "Secretni yangilash"; if it is lost, rotate it (the old secret and its tokens die at once).
- An account no longer needed: "O'chirish" (final). The key owner may revoke the act at any time - the next request is refused.
- An API token opens none of the person's endpoints: only the token,
client/*andsignatures/*.