API معاهدو

سنڌ آءِ ٽي پورٽل — سهولت ڊيسڪ (SITP) جي مستند REST API معاهدي جي دستاويز: بيس URL، ورزننگ، تصديق ۽ اجازت، ريٽ لمٽنگ، صفحہ بندي، لفافو، خاميون، idempotency، OpenAPI 3.1 خاڪو، مڪمل وسائل جي فهرست، ٻاهر نڪرندڙ ويب هوڪ جو معاهدو، SDK/codegen منصوبو، deprecation، سينڊ باكس، ۽ مشاهدگي۔

1. دائرو ۽ هن دستاويز کي پڙهڻ جو طريقو

هي دستاويز SITP جي عوامي REST API جو انجنيئرنگ معاهدو آهي. انهي کي هيٺيان استعمال ڪن ٿا:

• پارٽنر ڊولپرز — ٻيا حڪومتي پورٽلز، انضمام جا پارٽنرز، ۽ وڏيون ڪمپني ٽيننٽس جيڪي پروگرامي سطح تي ٽِڪيٽ درج ڪن ٿا ۽ انهن جي پيروي ڪن ٿا.
• اندروني فرنٽ اينڊ/موبائل ٽيمون — Next.js پورٽل ۽ مستقبل جو React Native اپ ساڳيو API ڪال ڪن ٿا.
• QA ۽ ٽيسٽ انجنيئرز — §7 (خاميون) ۽ §10 (وسائل جي فهرست) جي خلاف معاهدي ٽيسٽ مرتب ڪرڻ لاءِ.
• سيڪيورٽي جائزو — §3 (تصديق ۽ اجازت)، §4 (ريٽ لمٽس)، ۽ §16 (مشاهدگي) /specs/sd/11-security-compliance/ ڏانهن حوالو ڏين ٿا.

هي دستاويز API جي شڪل لاءِ مستند ماخذ آهي. اها /specs/sd/08-integrations-spec/ جي §8 (عوامي API) کي هڪ مڪمل معاهدي ۾ وڌائي ٿي. انضمام جي تفصيلي دستاويز انفرادي انضمام ايڊاپٽرز (NADRA، SECP، Mailjet وغيره) لاءِ مستند ماخذ رهي ٿي؛ هي دستاويز رڳو ان سطح جو احاطو ڪري ٿي جيڪا SITP پاڻ ظاهر ڪري ٿي. جتي ٻئي ڪنهن عوامي-API تفصيل تي متفق نه هجن، هي دستاويز غالب آهي.

هر وسيلي پٺيان ڊيٽا ماڊل /specs/sd/05-data-model/ ۾ مقرر ٿيل آهي؛ API فيلڊ جا نالا اتي دستاويز ٿيل snake_case ڪالمن جا camelCase عڪس آهن.

2. بيس URL، ورزننگ ۽ ميڊيا قسمون

2.1 بيس URL

هن دستاويز جا سڀ رستا مڪمل طرح لکڻ کان سواءِ بيس URL جي نسبت سان آهن.

2.2 ورزننگ جي حڪمت عملي

SITP URL سيگمنٽ ميجر ورزننگ (/api/v1، /api/v2) استعمال ڪري ٿو. قاعدا:

• پيچ/مائنر تبديليون (اضافي، غير ڀڃندڙ) موجوده ميجر ورزن ۾ جاري ٿين ٿيون. مثالون: هڪ نئون اختياري فيلڊ، نئون endپوائنٽ، هڪ نئين enum قدر جنهن کي ڪلائنٽ نظر انداز ڪري سگهي، نئون query پيٽاميٽر.
• ڀڃندڙ تبديليون نئين ميجر ورزن جو مطالبو ڪن ٿيون. مثالون: فيلڊ هٽائڻ، فيلڊ جي قسم بدلائڻ، ڊفالٽ رويو بدلائڻ، enum کي تنگ ڪرڻ، اسٽيٽس ڪوڊ بدلائڻ.
• جڏهن نئون ميجر ورزن جاري ٿئي ته پويون ورزن گهٽ ۾ گهٽ 12 مهينا متوازي طور معاون رهي ٿو (ڏسو §14 Deprecation). ٻئي ورزن هڪ ئي ڊپلائمنٽ تي هلن ٿا؛ روٽنگ URL سيگمنٽ ذريعي ٿئي ٿي.
• ڪا به Accept-هيڊر ورزننگ ناهي — URL سيگمنٽ واحد ورزن چونڊيندڙ آهي. ان سان ڪلائنٽ ڪوڊ، پراکسيون، ۽ ڊي بگنگ آسان رهي ٿي.
• هر جواب هڪ X-SITP-API-Version: v1 هيڊر رکي ٿو ته جيئن ڪلائنٽس ۽ لاگز تصديق ڪري سگهن ته ڪهڙي ورزن درخواست پيش ڪئي.

اهو ته ڀڃندڙ ڪهڙو آهي §14.2 ۾ دستاويز ٿيل آهي ۽ /api/v1/openapi.json تي پيش ڪيل چينج لاگ ۾ ظاهر آهي (OpenAPI جو info.version هڪ ميجر اندر SemVer تي قائم آهي).

2.3 ميڊيا قسمون

2.4 عام هيڊرز (هر درخواست)

3. تصديق ۽ اجازت

SITP ٻن تصديقي انداز ظاهر ڪري ٿو، ٻئي پنهنجي ميزبان Keycloak مثال تي ختم ٿين ٿا (/specs/sd/08-integrations-spec/ §7 مطابق):

1. OAuth 2.0 client-credentials — پارٽنر ائپس لاءِ (مشين کان مشين تائين). ڪو آخري صارف عمل ۾ ناهي.
2. OIDC bearer (Authorization Code + PKCE) — انٽرايڪٽو صارفين لاءِ (ڪمپني نمائندا، حڪومتي عملو) جيڪي SITP UI يا ڪنهن فيڊرل حڪومتي IdP ذريعي لاگ اِن ٿين ٿا.

ٻئي مختصر مدت جا bearer رسائي ٽوکنز (JWTs) پيدا ڪن ٿا جيڪي Authorization: Bearer <token> هيڊر ۾ موڪليا وڃن ٿا. ٽوڪنز ڪڏهن به query پيٽاميٽرز جي طور تي موڪليا ناهن وڃدا.

3.1 OAuth 2.0 client-credentials (پارٽنر ائپس)

پارٽنر ائپس SITP پارٽنر ڪنسول ۾ رجسٽرڊ ٿين ٿيون ۽ هڪ client_id ۽ client_secret وصول ڪن ٿيون. هر پارٽنر هڪ يا وڌيڪ companyId قدرن سان ٻڌل آهي جنهن لاءِ هو مجاز آهي (ڪمپني پارٽنر کي پورٽل ۾ OAuth انداز جي رضامندگيءَ سان اجازت ڏئي ٿي). فلو:

