API Contract

The authoritative REST API contract for the Sindh IT Portal — Facilitation Desk (SITP): base URL, versioning, authentication, rate limiting, pagination, envelope, errors, idempotency, an OpenAPI 3.1 skeleton, the full resource catalog, the outbound webhook contract, SDK/codegen plan, deprecation, sandbox, and observability.

1. Scope & How to Read This Document

This document is the engineering contract for SITP's public REST API. It is consumed by:

• Partner developers — other government portals, integration partners, and large company tenants that file and track tickets programmatically.
• Internal frontend/mobile teams — the Next.js portal and the future React Native app call the same API.
• QA & test engineers — to author contract tests against §7 (errors) and §10 (resource catalog).
• Security review — §3 (auth), §4 (rate limits), and §16 (observability) cross-reference /specs/en/11-security-compliance/.

This document is the source of truth for the shape of the API. It expands §8 of /specs/en/08-integrations-spec/ (the Public API) into a full contract. The integrations spec remains the source of truth for individual integration adapters (NADRA, SECP, Mailjet, etc.); this document covers only the surface SITP itself exposes. Where the two disagree on a public-API detail, this document wins.

The data model behind every resource is defined in /specs/en/05-data-model/; the API field names are camelCase projections of the snake_case columns documented there.

2. Base URL, Versioning & Media Types

2.1 Base URL

All paths in this document are relative to the base URL unless written in full.

2.2 Versioning strategy

SITP uses URL-segment major versioning (/api/v1, /api/v2). The rules:

• Patch/minor changes (additive, non-breaking) ship inside the current major version. Examples: a new optional field, a new endpoint, a new enum value that clients can ignore, a new query parameter.
• Breaking changes require a new major version. Examples: removing a field, changing a field's type, changing default behavior, narrowing an enum, changing a status code.
• When a new major version ships, the previous version is supported in parallel for at least 12 months (see §14 Deprecation). Both versions run on the same deployment; routing is by URL segment.
• No Accept-header versioning — the URL segment is the only version selector. This keeps client code, proxies, and debugging simple.
• Every response carries an X-SITP-API-Version: v1 header so clients and logs can confirm which version served the request.

What counts as breaking is documented in §14.2 and reflected in the changelog served at /api/v1/openapi.json (OpenAPI info.version follows SemVer within a major).

2.3 Media types

2.4 Common headers (every request)

3. Authentication & Authorization

SITP exposes two authentication modes, both terminating at the self-hosted Keycloak instance (per /specs/en/08-integrations-spec/ §7):

1. OAuth 2.0 client-credentials — for partner apps (machine-to-machine). No end-user in the loop.
2. OIDC bearer (Authorization Code + PKCE) — for interactive users (company reps, government staff) who log in through the SITP UI or a federated government IdP.

Both yield short-lived bearer access tokens (JWTs) sent in the Authorization: Bearer <token> header. Tokens are never passed as query parameters.

3.1 OAuth 2.0 client-credentials (partner apps)

Partner apps are registered in the SITP partner console and receive a client_id and client_secret. Each partner is bound to one or more companyId values it is authorized to act for (the company grants the partner via OAuth-style consent in the portal). The flow:

Token request

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"
}

Token response

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"
}

• Token TTL: 1 hour (3600 s). Partners must refresh before expiry; SITP never extends a token, it issues a new one.
• client_secret is shown once at registration; rotation is a documented runbook (see /specs/en/11-security-compliance/).
• Tokens are scope-limited (§3.3). Requesting an ungranted scope returns a SITP-AUTH-003 error (§7.3).

Token revocation

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

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

Returns 204 No Content. A denylist is mirrored to Redis so revocation takes effect within seconds.

3.2 OIDC bearer (interactive users)

