Hamkorlar uchun public API

Shartnomalarni o'z tizimingizdan tuzing

1C, ERP, sayt yoki mobil ilovadan turib Hesap'da shartnoma tuzing, holatini kuzating va PDF'ini oling. REST, JSON, bitta X-API-Key — boshqa hech narsa kerak emas.

Base URL

https://open.hesap.uz/v1

Autentifikatsiya

X-API-Key: hsp_…

Mashina spec

/api-docs (OpenAPI 3)

Shartnoma API orqali imzolanmaydi. Yaratilgan hujjat CREATED holatida taraflarni kutadi — imzo Hesap ilovasi yoki kabineti orqali qo'yiladi. Ikkala taraf imzolagach status ACTIVE bo'ladi va CONTRACT_ACTIVE webhook yuboriladi.

Tez boshlash

Uch qadamda birinchi shartnoma.

Kalit oling

Business kabinetida Integratsiyalar → Yangi kalit. Admin esa Control panelidan istalgan mijozga kalit bera oladi. Kalit matni faqat bir marta ko'rsatiladi — saqlab qo'ying.

Shablon id'sini toping

GET /templates kalit ishlay oladigan shablonlar ro'yxatini qaytaradi.

Shartnoma tuzing

POST /contracts — templateId va qarshi tomon buyerIn/sellerIn bilan.

shell

# 1 — shablonlarni olish
curl https://open.hesap.uz/v1/templates \
  -H "X-API-Key: hsp_live_9f3c…"

# 2 — shartnoma tuzish
curl -X POST https://open.hesap.uz/v1/contracts \
  -H "X-API-Key: hsp_live_9f3c…" \
  -H "Content-Type: application/json" \
  -d '{
        "templateId": "0f0c1f2e-8a41-4d02-9d55-2f7c1b6f9a30",
        "buyerIn": "51234567890123",
        "price": 1200000000,
        "currency": "UZS"
      }'

Kalit va huquqlar

Har bir so'rovda X-API-Key headeri. Kalit hsp_ bilan boshlanadi va faqat public API yo'llarida ishlaydi — kabinet endpointlariga o'tmaydi.

Huquqlar (scope)

Har bir kalitga yaratishda huquqlar biriktiriladi. Yetishmagan huquq — 403.

TEMPLATES_READ

Shablonlar ro'yxati va ularning maydonlari.

CONTRACTS_READ

Shartnomalarni o'qish: ro'yxat, bitta hujjat, PDF.

CONTRACTS_WRITE

Shartnoma tuzish.

CLIENTS_READ

Tarafni PINFL/STIR bo'yicha tekshirish.

Shablon doirasi va muddat

Kalit barcha shablonlar bilan (allTemplates: true) yoki faqat tanlangan shablonlar bilan ishlashi mumkin. Muddat (expiresAt) belgilanadi yoki null — abadiy. Joriy holatni GET /me qaytaradi.

Umumiy qoidalar