ٽوڪن درخواست

POST /api/v1/partners/tokens
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "partner_acmeintegrator",
  "client_secret": "••••••••••••••••",
  "scope": "tickets:write tickets:read kb:read"
}

ٽوڪن جواب

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "tickets:write tickets:read kb:read",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

• ٽوڪن TTL: 1 ڪلاڪ (3600 s). پارٽنرز کي ختم ٿيڻ کان اڳ refresh ڪرڻ گهرجن؛ SITP ڪنهن ٽوڪن کي ڊگهو ناهي ڪندو، بلڪه نئون جاري ڪندو آهي.
• client_secret رجسٽريشن تي هڪ ڀيرو ڏيکاريو ويندو آهي؛ ان جي rotation هڪ دستاويز ٿيل رن بڪ آهي (ڏسو /specs/sd/11-security-compliance/).
• ٽوکنز اسڪوپ محدود آهن (§3.3). غير ڏنل اسڪوپ جي درخواست SITP-AUTH-003 خامي موٽائي ٿي (§7.3).

ٽوڪن منسوخي

POST /api/v1/partners/tokens/revoke
Authorization: Bearer <partner admin token>
Content-Type: application/json

{ "token": "eyJhbGciOi...", "token_type_hint": "access_token" }

اها 204 No Content موٽائي ٿي. هڪ denylist کي Redis ۾ عكس بند ڪيو ويندو آهي ته جيئن منسوخي چند سيڪنڊن اندر اثر انداز ٿئي.

3.2 OIDC bearer (انٽرايڪٽو صارفين)

ڪمپني نمائندا ۽ حڪومتي عملو SITP UI ذريعي تصديق ڪن ٿا، جيڪو Keycloak جي خلاف PKCE سان گڏ OIDC Authorization Code فلو سرانجام ڏئي ٿو. نتيجي جو رسائي ٽوڪن هڪ bearer طور API کي بالڪل پارٽنر ٽوڪن وانگر موڪليو ويندو آهي. Claims ۾ sub، email، realm (gov-staff | company)، roles[]، deptCode، ۽ 2fa_verified شامل آهن (/specs/sd/08-integrations-spec/ §7 مطابق). حڪومتي عملي جا ٽوڪنز اضافي طور هڪ SITP ڪردار (Staff، POC، DG، Secretary، SuperAdmin) رکن ٿا جيڪو RolesGuard/PermissionsGuard استعمال ڪندو آهي.

SITP جي پنهنجي فرنٽ اينڊ لاءِ، هي شفاف آهي — SPA ٽوکن کي محفوظ سيسن ۾ رکي ٿو. ٽين پارٽي UI لاءِ جيڪي ساڳئي Keycloak realm سان فيڊرل ٿين ٿيون، ساڳيو طريقو عمل ۾ اچي ٿو.

3.3 اسڪوپس

اسڪوپس پارٽنر ائپس لاءِ اجازت جي اڪائي آهن. انٽرايڪٽو صارفين کي ڪردار + صلاحيت ذريعي اجازت ڏني ويندي آهي (/specs/sd/04-roles-permissions/ مطابق)، اسڪوپ ذريعي ناهي؛ تنهن هوندي به انهن جي ٽوڪن کي endپوائنٽ جي گهربل صلاحيت پوري ڪرڻ گهرجي.

هڪ endپوائنٽ جو گهربل اسڪوپ وسائل جي فهرست (§10) ۽ OpenAPI جي security بلاڪ (§9) ۾ درج آهي. اسڪوپ جي کوٽ → SITP-AUTH-004 (§7.3).

3.4 عوامي (no-auth) endپوائنٽس

هڪ ننڍڙو سيٽ صرف پڙهڻ جا endپوائنٽس عوامي آهن — ڪابه ٽوڪن گهربل ناهي — ته جيئن شهري ۽ محقق رجسٽريشن کان سواءِ انهن کي استعمال ڪري سگهن:

• GET /departments، GET /departments/{deptId}
• GET /service-catalog، GET /service-catalog/{serviceId}
• GET /kb/articles، GET /kb/articles/{articleId} (شائع ٿيل ذيلي سيٽ)
• GET /stats/public، GET /stats/public/summary

عوامي endپوائنٽس پوءِ به ريٽ لمٽنگ (§4) جا تابع آهن هڪ سخت تر ڊفالٽ درجي تي.

4. ريٽ لمٽنگ

ريٽ لمٽس پليٽ فارم کي غلط استعمال ڪندڙ يا ڀڄي ويندڙ ڪلائنٽس کان محفوظ رکن ٿا. لمٽس في پارٽنر (client_id/ٽوڪن سان سڃاڻپ ٿيل) تصديق ٿيل ڪالز لاءِ ۽ في ماخذ IP عوامي ڪالز لاءِ آهن. لمٽس int_ratelimit جدول ۾ تشڪيل جوڳا آهن (/specs/sd/05-data-model/ §3.10 مطابق) ۽ پارٽنر درجي ۽ آپريشن ڪلاس جي لحاظ کان مختلف آهن.

4.1 درجو بندي ماڊل

لکڻ جون لمٽس هر آپريشن ڪلاس لاءِ الگ آهن (ٽِڪيٽ بنائڻ، پيغام شامل ڪرڻ، اپ لوڊ) ته جيئن پڙهڻ جو اچار لکڻ جي گنجائش ختم ناهي ڪري سگهندو. اچارڻ وارن ڪلائنٽس کي throttle ڪيو ويندو آهي (HTTP 429)، اڳ ۾ اطلاع کان سواءِ خاموشيءَ سان ڪڏهن به banned ناهي ڪيو ويندو.

4.2 ريٽ لمٽ هيڊرز

هر جواب — ڪامياب جواب سميت — هي هيڊرز رکي ٿو ته جيئن ڪلائنٽس پاڻ کي منظم ڪري سگهن:

جڏهن تجاوز ڪري وڃي:

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 28
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1752752522

{
  "type": "https://sindhitportal.maahir.io/docs/errors/rate-limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "You have exceeded 600 requests per minute. Retry after the Retry-After window.",
  "instance": "/api/v1/tickets",
  "code": "SITP-RATELIMIT-001",
  "retryAfterSeconds": 28
}

Retry-After هميشه 429 تي موجود هوندو آهي ۽ سيڪنڊن ۾ ڏنو ويندو آهي.

5. صفحہ بندي، فلٽرنگ، ترتيب ڏيڻ ۽ Sparse Fieldsets

5.1 صفحہ بندي (cursor + page)

SITP فهرست endپوائنٽس لاءِ ٻن صفحہ بندي انداز معاون آهن. Cursor اعليٰ حجم، ترتيب ڏنل فهرستن لاءِ ترجيحی آهي؛ page سهولت ۽ ايڊمن UIs لاءِ معاون آهي.