Company representatives and government staff authenticate through the SITP UI, which performs the OIDC Authorization Code flow with PKCE against Keycloak. The resulting access token is sent as a bearer to the API exactly like a partner token. Claims include sub, email, realm (gov-staff | company), roles[], deptCode, and 2fa_verified (per /specs/en/08-integrations-spec/ §7). Government staff tokens additionally carry a SITP role (Staff, POC, DG, Secretary, SuperAdmin) consumed by the RolesGuard/PermissionsGuard.

For SITP's own frontend, this is transparent — the SPA holds the token in a secure session. For third-party UIs that federate to the same Keycloak realm, the same mechanism applies.

3.3 Scopes

Scopes are the unit of authorization for partner apps. Interactive users are authorized by role + capability (per /specs/en/04-roles-permissions/), not by scope; their token still must satisfy the endpoint's required capability.

An endpoint's required scope is listed in the resource catalog (§10) and in the OpenAPI security block (§9). Missing scope → SITP-AUTH-004 (§7.3).

3.4 Public (no-auth) endpoints

A small set of read-only endpoints are public — no token required — so that citizens and researchers can consume them without registration:

• GET /departments, GET /departments/{deptId}
• GET /service-catalog, GET /service-catalog/{serviceId}
• GET /kb/articles, GET /kb/articles/{articleId} (published subset)
• GET /stats/public, GET /stats/public/summary

Public endpoints are still subject to rate limiting (§4) at a stricter default tier.

4. Rate Limiting

Rate limits protect the platform from abusive or runaway clients. Limits are per partner (identified by client_id/token) for authenticated calls and per source IP for public calls. Limits are configurable in the int_ratelimit table (per /specs/en/05-data-model/ §3.10) and differ by partner tier and operation class.

4.1 Tier model

Write limits are separate per operation class (ticket-create, message-append, upload) so a burst of reads cannot exhaust write capacity. Bursty clients are throttled (HTTP 429), never silently banned without prior notice.

4.2 Rate-limit headers

Every response — including successful ones — carries these headers so clients can self-regulate:

When exceeded:

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 is always present on a 429 and is given in seconds.

5. Pagination, Filtering, Sorting & Sparse Fieldsets

5.1 Pagination (cursor + page)

SITP supports two pagination styles for list endpoints. Cursor is preferred for high-volume, ordered lists; page is supported for convenience and admin UIs.

Cursor tokens are opaque to the client (a base64url-encoded signed string); clients must treat them as black boxes and just pass them back. The response always tells the client how to continue via the links block (§6).

5.2 Filtering

Filters are whitelist-validated query parameters per endpoint. Unknown filters are rejected with SITP-VALIDATION-005. Common filters:

5.3 Sorting

?sort=<field> ascending; ?sort=-<field> descending (leading -). Multi-sort: ?sort=-createdAt,priority. Sortable fields are listed per endpoint in OpenAPI; sorting by an unsortable field returns SITP-VALIDATION-006.

5.4 Sparse fieldsets

Clients may request only the fields they need to reduce payload size, useful for mobile and metered networks:

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

Returns only the requested top-level fields inside data. Unknown or non-permitted fields are silently dropped (not an error) to keep clients forward-compatible. Nested sparse selection uses dot-paths: ?fields=ticketId,sla.responseBy.

6. Response Envelope

Every successful response uses the same envelope: { data, meta, links }. Single-resource responses put the resource in data and omit meta/links when empty; list responses populate all three.

Envelope example (list with cursor pagination)

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"
  }
}

Envelope example (single resource)

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

Errors do not use this envelope — they use RFC 7807 (§7).

7. Errors (RFC 7807 Problem Details)

All errors use RFC 7807 (application/problem+json). Every error carries a SITP-specific code (stable, machine-readable) in addition to the standard fields. Clients should branch on code, never on detail (which is human-readable and localized).

7.1 Standard fields

7.2 Validation error example

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 Error code catalog

Status codes follow HTTP. SITP error codes are grouped by family. The catalog is served live at https://sindhitportal.maahir.io/docs/errors and versioned in the OpenAPI document.

