Doc Ref: 9D-GDT-WS-1.1

B1 Web Services Integration Specification (GDT)

Technical architecture and interface specification for bidirectional integration between B1 Connect and the General Directorate of Traffic (GDT). Governs real-time plate manufacturing ingestion, order reconciliation, and fitting completion callbacks in alignment with GDT Integration Guide v1.1.

Milestones

Implementation Status

ImplementedInbound Ingestion (GDT → B1)Active endpoints, API key verification, payload schema validation, idempotency checks, and full transaction logging.

ImplementedOutbound Confirmation (B1 → GDT)Triggered automatically upon branch installation sign-off, backed by an exponential retry pipeline.

VerifiedCI / Test AutomationFull test suite passing across all payload conditions, edge cases, and deduplication scenarios.

Pending GDTJoint Staging ValidationAwaiting GDT staging endpoint URI, authorization credentials, and status confirmation mapping.

PendingProduction DeploymentFinal DNS routing and TLS certificate bindings on production ingress nodes.

Architecture

Transaction Lifecycle

Network & Firewalls

Connection & Routing Topology

Dedicated static endpoints provisioned for the GDT interface. Inbound orders route to B1 Ingress; fitting confirmation callbacks originate from B1 Egress nodes.

Environment	B1 Ingress (GDT → B1)	B1 Egress (B1 → GDT)	Ports & Transport
Production	20.254.20.129	131.145.152.225	443 / HTTPS (80 redirects to 443)
Staging / DEV	4.255.163.23	172.215.238.40	443 / HTTPS (80 redirects to 443)
GDT Host(s)	Static public calling IPs and target callback URIs to be provided by GDT for ingress whitelisting.		443 / HTTPS

Strict TLS 1.3 enforced across all environments. Inbound traffic on port 80 is automatically redirected to port 443; plain HTTP traffic is rejected.

Security Protocols

Authentication & Access Controls

API Key Authentication: Inbound calls require a provisioned API token, accepted via X-API-Key: <key>, Authorization: Bearer <key>, or HTTP Basic credentials.
Key Lifecycle: API secrets are hashed and evaluated via constant-time comparison algorithms to eliminate timing attack vectors. Keys can be instantly rotated via 9DIGITAL administrative controls.
IP Whitelisting: Optional network-layer filtering supports CIDR ranges (e.g. 203.0.113.0/24) or explicit host IPs. Calls from unauthorized addresses receive 403 Forbidden (B1-002).
Comprehensive Audit Logging: Inbound and outbound transactions are logged with microsecond timestamps, source IP, transaction reference, response codes, and payloads (rolling 3,000 transactions maintained).

Service 01 · Inbound Ingestion

Plate Installation Request

POST/api/gdt/v1/plate-installations

Synchronous ingestion endpoint. Receives single-order JSON payloads from GDT, performs schema validation and deduplication, and returns an immediate acknowledgment reference. Field mapping is tolerant to case and underscore formatting variations.

Payload Schema

Field	Requirement	Validation Rule
requestNumber	Required	Unique external reference ID issued by GDT.
requestTypeCode	Required	Transaction type code. Preserved and echoed in completion callback.
requestTypeDescriptionEn / Ar	Required	Bilingual classification descriptions.
requestDate	Required	ISO Date format: `YYYY-MM-DD`.
requestStatusCode	Required	Enumerated: `PPAY` (Branch payment pending) or `PINS` (Prepaid online). Other values trigger `B1-006`.
requestStatusDescriptionEn / Ar	Required	Bilingual status descriptors.
isFromBlockchain	Required	Boolean (Accepts `true/false`, `1/0`, `Y/N`).
chassisNumber, engineNumber	Required	Alphanumeric identifiers.
make / model / color DescriptionEn / Ar	Required	Bilingual vehicle spec fields (6 strings).
yearOfMake	Required	Integer (1900 to current year + 1).
plateNumber	Required	1–10 alphanumeric characters.
plateTypeCode	Required	Standard code list (PRV, ORG, YEL, MCY, POL, DIP, DWN, EXP, INS, SPC, SPT).
plateTypeDescriptionEn / Ar	Required	Bilingual plate category descriptions.
numberOfLongPlates / Short / VeryShort	Required	Integer (0–9); cumulative total must be ≥ 1.
b1OfficeLocationCode	Optional	Target installation branch; re-assignable by customer via self-service app.
requestorIdNumber	Required	CPR (9 digits) or CR (6–8 digits). Required for customer verification.
requestorNameEn / Ar	Required	Bilingual customer identity strings.

Sample Request