Cursor ٽوڪنز ڪلائنٽ لاءِ opaque آهن (هڪ base64url-encoded signed اسٽرنگ)؛ ڪلائنٽس کي انهن کي black box سمجهڻ گهرجن ۽ رڳو واپس موڪلڻ گهرجن. جواب هميشه links بلاڪ (§6) ذريعي ڪلائنٽ کي جاري رکڻ جو طريقو ٻڌائي ٿو.

5.2 فلٽرنگ

فلٽرز في endپوائنٽ whitelist-ٿيل تصديق ٿيل query پيٽاميٽرز آهن. نامعلوم فلٽرز SITP-VALIDATION-005 سان مسترد ڪيا ويندا آهن. عام فلٽرز:

5.3 ترتيب ڏيڻ

?sort=<field> چڙهندڙ؛ ?sort=-<field> لهندڙ (شروعاتي -). multi-sort: ?sort=-createdAt,priority. ترتيب ڏيڻ جوڳا فيلڊز في endپوائنٽ OpenAPI ۾ درج آهن؛ غير ترتيب ڏيڻ جوڳي فيلڊ مان ترتيب ڏيڻ تي SITP-VALIDATION-006 موٽي ٿو.

5.4 Sparse fieldsets

ڪلائنٽس رڳو اهي فيلڊز گهر ڪري سگهن ٿا جيڪي کين گهربل آهن ته جيئن payload سائز گهٽ رهي، جيڪو موبائل ۽ ميٽرڊ نيٽ ورڪن لاءِ ڪارآمد آهي:

GET /api/v1/tickets/SITP-2026-SRB-000128?fields=ticketId,status,sla
Authorization: Bearer <token>

رڳو data اندر گهرايل اعليٰ سطحي فيلڊز موٽائي ٿو. نامعلوم يا غير مجاز فيلڊز خاموشيءَ سان ڇڏي ويندا آهن (خامي ناهي) ته جيئن ڪلائنٽس forward-compatible رهن. Nested sparse selection dot-paths استعمال ڪري ٿو: ?fields=ticketId,sla.responseBy.

6. جواب جو لفافو

هر ڪامياب جواب ساڳيو لفافو استعمال ڪري ٿو: { data, meta, links }. واحد وسيلي جوابون وسيلي کي data ۾ رکن ٿيون ۽ خالي هجڻ تي meta/links کي ڇڏي ڏين ٿيون؛ فهرست جوابون ٽيئي ڀرين ٿيون.

لفافو مثال (cursor صفحہ بندي سان فهرست)

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01HZX9F8K7P4N2Q3R6STV8WXAB
X-SITP-API-Version: v1

{
  "data": [
    { "ticketId": "SITP-2026-SRB-000127", "status": "assigned" },
    { "ticketId": "SITP-2026-SRB-000128", "status": "new" }
  ],
  "meta": {
    "requestId": "req_01HZX9F8K7P4N2Q3R6STV8WXAB",
    "locale": "en",
    "serverTime": "2026-07-17T09:18:42.117Z",
    "page": { "limit": 50, "returned": 2, "hasMore": true }
  },
  "links": {
    "self":  "/api/v1/tickets?cursor=eyJpZCI6MTI3fQ&limit=50",
    "next":  "/api/v1/tickets?cursor=eyJpZCI6MTIyOH0&limit=50",
    "prev":  null,
    "first": "/api/v1/tickets?limit=50"
  }
}

لفافو مثال (واحد وسيلو)

{
  "data": {
    "ticketId": "SITP-2026-SRB-000128",
    "status": "new"
  },
  "meta": { "requestId": "req_01HZX9F8K7P4N2Q3R6STV8WXAB" }
}

خاميون انهي لفافي جو استعمال ناهن ڪنديون — هو RFC 7807 (§7) استعمال ڪن ٿيون.

7. خاميون (RFC 7807 Problem Details)

سڀ خاميون RFC 7807 (application/problem+json) استعمال ڪن ٿيون. هر خامي معياري فيلڊز کان علاوه هڪ SITP مخصوص code (مستحکم، مشين جي پڙهڻ جوڳو) رکي ٿي. ڪلائنٽس کي code تي branch ڪرڻ گهرجي، ڪڏهن detail تي ناهي (جيڪو انسان جي پڙهڻ جوڳو ۽ localized آهي).

7.1 معياري فيلڊز

7.2 Validation خامي جو مثال

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json
X-Request-Id: req_01HZX9F8K7P4N2Q3R6STV8WXAC

{
  "type": "https://sindhitportal.maahir.io/docs/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "companyId does not match the partner's authorized scope.",
  "instance": "/api/v1/tickets",
  "code": "SITP-VALIDATION-042",
  "requestId": "req_01HZX9F8K7P4N2Q3R6STV8WXAC",
  "errors": [
    { "field": "companyId", "code": "SCOPE_MISMATCH" },
    { "field": "attachments[0].size", "code": "MAX_SIZE_EXCEEDED" }
  ]
}

7.3 خامي ڪوڊ جي فهرست

اسٽيٽس ڪوڊز HTTP تي قائم آهن. SITP خامي ڪوڊز خاندان جي لحاظ کان گروهه بند آهن. هي فهرست https://sindhitportal.maahir.io/docs/errors تي live پيش ڪئي ويندي آهي ۽ OpenAPI دستاويز ۾ versioned آهي.

4xx خاميون (429 کان سواءِ) ڪلائنٽس پاران ڪڏهن به ٻيهر ڪوشش ناهن ٿينديون. 5xx ۽ 429 کي exponential backoff سان ٻيهر ڪوشش ڪري سگهجي ٿو (ڏسو §8 ۽ /specs/sd/08-integrations-spec/ §11.2).

8. Idempotency

هر تحرير (POST، PUT، PATCH، DELETE جيڪا state بدلائي) Idempotency-Key هيڊر قبول ڪندي آهي. هيڊر ڪلائنٽ جو پيدا ڪيل UUID v4 يا v7 آهي. 24 ڪلاڪن جي idempotency ونڊو اندر (/specs/sd/08-integrations-spec/ §11 ۾ NFR-INT-004 مطابق):

• ڪنهن ڏنل ڪنجي جي پهرين درخواست عمل ۾ آندي ويندي آهي ۽ ان جو مڪمل جواب (status، body، headers) cache ٿيندو آهي.
• ساڳئي ڪنجي جي ٻيهر درخواست cached جواب موٽائي ٿي، چاهه اصل validation جي لحاظ کان ناڪام ٿي هجي — ان لاءِ ڪلائنٽس کي payload بدلائڻ تي نئون ڪنجي تيار ڪرڻ گهرجي.
• ساڳئي ڪنجي مگر مختلف payload باڊي سان ٻيهر درخواست SITP-CONFLICT-002 (409) موٽائي ٿي، جيڪا هڪ مختلف intent لاءِ ڪنجي جي حادثاتي استعمال کان بچائي ٿي.
• GET درخواستون هيڊر کي نظر انداز ڪن ٿيون.