4xx errors (other than 429) are never retried by clients. 5xx and 429 may be retried with exponential backoff (see §8 and /specs/en/08-integrations-spec/ §11.2).

8. Idempotency

Every write (POST, PUT, PATCH, DELETE that mutates state) accepts the Idempotency-Key header. The header is a client-generated UUID v4 or v7. Within the 24-hour idempotency window (per NFR-INT-004 in /specs/en/08-integrations-spec/ §11):

• The first request with a given key is executed and its full response (status, body, headers) is cached.
• A repeat request with the same key returns the cached response, even if the original failed validationally — clients therefore must mint a fresh key when they change the payload.
• A repeat request with the same key but a different payload body returns SITP-CONFLICT-002 (409), protecting against accidental reuse of a key for a different intent.
• GET requests ignore the header.

Missing Idempotency-Key on a write returns SITP-VALIDATION-001 with a pointer at the header. The header is also surfaced in audit_logs.request_id correlation (per /specs/en/05-data-model/ §3.10) so a write and any resulting integration calls share a thread.

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

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

Replaying the identical request within 24 h returns the original 201 Created with the same ticketId, not a duplicate ticket.

9. OpenAPI 3.1 Skeleton

The full OpenAPI 3.1 document is generated from NestJS controllers via @nestjs/swagger and served at /api/v1/openapi.json, then rendered at /docs/api. The skeleton below shows the top-level document shape and three representative operations (POST /partners/tokens, POST /tickets, GET /tickets/{ticketId}). It is illustrative, not exhaustive.

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 }

The complete document repeats this pattern for every operation in §10, including request-body schemas, response envelopes, problem-details for every documented status, and the webhooks: extension (OpenAPI 3.1 supports native webhooks) for the events in §12.

10. Resource Catalog

The catalog below lists every endpoint in v1. Field names are stable; full schemas are in /api/v1/openapi.json. Each row carries: HTTP method, path, purpose, required auth scope (or public), and whether the write is idempotent (accepts Idempotency-Key).

Conventions: GET/HEAD are never idempotent-keyed. {ticketId} is the user-facing tracking id SITP-YYYY-DEPT-NNNNNN. All {orgId}/{repId} are opaque SITP ids.

10.1 Auth

10.2 Tickets

10.3 TicketMessages

10.4 Attachments

The recommended partner flow is presigned-URL upload to MinIO (the partner PUTs the bytes directly to object storage; SITP never proxies the bytes). After the PUT completes, the partner references the uploadId in POST /tickets (see §11.3 of /specs/en/08-integrations-spec/). Every upload is AV-scanned by ClamAV before it is attachable (SITP-UPLOAD-003 if infected — per /specs/en/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

The public-stats payloads are anonymized aggregates derived from the analytics model in /specs/en/17-analytics-kpis/. No individual ticket or company is identifiable.

10.11 Webhooks

Total v1 endpoints: 30.

11. Sample Request/Response Flows

Three end-to-end flows that exercise the envelope, idempotency, errors, and pagination. Field names mirror /specs/en/05-data-model/ (camelCased for the API).

11.1 Create a ticket (partner, on behalf of a company)

A partner app files a ticket on behalf of an authorized company, attaching a previously uploaded file. The call is idempotent; replaying the same Idempotency-Key within 24 h returns the identical 201 response (no duplicate ticket).

Request

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" }
}

Response

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"
  }
}

A duplicate POST with the same Idempotency-Key and an identical body returns the same 201 (with the same ticketId) instead of 409/duplicate; a different body with the same key returns 409 SITP-CONFLICT-002 (§8).

11.2 Get ticket status (read, sparse fieldset)

A partner polls a single ticket and asks only for status + SLA fields to keep the payload minimal on a metered mobile link. Uses the sparse-fieldset query (§5.4).

Request

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

Response

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"]
  }
}

Fields not requested (title, description, attachments, createdAt, …) are omitted. If the ticket does not exist or the caller lacks visibility, the response is 404 SITP-NOTFOUND-001 (§7.3) — same shape for both, so existence is not leaked.