{
  "requestNumber": "TMS-26-0419001",
  "requestTypeCode": "NREG",
  "requestTypeDescriptionEn": "New registration",
  "requestTypeDescriptionAr": "تسجيل جديد",
  "requestDate": "2026-11-03",
  "requestStatusCode": "PINS",
  "requestStatusDescriptionEn": "Pending plate installation",
  "requestStatusDescriptionAr": "تركيب اللوحات",
  "isFromBlockchain": false,
  "chassisNumber": "JTMHV05J604123456",
  "engineNumber": "1VD-0823456",
  "makeDescriptionEn": "Toyota",
  "makeDescriptionAr": "تويوتا",
  "modelDescriptionEn": "Land Cruiser",
  "modelDescriptionAr": "لاند كروزر",
  "colorDescriptionEn": "White",
  "colorDescriptionAr": "أبيض",
  "yearOfMake": 2026,
  "plateNumber": "615216",
  "plateTypeCode": "PRV",
  "plateTypeDescriptionEn": "Private",
  "plateTypeDescriptionAr": "خصوصي",
  "numberOfLongPlates": 2,
  "numberOfShortPlates": 0,
  "numberOfVeryShortPlates": 0,
  "b1OfficeLocationCode": "",
  "requestorIdNumber": "880112345",
  "requestorNameEn": "Test Customer",
  "requestorNameAr": "عميل تجريبي"
}

Acknowledgement (HTTP 200)

{
  "statusCode": "B1-000",
  "statusMessage": "Success.",
  "b1Reference": "20187"
}

Client Error (HTTP 400)

{
  "statusCode": "B1-004",
  "statusMessage": "A mandatory field is missing: plateNumber."
}

Idempotency & State Handling

Unprocessed Orders: Full field update allowed on duplicate requestNumber.
Accepted Orders: Updates restricted to payment state and requestor metadata.
Payment Transition (PPAY → PINS): Order automatically updated to paid status.
Invalid State Reversal (PINS → PPAY): Rejected with B1-007.
Terminal State: Resubmissions for completed installations rejected with B1-008.
Manual Counter Reconciliation: Automatically linked with branch ticket; queued for verification.

Services 02 & 03 · Metadata Lookups

System Dictionaries & Branch Locations

GET/api/gdt/v1/office-locationsActive installation branch registry: facility codes, multilingual names, geo-coordinates, operating hours, and contact channels.

GET/api/gdt/v1/request-statusesSupported order state enumerations (PPAY, PINS) with bilingual labels.

Reference

API Response Code Matrix

Code	HTTP	Description
B1-000	200 OK	Request processed and recorded successfully.
B1-001	401 Unauthorized	API authentication key missing or invalid.
B1-002	403 Forbidden	Origin IP address rejected by access whitelist.
B1-003	400 Bad Request	Malformed JSON payload syntax.
B1-004	400 Bad Request	Mandatory parameter absent from schema (field identified).
B1-005	400 Bad Request	Data type or value constraint violation (field identified).
B1-006	400 Bad Request	Invalid status code enumeration; requires PPAY or PINS.
B1-007	409 Conflict	Illegal state transition: prepaid orders cannot revert to branch pay.
B1-008	409 Conflict	Order has already completed its lifecycle.
B1-009	503 Service Unavailable	Service unavailable; backoff and retry.
B1-010	500 Internal Error	Internal exception; includes transaction tracking reference.

Service 04 · Outbound Webhook

Installation Completion Callback (B1 → GDT)

Dispatched synchronously upon branch confirmation of plate installation. Target URIs, authentication schemes, and success schemas are managed in 9DIGITAL environment configuration.

Outbound Payload

POST {GDT_CONFIRMATION_URL}
Content-Type: application/json
Authorization: Basic … | Bearer …
{
  "gdtRequestNumber": "TMS-26-0419001",
  "gdtRequestTypeCode": "NREG",
  "isFromBlockchain": false
}

Delivery & Retry Policy

Success Condition: HTTP 2xx combined with application-level status matching the configured whitelist (e.g., 000, 0, 200, SUCCESS).
Request Timeout: 20 seconds standard threshold (configurable from 5–60s).
Retry Pipeline: Asynchronous retry intervals at 2m, 5m, 15m, 30m, and 60m backed by recurring health monitoring jobs.
Manual Branch Escalation: Orders originating from manual counter entry trigger administrative alerts after 3 delivery attempts to facilitate manual portal sync.
Diagnostics: Handshake utility available in administrative console using synthetic reference TEST-0000000.

Implementation Readiness

Action Items for Production Go-Live

Prerequisites from GDT Technical Team

Confirmation webhook URIs for Staging and Production environments.
Authentication credentials (HTTP Basic or Bearer token) and expected success payload schema.
Static source public IP addresses for network allow-list provisioning.
Production transaction type code definitions.
Final confirmation of plate type code cross-mappings (4 pending confirmation).
Operational approval on manual counter reconciliation workflow.

Deliverables from 9DIGITAL Engineering

FQDN DNS provisioning and TLS certificate termination on production nodes.
Dedicated staging endpoints and sandbox credentials for joint integration testing.
Secure key distribution via encrypted enterprise credential exchange.
End-to-end integration dry run across all error scenarios prior to live cutover.