تحرير تي Idempotency-Key جي کوٽ SITP-VALIDATION-001 موٽائي ٿي جنهن ۾ هيڊر ڏانهن اشارو هوندو آهي. هي هيڊر audit_logs.request_id correlation ۾ به ظاهر ٿيندو آهي (/specs/sd/05-data-model/ §3.10 مطابق) ته جيئن هڪ تحرير ۽ ان جي نتيجي ۾ ٿيندڙ انضمام ڪالز هڪ thread ۾ شريڪ ٿين.

POST /api/v1/tickets
Authorization: Bearer <token>
Idempotency-Key: 9a2c4e6b-1f3d-4a2c-9e8b-7d6c5b4a3f2e
Content-Type: application/json

{ "companyId": "cmp_01HZX7K4P9N2Q3R6STV8WXYPJ", "title": "..." }

24 ڪلاڪن اندر مماثل درخواست ٻيهر هلائڻ اصل 201 Created ساڳئي ticketId سان موٽائي ٿو، نه ته duplicate ٽِڪيٽ.

9. OpenAPI 3.1 خاڪو

مڪمل OpenAPI 3.1 دستاويز NestJS ڪنٽرولرز مان @nestjs/swagger ذريعي پيدا ٿيندي آهي ۽ /api/v1/openapi.json تي پيش ڪئي ويندي آهي، پوءِ /docs/api تي render ٿيندي آهي. هيٺ ڏنل خاڪو اعليٰ سطحي دستاويزي شڪل ۽ ٽي نمائندگي ڪندڙ آپريشنز (POST /partners/tokens، POST /tickets، GET /tickets/{ticketId}) ڏيکاري ٿو. اهو مثالي آهي، مڪمل ناهي.

openapi: 3.1.0
info:
  title: Sindh IT Portal — Facilitation Desk Public API
  version: 1.4.0
  description: >
    REST API for partner apps and interactive clients of the Sindh IT Portal.
    Base URL: https://sindhitportal.maahir.io/api/v1
  contact:
    name: SITP API Support
    email: api-support@sindhitportal.maahir.io
  license:
    name: Proprietary — Government of Sindh
servers:
  - url: https://sindhitportal.maahir.io/api/v1
    description: Production
  - url: https://sandbox.sindhitportal.maahir.io/api/v1
    description: Sandbox
tags:
  - name: Auth
  - name: Tickets
  - name: TicketMessages
  - name: Attachments
  - name: Organizations
  - name: Representatives
  - name: Departments
  - name: ServiceCatalog
  - name: KnowledgeBase
  - name: PublicStats
  - name: Webhooks
security:
  - bearerAuth: []
  - oauth2: [tickets:read]
paths:
  /partners/tokens:
    post:
      tags: [Auth]
      summary: Exchange client credentials for a bearer token (OAuth2 client-credentials)
      operationId: createPartnerToken
      security: []            # public endpoint
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TokenRequest' }
      responses:
        '200':
          description: Token issued
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TokenResponse' }
        '400': { $ref: '#/components/responses/Problem' }
        '401': { $ref: '#/components/responses/Problem' }
  /tickets:
    post:
      tags: [Tickets]
      summary: Create a ticket on behalf of a company
      operationId: createTicket
      security:
        - bearerAuth: []
        - oauth2: [tickets:write]
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/AcceptLanguage'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TicketCreateRequest' }
      responses:
        '201':
          description: Ticket created
          headers:
            Location: { schema: { type: string } }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TicketEnvelope' }
        '400': { $ref: '#/components/responses/Problem' }
        '401': { $ref: '#/components/responses/Problem' }
        '403': { $ref: '#/components/responses/Problem' }
        '422': { $ref: '#/components/responses/Problem' }
        '429': { $ref: '#/components/responses/Problem' }
    get:
      tags: [Tickets]
      summary: List tickets for the authorized company (cursor pagination)
      operationId: listTickets
      security:
        - bearerAuth: []
        - oauth2: [tickets:read]
      parameters:
        - in: query
          name: cursor
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
        - in: query
          name: status
          schema: { type: array, items: { type: string } }
        - in: query
          name: dept
          schema: { type: string }
        - in: query
          name: since
          schema: { type: string, format: date-time }
      responses:
        '200':
          description: A page of tickets
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TicketListEnvelope' }
        '401': { $ref: '#/components/responses/Problem' }
        '429': { $ref: '#/components/responses/Problem' }
  /tickets/{ticketId}:
    get:
      tags: [Tickets]
      summary: Get a single ticket by tracking id
      operationId: getTicket
      security:
        - bearerAuth: []
        - oauth2: [tickets:read]
      parameters:
        - in: path
          name: ticketId
          required: true
          schema: { type: string, example: SITP-2026-SRB-000128 }
        - in: query
          name: fields
          description: Sparse fieldset
          schema: { type: string, example: ticketId,status,sla }
      responses:
        '200':
          description: The ticket
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TicketEnvelope' }
        '404': { $ref: '#/components/responses/Problem' }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: /api/v1/partners/tokens
          scopes:
            tickets:read:  Read tickets, messages, attachments
            tickets:write: Create and mutate tickets
            orgs:read:     Read organization records
            orgs:write:    Register and manage organizations
            reps:write:    Manage representatives
            kb:read:       Read published KB articles
            stats:read:    Read non-public analytics slices
            files:read:    Download attachments
            files:write:   Upload and attach files
            webhooks:manage: Manage webhook subscriptions
  parameters:
    IdempotencyKey:
      in: header
      name: Idempotency-Key
      required: true
      schema: { type: string, format: uuid }
    AcceptLanguage:
      in: header
      name: Accept-Language
      required: false
      schema: { type: string, enum: [en, ur, sd], default: en }
  responses:
    Problem:
      description: An RFC 7807 problem document
      content:
        application/problem+json:
          schema: { $ref: '#/components/schemas/Problem' }
  schemas:
    Problem:
      type: object
      required: [type, title, status, code]
      properties:
        type:     { type: string, format: uri }
        title:    { type: string }
        status:   { type: integer }
        detail:   { type: string }
        instance: { type: string }
        code:     { type: string, example: SITP-VALIDATION-042 }
        requestId:{ type: string }
        errors:
          type: array
          items:
            type: object
            properties:
              field: { type: string }
              code:  { type: string }