11.3 List public stats (anonymous, no auth)

A citizen or researcher fetches the anonymized public-transparency aggregates. No token required; subject to the public rate-limit tier (§4.1).

Request

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

Response

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"
  }
}

The byDepartment and byStatus breakdowns are pre-aggregated nightly (per /specs/en/17-analytics-kpis/) and cached; the meta.anonymized: true flag is always present on public-stats responses. No individual ticket, company, or rep is identifiable in any public-stats payload.

12. Webhook Contract

Webhooks let partner apps react to SITP events in real time without polling. This section is the partner-facing contract; the receiver-side mechanics (signature verify, replay protect, enqueue) are described in /specs/en/08-integrations-spec/ §9.

12.1 Events

12.2 Delivery contract

• Transport: HTTPS POST to the partner's registered endpoint, JSON body, Content-Type: application/json.
• Signing: every payload is HMAC-SHA256 signed with the subscription's shared secret. The signature is sent in the X-SITP-Signature header as t=<unix-ts>,v1=<hex-signature> over the string <ts>.<raw-body>. Partners verify by recomputing the HMAC.
• Replay protection: the timestamp t is checked; requests older than 5 minutes must be rejected by the partner. Each delivery carries eventId and deliveryId; SITP records both in the webhook delivery log (per /specs/en/05-data-model/ §3.10 and /specs/en/08-integrations-spec/ §9.1).
• Retry: non-2xx responses are retried with exponential backoff — 10s, 30s, 2m, 10m, 1h, 6h, 24h (7 attempts). After exhaustion the delivery is flagged failed and surfaced in the partner dashboard for manual replay via POST /webhooks/subscriptions/{subId}/replay.
• Ordering: events for the same ticketId are delivered in order via a per-endpoint queue. Cross-ticket ordering is not guaranteed.
• Idempotency: partners must deduplicate on eventId; SITP may redeliver.
• Versioning: the data block carries a version field; a major shape change ships as a new version with parallel delivery until partners migrate.

12.3 HMAC-signed payload sample

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 }
}

Verification pseudocode (partner side):

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)

The signature is computed by SITP as HMAC_SHA256(secret, "<t>.<rawRequestBody>") and hex-encoded as v1.

13. SDK & Codegen Plan

SITP's OpenAPI 3.1 document is the single input for client SDK generation. The plan:

Conventions:

• Generated, never hand-written. SDKs are regenerated from openapi.json on every contract change; manual edits are forbidden.
• Stable method names. operationId in the OpenAPI doc is treated as a public symbol and changed only across a major version.
• Versioning. SDK packages are versioned independently and pin a major API version (sitp-sdk-ts@^1 ↔ API v1).
• Bundled models. Request/response types are bundled so partners get compile-time safety.
• Retry & idempotency built in. The official SDKs auto-mint Idempotency-Key for writes and retry idempotently on 5xx/429 with exponential backoff (capped) — partners do not implement this themselves.

14. Deprecation Policy

14.1 Lifecycle

Every API element (endpoint, field, parameter, enum value, event) moves through:

experimental → current → deprecated → sunset → removed

• experimental: behind a feature flag, may change without notice; documented as such in OpenAPI (x-sitp-experimental: true). Partners should not depend on these.
• current: stable, covered by the versioning guarantee.
• deprecated: still functional; announces a removal date. Adds the Deprecation and Sunset HTTP response headers (RFC 8594 / RFC 9745) on every affected response, and the OpenAPI doc marks it deprecated: true.
• sunset: returns the standard Sunset header with the removal date; calls succeed but are logged for telemetry.
• removed: returns SITP-NOTFOUND-001 (404) on an endpoint, or the field is absent from responses.

14.2 What counts as breaking (forces a new major)

