HuqSi API Azərbaycan qanunvericiliyi üçün REST və MCP qapısı

HuqSi API

Sənədlər

REST və MCP qapısının istifadə qaydaları, nümunələr, limitlər və xəta kodları.

REST nümunələri

Baza ünvan: https://api.huqsi.az. Bütün cavablar JSON (UTF-8). Auth: X-API-Key başlığı. Tam sxem: /v1/openapi.json · interaktiv: /v1/swagger.

Dəyişiklik (2026-10-30, beta-dan əvvəl): POST /v1/search artıq maddənin tam mətnini qaytarmır. Hər nəticədə sorğuya ən uyğun parça (snippet, ən çox 600 simvol) olur. Köhnə text sahəsi qalır, amma onda da həmin parça olur (köhnəlmiş ad). Tam mətni GET /v1/articles/{id} verir. Səbəb: bəzi maddələr (tək-mətnli aktlar) on minlərlə simvoldur. Bu, /v1 kontraktında mövcud sahənin mənasının dəyişdiyi yeganə haldır; qalan bütün dəyişikliklər yeni sahələrdir.

Dəyişiklik (2026-11-01, beta-dan əvvəl): sahə adları aydınlaşdırıldı: versions → stored_versions, text_updated_at → first_seen_at, source_checked_at → data_updated_at. law.citation artıq qanunun istinad adıdır, qəbul nömrəsi law.number-dadır. Vaxtlar vahid formatdadır, boş sətir əvəzinə null qayıdır (aşağıda «Format»).

Format

  • Vaxt sahələri (*_at): UTC, millisaniyə dəqiqliyi, Z ilə — 2026-11-01T02:08:57.435Z.
  • Tarix sahələri (act_date, accept_date): YYYY-MM-DD.
  • Dəyəri olmayan sahə null olur, boş sətir ("") heç vaxt qayıtmır.

POST /v1/search — mətn axtarışı

curl -X POST https://api.huqsi.az/v1/search \
  -H "X-API-Key: hq_SİZİN_AÇARINIZ" \
  -H "Content-Type: application/json" \
  -d '{"query": "oğurluğa görə cəza", "limit": 3}'

Gövdə:

Sahə Tip Qeyd
query string, 2–500 Azərbaycan dilində sərbəst mətn
limit int, 1–20 defolt 5
law_ids int[] yalnız bu qanunlar (framework id-ləri), məs. [46944]
include_repealed bool qüvvədən düşmüş aktların maddələri də (defolt false)

Cavab:

{
  "query": "oğurluğa görə cəza",
  "count": 3,
  "results": [
    {
      "article_id": "46947:p1:177",
      "law_id": 46947,
      "law_title": "Azərbaycan Respublikasının Cinayət Məcəlləsi",
      "article_no": "177",
      "title": "Oğurluq",
      "citation": "Cinayət Məcəlləsi, maddə 177",
      "snippet": "177.1. Oğurluq, yəni özgənin əmlakını gizli talama — … cəzalandırılır.…",
      "snippet_truncated": true,
      "text_length": 4180,
      "text": "177.1. Oğurluq, yəni özgənin əmlakını gizli talama — … cəzalandırılır.…",
      "score": 0.8731,
      "source_url": "https://e-qanun.az/framework/46947"
    }
  ],
  "note": "Semantik axtarış: …",
  "data_updated_at": "2026-11-01T02:08:57.435Z",
  "notice": "Gələcəkdə qüvvəyə minəcək müddəalar hələlik ayrıca işarələnmir. …"
}

snippet sorğu sözləri ilə ən çox üst-üstə düşən cümlədən başlayır və cümlə sərhədində kəsilir. Başlanğıcda və ya sonda kəsilibsə … qoyulur. text_length tam mətnin uzunluğudur. text köhnəlmiş addır, snippet ilə eynidir. data_updated_at və notice üçün bax Təzəlik.

score — (1+cos)/2 şkalası; tipik dəyərlər 0.80–0.90. law_ids verildikdə axtarış daha geniş aparılıb nəticə yerində süzülür: bəzən limit-dən az nəticə qayıda bilər.

Python:

import httpx

r = httpx.post("https://api.huqsi.az/v1/search",
               headers={"X-API-Key": "hq_SİZİN_AÇARINIZ"},
               json={"query": "oğurluğa görə cəza", "limit": 3}, timeout=30)
r.raise_for_status()
for hit in r.json()["results"]:
    print(hit["citation"], "→", hit["article_id"])

GET /v1/articles/{id} — qüvvədə olan mətn

curl https://api.huqsi.az/v1/articles/46947:p1:177 -H "X-API-Key: hq_SİZİN_AÇARINIZ"