مڪمل دستاويز §10 جي هر آپريشن لاءِ هيئن pattern ورجائي ٿي، بشمول request-body schemas، response envelopes، هر دستاويزي status لاءِ problem-details، ۽ §12 جي واقعن لاءِ webhooks: ايڪسٽينشن (OpenAPI 3.1 native webhooks جي معاونت رکي ٿو).

10. وسائل جي فهرست

هيٺ ڏنل فهرست v1 جو هر endپوائنٽ درج ڪري ٿي. فيلڊ نالا مستحکم آهن؛ مڪمل schemas /api/v1/openapi.json ۾ آهن. هر قطار رکي ٿي: HTTP ميٿڊ، رستو، مقصد، گهربل auth اسڪوپ (يا public)، ۽ آيا تحرير idempotent آهي (Idempotency-Key قبول ڪري ٿي).

ضابطا: GET/HEAD ڪڏهن به idempotent-keyed ناهن. {ticketId} صارف جي سامهون جو ٽريڪنگ آءِ ڊي SITP-YYYY-DEPT-NNNNNN آهي. سڀ {orgId}/{repId} opaque SITP ids آهن.

10.1 Auth

10.2 Tickets

10.3 TicketMessages

10.4 Attachments

تجويز ڪيل پارٽنر فلو MinIO تائين presigned-URL اپ لوڊ آهي (پارٽنر bytes براهِ راست آبجيڪٽ اسٽوريج ڏانهن PUT ڪري ٿو؛ SITP bytes ڪڏهن proxy ناهي ڪندو). PUT مڪمل ٿيڻ کان پوءِ، پارٽنر uploadId کي POST /tickets ۾ refer ڪري ٿو (/specs/sd/08-integrations-spec/ جو §11.3 ڏسو). هر اپ لوڊ قابلِ اتصال ٿيڻ کان اڳ ClamAV ذريعي AV-scan ٿيندو آهي (متاثر هجي ته SITP-UPLOAD-003 — /specs/sd/05-data-model/ §4.4 media_library.av_status مطابق).

10.5 Organizations

10.6 Representatives

10.7 Departments

10.8 ServiceCatalog

10.9 KnowledgeBase

10.10 PublicStats

عوامي-stats payloads /specs/sd/17-analytics-kpis/ ۾ تجزياتي ماڊل مان اخذ ٿيل گمنام ٿيل مجموعات آهن. ڪو به انفرادي ٽِڪيٽ يا ڪمپني سڃاڻپ جوڳو ناهي.

10.11 Webhooks

ڪل v1 endپوائنٽس: 30.

11. نموني درخواست/جواب Flows

ٽي end-to-end flows جيڪي لفافو، idempotency، خاميون، ۽ صفحہ بندي کي استعمال ڪن ٿا. فيلڊ نالا /specs/sd/05-data-model/ جو عڪس آهن (API لاءِ camelCased).

11.1 ٽِڪيٽ بنائڻ (پارٽنر، ڪنهن ڪمپني جي پاران)

هڪ پارٽنر اپ مجاز ڪمپني جي پاران ٽِڪيٽ درج ڪري ٿي، اڳ ۾ ئي اپ لوڊ ٿيل فائل منسلڪ ڪندي. ڪال idempotent آهي؛ ساڳيو Idempotency-Key 24 ڪلاڪن اندر ورجائڻ مماثل 201 جواب موٽائي ٿو (ڪابه duplicate ٽِڪيٽ ناهي).

درخواست

POST /api/v1/tickets
Host: sindhitportal.maahir.io
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIs...
Idempotency-Key: 9a2c4e6b-1f3d-4a2c-9e8b-7d6c5b4a3f2e
X-Request-Id: req_01HZX9F8K7P4N2Q3R6STV8WXAB
Accept-Language: en
Content-Type: application/json

{
  "companyId": "cmp_01HZX7K4P9N2Q3R6STV8WXYPJ",
  "title": "Pending sales tax refund for Q4 2025",
  "description": "Our company filed the Q4 2025 SRB refund on 15 Jan 2026; no acknowledgment received.",
  "category": "SRB-REFUND",
  "targetDept": "SRB",
  "priority": "normal",
  "language": "en",
  "attachments": [
    {
      "filename": "SRB-Q4-2025-filing.pdf",
      "mimeType": "application/pdf",
      "size": 482310,
      "uploadId": "fil_upl_01HZX9F8K7P4N2Q3R6STV8WXY"
    }
  ],
  "requestedBy": { "repId": "rep_01HZX7K4P9N2Q3R6STV8WXYPJ" }
}

جواب

HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/v1/tickets/SITP-2026-SRB-000128
X-Request-Id: req_01HZX9F8K7P4N2Q3R6STV8WXAB
X-SITP-API-Version: v1
X-RateLimit-Tier: standard
X-RateLimit-Remaining: 599

{
  "data": {
    "ticketId": "SITP-2026-SRB-000128",
    "status": "new",
    "state": "triage-pending",
    "category": "SRB-REFUND",
    "targetDept": "SRB",
    "priority": "normal",
    "sla": {
      "responseBy": "2026-07-19T09:00:00Z",
      "resolveBy": "2026-07-27T09:00:00Z",
      "paused": false
    },
    "createdAt": "2026-07-17T09:18:42.117Z",
    "portalUrl": "https://sindhitportal.maahir.io/tickets/SITP-2026-SRB-000128",
    "attachments": [
      {
        "filename": "SRB-Q4-2025-filing.pdf",
        "attachmentId": "fil_att_01HZX9F8K7P4N2Q3R6STV8WXZ",
        "size": 482310,
        "isEvidence": false
      }
    ]
  },
  "meta": {
    "requestId": "req_01HZX9F8K7P4N2Q3R6STV8WXAB",
    "locale": "en",
    "serverTime": "2026-07-17T09:18:42.117Z"
  }
}

ساڳئي Idempotency-Key ۽ مماثل باڊي سان duplicate POST ساڳيو 201 (ساڳئي ticketId سان) موٽائي ٿو، 409/duplicate جي بدران؛ ساڳئي ڪنجي سان مختلف باڊي 409 SITP-CONFLICT-002 موٽائي ٿي (§8).

11.2 ٽِڪيٽ حيثيت حاصل ڪرڻ (پڙهڻ، sparse fieldset)

هڪ پارٽنر هڪ ٽِڪيٽ poll ڪري ٿو ۽ رڳو حيثيت + SLA فيلڊز گهرُي ٿو ته جيئن ميٽرڊ موبائل لنڪ تي payload گهٽ ۾ گهٽ رهي. اهو sparse-fieldset query (§5.4) استعمال ڪري ٿو.

درخواست

GET /api/v1/tickets/SITP-2026-SRB-000128?fields=ticketId,status,sla,assignedTo
Host: sindhitportal.maahir.io
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIs...
Accept-Language: en
X-Request-Id: req_01HZX9F8K7P4N2Q3R6STV8WXAE