• Removing or renaming an endpoint, field, parameter, or enum value.
• Changing a field's type, nullability, or semantics.
• Changing a default behavior clients depend on.
• Changing a status code or error code.
• Narrowing a paginated limit maximum.

14.3 What is non-breaking (ships in-version)

• Adding a new endpoint, field, parameter, or enum value (clients must ignore unknowns).
• Adding a new optional request field.
• Loosening validation (e.g., raising a max length).
• Reordering fields in a JSON object (clients must not depend on key order).

14.4 Timelines

• A deprecated element is supported for at least 12 months from the deprecation announcement before it can be removed (and only in a new major version).
• The previous major version is supported for at least 12 months of parallel run after the next major ships.
• Deprecation announcements are emailed to registered partners, posted on /docs/api/changelog, and surfaced in the partner dashboard.

15. Sandbox & Test Environment

A dedicated Sandbox environment lets partners build and test without touching production data.

15.1 Test data

• Synthetic organizations with known companyIds (cmp_test_*) documented in the sandbox onboarding pack.
• Synthetic CNICs/NTNs that return predictable mock results (e.g., active, not-found, cancelled) so partners can exercise every verification branch.
• A reset endpoint (POST /sandbox/reset) restores the seed dataset for repeatable tests. Production has no such endpoint.

15.2 Contract testing

• Every release runs the OpenAPI document against the live sandbox using prism to verify the implementation matches the contract.
• Partner-facing examples in this document are validated by a CI job that replays them against the sandbox on every change.

16. Observability — Correlation IDs

Every request — success or error — is traceable end-to-end via a correlation id.

Behavior:

• If the client sends X-Request-Id, SITP validates it (UUID or req_<ulid> form) and reuses it; otherwise SITP mints one (req_<ulid>).
• The id appears in: HTTP response header, the meta.requestId field of the envelope, the RFC 7807 requestId field on errors, every structured log line, every OTel span, the audit_logs.request_id column, and every int_call row for integration calls triggered by the request.
• Partners quoting the id in a support ticket lets SITP retrieve the full request trace in Grafana/Loki in seconds.
• PII is never placed in the id or in log tags; only opaque identifiers and outcome codes are logged (per /specs/en/11-security-compliance/).

17. Request Lifecycle (end-to-end)

The diagram shows the full lifecycle of a single authenticated write — POST /tickets — from the partner's HTTP call through every cross-cutting concern to the final response.

Written description. A partner issues POST /tickets with an Authorization bearer, an Idempotency-Key, and (optionally) an X-Request-Id. The nginx gateway forwards the call, minting a W3C traceparent if none is present. Inside NestJS, the cross-cutting middleware chain runs in a fixed order: CORS → rate limit → authentication → authorization (scope/role) → idempotency lookup → request validation → audit/OTel span open. Any failure short-circuits with an RFC 7807 problem document carrying the original X-Request-Id. If the idempotency key was seen within 24 h and the payload matches, the original response is replayed verbatim and no domain work runs. On a cache miss, the controller hands the validated DTO to the TicketsService, which opens a MariaDB transaction, generates the SITP-YYYY-DEPT-NNNNNN tracking id, inserts the ticket, writes a ticket_history row and an audit_logs row, and enqueues side-effects (SLA clock start, notifications, optional e-Office file push, registry verification jobs) to BullMQ — these run after the transaction commits so the response is never blocked by external latency. The transaction commits, the controller wraps the new ticket in the {data, meta, links} envelope, the middleware attaches the rate-limit and version headers, and the gateway returns 201 Created with a Location header pointing at the new resource. Meanwhile, the BullMQ workers fan out: notifications go out via the communications adapters, the ticket.created webhook is HMAC-signed and delivered (and retried per §12.2), and the SLA clock starts ticking within the department's business hours. Every step — gateway, middleware, domain, integration, queue — emits an OTel span tagged with the same X-Request-Id, so a partner reporting the id lets ops reconstruct the entire trace in Grafana/Loki.

18. Open Questions / TBD

End of document.