{
  "article_id": "46947:p1:177",
  "law": {"id": 46947, "title": "Azərbaycan Respublikasının Cinayət Məcəlləsi", "status": "Qüvvədədir",
          "in_force": true, "accept_date": "1999-12-30", "number": "787-IQ",
          "citation": "Azərbaycan Respublikasının Cinayət Məcəlləsi",
          "source_url": "https://e-qanun.az/framework/46947"},
  "article_no": "177",
  "title": "Oğurluq",
  "part_title": null,
  "section_path": null,
  "text": "177.1. …",
  "truncated": false,
  "text_length": 4180,
  "status": "aktiv",
  "in_force": true,
  "stored_versions": 3,
  "first_seen_at": "2026-10-07T12:16:46.000Z",
  "amendments_total": 2,
  "last_amendment": {"act_id": 61233, "act_title": "Cinayət Məcəlləsində dəyişiklik edilməsi haqqında",
                     "act_date": "2025-12-30", "act_no": "330-VIIQD",
                     "source_url": "https://e-qanun.az/framework/61233"},
  "recent_amendments": [{"act_id": 61233, "…": "…"}, {"act_id": 58611, "…": "…"}],
  "data_updated_at": "2026-11-01T02:08:57.435Z",
  "notice": "Gələcəkdə qüvvəyə minəcək müddəalar hələlik ayrıca işarələnmir. …"
}

in_force yalnız həm qanun qüvvədə olanda, həm maddə aktiv olanda true olur. Ləğv edilmiş maddədə status: "ləğv_edilib" olur, text null ola bilər.

  • stored_versions — bizim bazada bu maddənin neçə mətn versiyasının saxlandığı. Bu, hüquqi dəyişikliklərin sayı deyil: baza 2026-10-07-dən işləyir, ondan əvvəlki dəyişikliklər versiya kimi saxlanmayıb. Maddəni neçə aktın dəyişdirdiyini amendments_total göstərir (məs. amendments_total: 12, stored_versions: 1 normaldır).
  • first_seen_at — maddənin cari mətninin bazada ilk göründüyü vaxt (dəyişiklik aktının tarixi deyil).
  • data_updated_at — bazaya son məlumat paketinin (e-qanun.az-dan gündəlik yeniləmə) tətbiq olunduğu vaxt.
  • law.citation — qanunun istinad adı; maddəyə «law.citation, maddə article_no» kimi istinad edin. law.number — qəbul nömrəsi (məs. «787-IQ»), bilinmirsə null.
  • section_path (bölmə/fəsil yolu) hazırda həmişə null-dur: mənbədə iyerarxiya yoxlanılır, düzələndə qaytarılacaq.

Mətn 100 000 simvoldan uzundursa, cümlə sərhədində kəsilir: truncated: true, text_length tam uzunluğu göstərir, tam mətn law.source_url-dadır. last_amendment və recent_amendments (son ən çox 3) maddəni dəyişdirən aktlardır. Tam siyahını /history verir.

GET /v1/articles/{id}/history — dəyişiklik tarixçəsi

curl "https://api.huqsi.az/v1/articles/46947:p1:177/history?limit=10&offset=0" \
  -H "X-API-Key: hq_SİZİN_AÇARINIZ"

{
  "article_id": "46947:p1:177",
  "law_id": 46947,
  "law_title": "Azərbaycan Respublikasının Cinayət Məcəlləsi",
  "article_no": "177",
  "stored_versions": 3,
  "total": 2,
  "limit": 10,
  "offset": 0,
  "amendments": [
    {"act_id": 61233, "act_title": "Cinayət Məcəlləsində dəyişiklik edilməsi haqqında",
     "act_date": "2025-12-30", "act_no": "330-VIIQD", "act_status": "Qüvvədədir",
     "kinds": ["dəyişdirilib"], "source_url": "https://e-qanun.az/framework/61233"}
  ],
  "note": "…"
}

total maddəni dəyişdirən aktların sayıdır; stored_versions isə yalnız bizim bazada saxlanan mətn versiyalarının sayı (hüquqi dəyişiklik sayı deyil, bax yuxarıda).

kinds: dəyişdirilib · əlavə edilib · çıxarılıb · ləğv edilib · yeni redaksiya. Qeyddə açıq fel yoxdursa siyahı boş olur. Köhnə redaksiyanın mətni verilmir. Planlar üzrə açıq endpoint-lər: Limitlər.

Başlıqlar

Hər uğurlu cavabda (limitlər hesab üzrədir, bütün açarlarınız üçün ortaqdır):

X-Plan: developer              # hesabın planı
X-RateLimit-Limit: 20          # dəqiqəlik limit
X-RateLimit-Remaining: 18
X-RateLimit-Reset: 42          # saniyə
X-RateLimit-Monthly-Limit: 100
X-RateLimit-Monthly-Remaining: 93

Limit aşılanda 429 və Retry-After (saniyə) qayıdır. Xətaların tam siyahısı: Xəta kodları.