جواب

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01HZX9F8K7P4N2Q3R6STV8WXAE
X-SITP-API-Version: v1
X-RateLimit-Remaining: 587

{
  "data": {
    "ticketId": "SITP-2026-SRB-000128",
    "status": "assigned",
    "assignedTo": { "dept": "SRB", "section": "Refunds" },
    "sla": {
      "responseBy": "2026-07-19T09:00:00Z",
      "resolveBy": "2026-07-27T09:00:00Z",
      "paused": false,
      "firstResponseAt": null
    }
  },
  "meta": {
    "requestId": "req_01HZX9F8K7P4N2Q3R6STV8WXAE",
    "locale": "en",
    "serverTime": "2026-07-17T10:02:13.004Z",
    "requestedFields": ["ticketId", "status", "sla", "assignedTo"]
  }
}

جن فيلڊز جي درخواست ناهي ٿي (title، description، attachments، createdAt، …) انهن کي ڇڏي ويندو آهي. جيڪڏهن ٽِڪيٽ موجود ناهي يا ڪالر جي visibility ناهي ته جواب 404 SITP-NOTFOUND-001 (§7.3) آهي — ٻنهي لاءِ هڪ ئي شڪل، ته جيئن موجودگي leak ناهي ٿيندي.

11.3 عوامي stats جي فهرست (گمنام، ڪابه auth ناهي)

هڪ شهري يا محقق گمنام ٿيل عوامي-شفافيت مجموعات آڻي ٿو. ڪابه ٽوڪن گهربل ناهي؛ public ريٽ لمٽ درجي (§4.1) جو تابع.

درخواست

GET /api/v1/stats/public?since=2026-07-01T00:00:00Z&until=2026-07-31T23:59:59Z&limit=20
Host: sindhitportal.maahir.io
Accept-Language: en
X-Request-Id: req_01HZX9F8K7P4N2Q3R6STV8WXAF

جواب

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01HZX9F8K7P4N2Q3R6STV8WXAF
X-SITP-API-Version: v1
X-RateLimit-Tier: public
X-RateLimit-Remaining: 118

{
  "data": {
    "window": { "since": "2026-07-01T00:00:00Z", "until": "2026-07-31T23:59:59Z" },
    "totals": {
      "ticketsReceived": 4821,
      "ticketsResolved": 3104,
      "ticketsClosed": 2877,
      "avgResolutionHours": 53.2,
      "medianResolutionHours": 38.0,
      "csatAverage": 4.2,
      "withinSlaPercent": 87.4
    },
    "byDepartment": [
      { "dept": "SRB",  "received": 1210, "resolved": 902, "withinSlaPercent": 91.1 },
      { "dept": "SITD", "received": 988,  "resolved": 741, "withinSlaPercent": 89.0 },
      { "dept": "LBR",  "received": 612,  "resolved": 388, "withinSlaPercent": 81.3 },
      { "dept": "FIN",  "received": 457,  "resolved": 290, "withinSlaPercent": 84.6 }
    ],
    "byStatus": {
      "new": 612, "triaged": 233, "assigned": 410,
      "in_progress": 374, "resolved": 227, "closed": 2877, "reopened": 88
    },
    "generatedAt": "2026-07-17T10:05:00.000Z"
  },
  "meta": {
    "requestId": "req_01HZX9F8K7P4N2Q3R6STV8WXAF",
    "locale": "en",
    "serverTime": "2026-07-17T10:05:11.882Z",
    "anonymized": true,
    "page": { "limit": 20, "returned": 4, "hasMore": false }
  },
  "links": {
    "self": "/api/v1/stats/public?since=2026-07-01T00:00:00Z&until=2026-07-31T23:59:59Z&limit=20"
  }
}

byDepartment ۽ byStatus تفصيلون nightly pre-aggregate ٿين ٿيون (/specs/sd/17-analytics-kpis/ مطابق) ۽ cache ٿين ٿيون؛ meta.anonymized: true flag عوامي-stats جوابن تي هميشه موجود هوندو آهي. ڪنهن به عوامي-stats payload ۾ ڪو به انفرادي ٽِڪيٽ، ڪمپني، يا نمائندو سڃاڻپ جوڳو ناهي.

12. ويب هوڪ معاهدو

ويب هوڪس پارٽنر ائپس کي polling کان سواءِ real time ۾ SITP واقعن تي ردعمل ظاهر ڪرڻ جي سهولت ڏين ٿا. هي سيڪشن پارٽنر جو سامهون وارو معاهدو آهي؛ وصول ڪندڙ طرف جا ميڪنزم (دستخط verify، replay protect، enqueue) /specs/sd/08-integrations-spec/ §9 ۾ بيان ٿيل آهن.

12.1 واقعا

12.2 ترسيل جو معاهدو

• Transport: پارٽنر جي رجسٽرڊ endپوائنٽ تائين HTTPS POST، JSON باڊي، Content-Type: application/json.
• Signing: هر payload سبسڪرپشن جي shared secret سان HMAC-SHA256 دستخط ٿيل آهي. دستخط <ts>.<raw-body> اسٽرنگ تي X-SITP-Signature هيڊر ۾ t=<unix-ts>,v1=<hex-signature> جي طور تي موڪليو ويندو آهي. پارٽنرز HMAC ٻيهر compute ڪري verify ڪن ٿا.
• Replay تحفظ: timestamp t چيڪ ڪئي ويندي آهي؛ 5 منٽ پراڻيون درخواستون پارٽنر پاران مسترد ڪجن ٿيون. هر ترسيل eventId ۽ deliveryId رکي ٿي؛ SITP ٻئي کي webhook ترسيل لاگ ۾ رڪارڊ ڪري ٿو (/specs/sd/05-data-model/ §3.10 ۽ /specs/sd/08-integrations-spec/ §9.1 مطابق).
• Retry: non-2xx جوابن کي exponential backoff سان ٻيهر ڪوشش ڪئي ويندي آهي — 10s, 30s, 2m, 10m, 1h, 6h, 24h (7 ڪوششون). ختم ٿيڻ کان پوءِ ترسيل failed mark ٿي ويندي آهي ۽ پارٽنر ڊيش بورڊ ۾ POST /webhooks/subscriptions/{subId}/replay ذريعي دستي ٻيهر هلائڻ لاءِ پيش ڪئي ويندي آهي.
• Ordering: ساڳئي ticketId جا واقعا في-endپوائنٽ قطار ذريعي ترتيب ۾ موڪليا ويندا آهن. cross-ٽِڪيٽ ترتيب جي ضمانت ناهي.
• Idempotency: پارٽنرز کي eventId تي duplicate هٽائڻ لازم آهي؛ SITP ٻيهر موڪلي سگهي ٿو.
• Versioning: data بلاڪ هڪ version فيلڊ رکي ٿو؛ هڪ وڏي شڪل جي تبديلي نئين version جي طور تي parallel ترسيل سان جاري ٿيندي آهي جيستائين پارٽنرز migrate ناهن ڪندا.