Mavzu	Qoida
Pul	Barcha pul qiymatlari tiyinda (so'm × 100). 12 000 000 so'm = `1200000000`. Amal qiladi: `price`, `initialPayment`, to'lov `amount`, mahsulot `price`/`amount`.
Sana	ISO-8601 UTC — `2026-09-01T00:00:00Z`.
Identifikator	Taraflar `in` bilan: jismoniy shaxsda 14 xonali PINFL, yuridikda 9 xonali STIR. Foydalanuvchi id'si emas — `in` barqaror.
Sahifalash	`page` (0 dan), `size` (default 20, maksimum 100). Javob: `content`, `totalElements`, `totalPages`, `number`, `size`.
Format	`application/json; charset=utf-8` (PDF endpointidan tashqari).

Umumiy

Kalit holati va taraf tekshiruvi.

GET /me huquq shart emas

Kalitning joriy holati — integratsiyani sozlashda birinchi chaqiriladigan endpoint. "Kalit ishlayaptimi, qaysi huquqlari bor?" degan savolga javob.

200 · javob

{
  "name": "1C integratsiyasi",
  "ownerIn": "301234567",
  "ownerLegalName": "OOO ALFA SAVDO",
  "scopes": ["TEMPLATES_READ", "CONTRACTS_READ", "CONTRACTS_WRITE"],
  "allTemplates": false,
  "templateIds": ["0f0c1f2e-8a41-4d02-9d55-2f7c1b6f9a30"],
  "expiresAt": null
}

expiresAt: null — kalit abadiy.

GET /clients/{in} CLIENTS_READ

Tarafni PINFL yoki STIR bo'yicha tekshirish — shartnoma tuzishdan oldin qarshi tomon Hesap'da bor-yo'qligini bilish uchun. Topilmasa 404.

200 · javob

{
  "in": "301234567",
  "firstName": null,
  "lastName": null,
  "midName": null,
  "legalName": "OOO ALFA SAVDO",
  "type": "COMPANY",
  "verified": true
}

verified — shaxs MyID (jismoniy) yoki E-IMZO (yuridik) orqali tasdiqlangan. Public API'da passport/telefon qaytmaydi.

Shablonlar

Kalitga ruxsat etilgan, nashr etilgan shartnoma shablonlari.

GET /templates TEMPLATES_READ

Kalit ishlay oladigan PUBLISHED shablonlar. JRXML manbasi tashqariga chiqarilmaydi.

200 · javob

[
  {
    "id": "0f0c1f2e-8a41-4d02-9d55-2f7c1b6f9a30",
    "nameUz": "Oldi-sotdi shartnomasi",
    "nameRu": "Договор купли-продажи",
    "nameEn": "Sale contract",
    "type": "B2C",
    "status": "PUBLISHED",
    "enabledCurrencies": ["UZS"],
    "productEnabled": true,
    "productRequired": false,
    "paymentScheduleEnabled": true,
    "witnessEnabled": false,
    "initialPaymentEnabled": true
  }
]

Maydon	Ma'no
`enabledCurrencies`	Ruxsat etilgan valyutalar; `null` — cheklov yo'q.
`productRequired`	`true` bo'lsa `products` majburiy.
`witnessCount`	Talab qilinadigan guvohlar soni.

GET /templates/{templateId}/fields TEMPLATES_READ

Shablonning to'ldiriladigan maydonlari — shartnomadagi values massivini shular bo'yicha yig'asiz.

200 · javob

[
  {
    "id": "7c1d0a55-3b21-4f88-9a0e-1d2b3c4d5e6f",
    "templateId": "0f0c1f2e-…",
    "parentKey": null,
    "nameUz": "Yetkazib berish manzili",
    "keyName": "delivery_address",
    "type": "STRING",
    "position": "BOTTOM",
    "productField": false
  }
]

productField: true — maydon mahsulotga tegishli, uni products[].values ichiga keyName kaliti bilan yozing. parentKey — bog'liq (ochiladigan) maydon kaliti.

Shartnomalar

Barcha amallar kalit egasi nomidan bajariladi.

POST /contracts CONTRACTS_WRITE

Yangi shartnoma tuzadi. Hujjat raqami (number) backendda generatsiya qilinadi, status har doim CREATED.

Maydon	Tur	Izoh
`templateId`	uuid	MAJBURIY — kalitga ruxsat etilgan shablon.
`buyerIn`	string	Xaridor PINFL/STIR. Bo'sh — kalit egasi.
`sellerIn`	string	Sotuvchi PINFL/STIR. Bo'sh — kalit egasi.
`price`	number	Shartnoma summasi, tiyinda.
`currency`	enum	`UZS` / `USD` / `RUB`.
`initialPayment`	number	Boshlang'ich to'lov, tiyinda.
`deliveryAt`	instant	Yetkazib berish sanasi.
`values`	array	Shablon maydonlari qiymatlari.
`payments`	array	To'lov jadvali: `{ amount, paymentDate }`.
`products`	array	Mahsulotlar (shablon `productEnabled` bo'lsa).
`witnessIds`	array	Guvohlar (foydalanuvchi id'lari).

Taraflardan biri kalit egasi bo'lishi shart. buyerIn yoki sellerIn bo'sh qoldirilsa u yerga kalit egasi qo'yiladi. Ikkalasi ham begona bo'lsa — 403: uchinchi shaxslar nomidan shartnoma tuzib bo'lmaydi.

so'rov tanasi

{
  "templateId": "0f0c1f2e-8a41-4d02-9d55-2f7c1b6f9a30",
  "buyerIn": "51234567890123",
  "price": 1200000000,
  "currency": "UZS",
  "initialPayment": 200000000,
  "deliveryAt": "2026-09-15T00:00:00Z",
  "values": [
    { "templateFieldId": "7c1d0a55-…", "keyName": "delivery_address",
      "value": "Toshkent sh., Amir Temur 108", "position": 1 }
  ],
  "payments": [
    { "amount": 500000000, "paymentDate": "2026-10-01T00:00:00Z" },
    { "amount": 500000000, "paymentDate": "2026-11-01T00:00:00Z" }
  ],
  "products": [
    { "name": "Sement M400", "unit": "KG", "price": 120000,
      "quantity": 10000, "amount": 1200000000 }
  ]
}

200 · javob

{ "id": "9b3f7c21-55ad-4e10-8b6e-0c4a91f2d773" }

GET /contracts CONTRACTS_READ

Kalit egasi ishtirok etgan shartnomalar — taraf sifatida ham, yaratuvchi sifatida ham. Shablon bo'yicha cheklangan kalit ruxsat etilmagan shablon hujjatlarini ko'rmaydi.

Parametr	Tur	Izoh
`statuses`	enum[]	`?statuses=CREATED&statuses=ACTIVE`
`templateId`	uuid	Shablon bo'yicha filtr.
`search`	string	Hujjat raqami yoki taraf bo'yicha qidiruv.
`page` / `size`	int	0 dan; default 20, maksimum 100.

Javob — sahifalangan Page: content[], totalElements, totalPages, number, size. Ro'yxatda values bo'sh keladi.

GET /contracts/{id} CONTRACTS_READ

Bitta shartnoma — taraflar, shablon, maydon qiymatlari va mahsulotlari bilan.

200 · javob

{
  "id": "9b3f7c21-55ad-4e10-8b6e-0c4a91f2d773",
  "number": "260815-0042",
  "status": "ACTIVE",
  "purpose": "CONTRACT",
  "buyerStatus": "ACCEPTED",
  "sellerStatus": "ACCEPTED",
  "buyerIn": "51234567890123",
  "sellerIn": "301234567",
  "creatorIn": "301234567",
  "price": 1200000000,
  "currency": "UZS",
  "templateId": "0f0c1f2e-…",
  "buyer": { "firstName": "Anvar", "lastName": "Qodirov", "type": "CLIENT" },
  "values": [{ "keyName": "delivery_address", "value": "Toshkent sh." }],
  "createdDate": "2026-08-15T09:12:44Z"
}

Kim imzolaganini buyerStatus/sellerStatus dan aniqlang, status dan emas. creatorIn — shartnomani kim tuzgan; bekor qilish huquqi shu tarafda.

GET /contracts/{id}/pdf CONTRACTS_READ

Shartnomaning PDF baytlari — application/pdf. ?lang=uz|ru|en (default uz).

shell

curl https://open.hesap.uz/v1/contracts/9b3f7c21-…/pdf?lang=ru \
  -H "X-API-Key: hsp_live_9f3c…" \
  -o shartnoma.pdf

Webhook

Kalitga webhookUrl biriktirilsa, shartnoma hodisalari o'sha manzilga POST qilinadi.

Hodisa	Qachon
`CONTRACT_CREATED`	Shartnoma tuzildi (hali imzolanmagan).
`CONTRACT_SIGNED`	Taraflardan biri imzoladi.
`CONTRACT_ACTIVE`	Ikkala taraf imzoladi — hujjat kuchga kirdi.
`CONTRACT_REJECTED`	Qarshi taraf rad etdi.
`CONTRACT_CANCELLED`	Yaratuvchi bekor qildi.
`PAYMENT_ACCEPTED`	To'lov so'rovi tasdiqlandi.

So'rov tanasi va headerlar

POST · sizning webhookUrl

// Headerlar:
//   X-Hesap-Event      hodisa turi
//   X-Hesap-Delivery   yetkazish id'si — takroriy ishlov bermaslik uchun saqlang
//   X-Hesap-Signature  sha256=<hex> — tananing HMAC-SHA256 imzosi
{
  "event": "CONTRACT_ACTIVE",
  "contractId": "9b3f7c21-55ad-4e10-8b6e-0c4a91f2d773",
  "contractNumber": "260815-0042",
  "status": "ACTIVE",
  "buyerIn": "51234567890123",
  "sellerIn": "301234567",
  "creatorIn": "301234567",
  "actorIn": "51234567890123",
  "amount": 1200000000,
  "currency": "UZS",
  "occurredAt": "2026-08-15T11:04:02Z"
}

Xulq-atvor: timeout 10 s, 3 marta qayta urinish (2 s dan eksponensial), har qanday 2xx muvaffaqiyat. Uch urinishdan keyin hodisa yo'qoladi — kritik oqimda faqat webhook'ga tayanmang, GET /contracts bilan solishtirib turing.

Imzoni tekshirish

Imzo xom tana (raw body) ustidan hisoblanadi — JSON'ni parse qilishdan oldin tekshiring. Secret kalit yaratilganda bir marta beriladi.

Node.js

const crypto = require("crypto");

function verify(rawBody, signature, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  const a = Buffer.from(expected), b = Buffer.from(signature || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

PHP

function verify($rawBody, $signature, $secret) {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature ?? '');
}

Xatolar

Barcha xatolar yagona JSON shaklida qaytadi.

Kod	Sabab	Nima qilish kerak
`400`	So'rov maydonlari noto'g'ri (masalan `templateId` yo'q, ikkala taraf bo'sh).	Javobdagi `message`ni o'qing.
`401`	Kalit yuborilmagan, noto'g'ri, bekor qilingan yoki muddati tugagan.	Kabinetda kalitni tekshiring / rotate qiling.
`403`	Scope yetishmaydi; shablon ruxsat etilmagan; hujjat kalit egasiga tegishli emas.	`GET /me` bilan huquq va shablon doirasini solishtiring.
`404`	Shartnoma yoki taraf topilmadi.	Identifikatorni tekshiring.
`503`	Ichki servis vaqtincha javob bermadi.	Bir necha soniyadan keyin qayta urining.

xato javobi shakli

{
  "code": 403,
  "status": "403 Forbidden",
  "path": "/openapi/v1/contracts",
  "message": "Bu shablon kalitga ruxsat etilmagan",
  "description": "Bu shablon kalitga ruxsat etilmagan",
  "timestamp": "15 avgust 2026 y., 16:04:02 UTC+5"
}

Enum qiymatlar

So'rov va javoblarda uchraydigan barcha sanoqli qiymatlar.

Shartnoma holati · `status`

CREATEDACTIVECOMPLETED REJECTEDCANCELLED

SIGNED_BY_BUYER / SIGNED_BY_SELLER — eski qiymatlar, yangi hujjatlarda uchramaydi.

Taraf holati · `buyerStatus`, `sellerStatus`

PENDINGACCEPTEDREJECTEDCANCELLED

Maydon turi · `TemplateFieldType`

STRINGINTEGERDOUBLEDATE LISTSELECTMULTISELECTCHECKBOXRADIO DOUBLE_INPUT_STRINGDOUBLE_INPUT_INTEGERDOUBLE_INPUT_DOUBLEDOUBLE_INPUT_DATE

Maydon	Qiymatlar
`currency`	`UZS`, `USD`, `RUB`
`unit` (mahsulot)	`DONA`, `KG`, `LITR`
`purpose`	`CONTRACT`, `TTN`, `AKT`, `FACTURA`
`type` (taraf)	`CLIENT` — jismoniy, `COMPANY` — yuridik
`exchangeMode`	`GOODS` — tovar ro'yxati, `MONEY` — pul/qarz

Shartnomalarni o'z tizimingizdan tuzing

Tez boshlash

Kalit oling

Shablon id'sini toping

Shartnoma tuzing

Kalit va huquqlar

Huquqlar (scope)

Shablon doirasi va muddat

Umumiy qoidalar

Umumiy

Shablonlar

Shartnomalar

Webhook

So'rov tanasi va headerlar

Imzoni tekshirish

Xatolar

Enum qiymatlar

Shartnoma holati · status

Taraf holati · buyerStatus, sellerStatus

Maydon turi · TemplateFieldType

Shartnoma holati · `status`

Taraf holati · `buyerStatus`, `sellerStatus`

Maydon turi · `TemplateFieldType`