12.3 HMAC-signed payload نمونو

POST https://partner.example.org/sitp/webhook
Content-Type: application/json
X-SITP-Event: ticket.status_changed
X-SITP-Signature: t=1752752322,v1=5b1c3729d4f8a2e6b0c1d9e7f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2
X-SITP-Delivery: dlv_01HZX9F8K7P4N2Q3R6STV8WXZ
X-Request-Id: req_01HZX9F8K7P4N2Q3R6STV8WXAD

{
  "eventId": "evt_01HZX9F8K7P4N2Q3R6STV8WXAB",
  "eventType": "ticket.status_changed",
  "occurredAt": "2026-07-17T09:38:42.000Z",
  "version": "1",
  "data": {
    "ticketId": "SITP-2026-SRB-000128",
    "companyId": "cmp_01HZX7K4P9N2Q3R6STV8WXYPJ",
    "previousStatus": "new",
    "status": "assigned",
    "assignedTo": { "dept": "SRB", "section": "Refunds" },
    "sla": { "responseBy": "2026-07-19T09:00:00Z" },
    "portalUrl": "https://sindhitportal.maahir.io/tickets/SITP-2026-SRB-000128"
  },
  "delivery": { "deliveryId": "dlv_01HZX9F8K7P4N2Q3R6STV8WXZ", "attempt": 1 }
}

Verify ڪرڻ جو pseudocode (پارٽنر طرف):

t, v1 = parse(X-SITP-Signature)            # "1752752322", "5b1c..."
if abs(now() - t) > 300: reject            # replay window
expected = HMAC_SHA256(secret, t + "." + raw_request_body)
if not constant_time_eq(expected, v1): reject
event = JSON.parse(raw_request_body)
if seen(event.eventId): ignore              # idempotency
handle(event)

دستخط SITP پاران HMAC_SHA256(secret, "<t>.<rawRequestBody>") جي طور تي compute ٿيندو آهي ۽ v1 جي طور تي hex-encode ٿيندو آهي.

13. SDK ۽ Codegen منصوبو

SITP جي OpenAPI 3.1 دستاويز ڪلائنٽ SDK پيدا ڪرڻ جو واحد input آهي. منصوبو:

ضابطا:

• پيدا ٿيل، ڪڏهن هٿ سان ناهي لکيل. SDKs هر معاهدي جي تبديلي تي openapi.json مان ٻيهر پيدا ٿين ٿا؛ دستي ترميمون منع ٿيل آهن.
• مستحڪم ميٿڊ نالا. OpenAPI دستاويز ۾ operationId کي هڪ عوامي symbol سمجهيو ويندو آهي ۽ رڳو ميجر ورزن پار بدلائي ويندو آهي.
• Versioning. SDK پيڪيجز آزاد طور تي versioned ٿين ٿا ۽ هڪ ميجر API ورزن کي pin ڪن ٿا (sitp-sdk-ts@^1 ↔ API v1).
• Bundled ماڊلز. Request/response قسمون bundled آهن ته جيئن پارٽنرن کي compile-time تحفظ ملئي.
• Retry ۽ idempotency built in. سرڪاري SDKs تحريرن لاءِ خود Idempotency-Key تيار ڪن ٿا ۽ 5xx/429 تي idempotently exponential backoff (capped) سان ٻيهر ڪوشش ڪن ٿا — پارٽنرز هي پاڻ لاڳو ناهن ڪندا.

14. Deprecation پاليسي

14.1 Lifecycle

هر API عنصر (endپوائنٽ، فيلڊ، پيٽاميٽر، enum قدر، واقعو) انهن مرحلن مان گذري ٿو:

experimental → current → deprecated → sunset → removed

• experimental: هڪ feature flag پٺيان، اطلاع کان سواءِ بدلجي سگهي ٿو؛ OpenAPI ۾ x-sitp-experimental: true طور دستاويز ٿيل آهي. پارٽنرز کي انهن تي انحصار ناهي ڪرڻ گهرجن.
• current: مستحکم، versioning ضمانت هيٺ.
• deprecated: اڃا تائين functional؛ هڪ هٽائڻ جي تاريخ جو اعلان ڪري ٿو. هر متاثر ٿيل جواب تي Deprecation ۽ Sunset HTTP response هيڊرز (RFC 8594 / RFC 9745) شامل ڪري ٿو، ۽ OpenAPI دستاويز ان کي deprecated: true mark ڪري ٿي.
• sunset: معياري Sunset هيڊر هٽائڻ جي تاريخ سان موٽائي ٿو؛ ڪالون ڪامياب ٿين ٿيون مگر telemetry لاءِ log ٿين ٿيون.
• removed: ڪنهن endپوائنٽ تي SITP-NOTFOUND-001 (404) موٽائي ٿو، يا فيلڊ جوابن مان غائب ٿي ويندي آهي.

14.2 ڇا ڀڃندڙ آهي (نئون ميجر لازمي)

• ڪنهن endپوائنٽ، فيلڊ، پيٽاميٽر، يا enum قدر کي هٽائڻ يا نالو بدلائڻ.
• ڪنهن فيلڊ جي قسم، nullability، يا semantics بدلائڻ.
• ڊفالٽ رويو بدلائڻ جنهن تي ڪلائنٽ انحصار ڪن ٿا.
• اسٽيٽس ڪوڊ يا خامي code بدلائڻ.
• Paginated limit maximum کي تنگ ڪرڻ.

14.3 ڇا غير ڀڃندڙ آهي (in-version جاري)

• نئون endپوائنٽ، فيلڊ، پيٽاميٽر، يا enum قدر شامل ڪرڻ (ڪلائنٽس کي unknowns نظر انداز ڪرڻ گهرجن).
• نئون اختياري request فيلڊ شامل ڪرڻ.
• validation ڍلو ڪرڻ (مثال طور، max length وڌائڻ).
• JSON آبجيڪٽ ۾ فيلڊز جي ترتيب بدلائڻ (ڪلائنٽس key order تي انحصار ناهن ڪرڻ گهرجن).

14.4 Timelines

• هڪ deprecated عنصر deprecated جي اعلان کان گهٽ ۾ گهٽ 12 مهينا معاون رهي ٿو ان کان اڳ جو ان کي هٽائي سگهجي (۽ رڳو نئين ميجر ورزن ۾).
• پويون ميجر ورزن اڳيون ميجر جاري ٿيڻ کان پوءِ گهٽ ۾ گهٽ 12 مهينا parallel run لاءِ معاون آهي.
• Deprecation جا اعلانات رجسٽرڊ پارٽنرز کي اي ميل ڪيا ويندا آهن، /docs/api/changelog تي شائع ٿيندا آهن، ۽ پارٽنر ڊيش بورڊ ۾ ظاهر ٿيندا آهن.

15. سينڊ باڪس ۽ ٽيسٽ ماحول

هڪ مخصوص سينڊ باڪس ماحول پارٽنرز کي پروڊڪشن ڊيٽا کي ڇهه کان سواءِ بنائڻ ۽ ٽيسٽ ڪرڻ جي سهولت ڏئي ٿو.

15.1 ٽيسٽ ڊيٽا

• Synthetic تنظيمون معلوم companyIds (cmp_test_*) جيڪي سينڊ باڪس آن بورڊنگ پيڪ ۾ دستاويز ٿيل آهن.
• Synthetic CNICs/NTNs جيڪي قابلِ پيش بياني mock نتيجا موٽائين ٿا (مثال طور، active، not-found، cancelled) ته جيئن پارٽنرز هر تصديقي branch کي استعمال ڪري سگهن.
• هڪ reset endپوائنٽ (POST /sandbox/reset) repeatable ٽيسٽن لاءِ seed ڊيٽا سيٽ بحال ڪري ٿو. پروڊڪشن ۾ اهڙو ڪو به endپوائنٽ ناهي.

15.2 معاهدي ٽيسٽنگ

• هر release OpenAPI دستاويز کي live سينڊ باڪس خلاف prism استعمال ڪندي هلائي ٿي ته جيئن verify ٿئي ته implementation معاهدي سان مطابقت رکي ٿي.
• هن دستاويز ۾ پارٽنر جي سامهون واريون مثالون هڪ CI job ذريعي validate ٿين ٿيون جيڪا کين هر تبديلي تي سينڊ باڪس خلاف ٻيهر هلائي ٿي.

16. مشاهدگي — correlation IDs

هر درخواست — ڪامياب يا ناڪام — هڪ correlation آءِ ڊي ذريعي end-to-end قابلِ سراغ آهي.

رويو:

• جيڪڏهن ڪلائنٽ X-Request-Id موڪلي ته SITP ان کي validate ڪري ٿو (UUID يا req_<ulid> شڪل) ۽ ٻيهر استعمال ڪري ٿو؛ بصورت دیگر SITP هڪ تيار ڪري ٿو (req_<ulid>).
• آءِ ڊي ظاهر ٿئي ٿو: HTTP response هيڊر ۾، لفافي جي meta.requestId فيلڊ ۾، خابين تي RFC 7807 جي requestId فيلڊ ۾، هر structured log لائن ۾، هر OTel span ۾، audit_logs.request_id ڪالم ۾، ۽ درخواست سان ٽرگر ٿيندڙ انضمام ڪالز لاءِ هر int_call قطار ۾.
• پارٽنرز پاران support ٽِڪيٽ ۾ آءِ ڊي quote ڪرڻ سان SITP کي Grafana/Loki ۾ مڪمل درخواست trace چند سيڪنڊن ۾ ملندو آهي.
• PII آءِ ڊي يا log tags ۾ ڪڏهن به رکيل ناهي؛ رڳو opaque سڃاڻپ ڪندڙ ۽ outcome ڪوڊز log ٿيندا آهن (/specs/sd/11-security-compliance/ مطابق).

17. درخواست Lifecycle (end-to-end)

ڊاياگرام هڪ واحد تصديق ٿيل تحرير — POST /tickets — جو مڪمل lifecycle ڏيکاري ٿو، پارٽنر جي HTTP ڪال کان هر cross-cutting تشوش ذريعي آخري جواب تائين.

تحريري وضاحت. هڪ پارٽنر POST /tickets هڪ Authorization bearer، هڪ Idempotency-Key، ۽ (اختياري طور تي) هڪ X-Request-Id سان جاري ڪري ٿو. nginx گیٽ وي ڪال forward ڪري ٿو، ۽ ڪابه traceparent موجود ناهي ته W3C traceparent تيار ڪري ٿو. NestJS اندر، cross-cutting middleware chain هڪ مقرر ترتيب ۾ هلندو آهي: CORS → rate limit → authentication → authorization (scope/role) → idempotency lookup → request validation → audit/OTel span open. ڪابه به ناڪامي اصل X-Request-Id رکندڙ RFC 7807 problem دستاويز سان short-circuit ٿي ويندي آهي. جيڪڏهن idempotency ڪنجي 24 ڪلاڪن اندر ڏٺي وئي هجي ۽ payload مطابقت رکي، ته اصل جواب verbatim ٻيهر هلائي ويندو آهي ۽ ڪابه ڊومين ڪم ناهي هلندو. cache miss تي، ڪنٽرولر validated DTO کي TicketsService حواله ڪري ٿو، جيڪو هڪ MariaDB ٽرانزيڪشن کولي ٿو، SITP-YYYY-DEPT-NNNNNN ٽريڪنگ آءِ ڊي پيدا ڪري ٿو، ٽِڪيٽ insert ڪري ٿو، هڪ ticket_history قطار ۽ هڪ audit_logs قطار لکي ٿو، ۽ side-effects (SLA ڪلاڪ start، notifications، اختياري e-Office فائل push، registry تصديقي jobs) کي BullMQ ۾ enqueue ڪري ٿو — هي ٽرانزيڪشن commit ٿيڻ کان پوءِ هلن ٿا ته جيئن جواب ڪڏهن به بيروني latency کان block ناهي ٿيندو. ٽرانزيڪشن commit ٿئي ٿو، ڪنٽرولر نئون ٽِڪيٽ {data, meta, links} لفافي ۾ ويڙهي ٿو، middleware ريٽ لمٽ ۽ version هيڊرز attach ڪري ٿو، ۽ گیٽ وي نئين وسيلي ڏانهن اشارو ڪندڙ Location هيڊر سان 201 Created موٽائي ٿو. ان دوران، BullMQ workers fan out ٿين ٿا: notifications communications ايڊاپٽرز ذريعي موڪليا ويندا آهن، ticket.created ويب هوڪ HMAC-signed ۽ deliver (۽ §12.2 مطابق retry) ٿيندو آهي، ۽ SLA ڪلاڪ محڪمي جي ڪاروباري ڪلاڪن اندر هلڻ شروع ڪندو آهي. هر قدم — گیٽ وي، middleware، ڊومين، انضمام، قطار — هڪ OTel span emit ڪري ٿو جيڪو ساڳئي X-Request-Id سان tag ٿيل آهي، ان لاءِ پارٽنر جي آءِ ڊي report ڪرڻ سان ops کي Grafana/Loki ۾ پورو trace reconstruct ملندو آهي.

18. کليل سوالات / TBD

دستاويز جو خاتمو.