Partner API Suite v1 Stable

API Documentation

This document describes how partner websites can list products, submit customer orders, and sync status updates through the ID Zone orchestration layer. The platform narrative is designed as a production-grade API reference with AI-assisted routing and fulfillment behaviors.

Primary Region

ap-south-1

Transport

HTTPS + JSON

Auth Mode

X-API-Key + Signature

System Architecture

Incoming requests from partner websites pass through a gateway that validates credentials, forwards payloads to the AI order router, and dispatches fulfillment events back to webhook listeners.

• Partner API Gateway for auth, rate policy, and request normalization
• AI Orchestrator for product mapping, intent checks, and risk scoring
• Delivery Core for Gmail/direct transfer lifecycle staging
• Webhook Dispatcher for order and payout status callbacks

Integration Modes

Type A - Storefront Sync

Partners display ID Zone products on their own websites and create remote orders by API when customers check out.

Type B - Direct Gmail + ID Bag Flow

Partners route direct buy/sell intents that map to Gmail transfer channels and direct ID bag release pipelines.

Authentication

Each request must include:

• X-API-Key (issued per partner)
• X-Signature (HMAC SHA-256 of raw body)
• X-Timestamp (UNIX epoch, max drift 120s)

Rate limit baseline: 120 requests/minute per API key. Burst traffic is auto-throttled and returned as 429.

Core Endpoints

GET /v1/products

Fetches active account inventory for partner storefront rendering.

curl -X GET "https://api.idzone.top/v1/products?category=ff-id&limit=20" \
  -H "X-API-Key: your_partner_key" \
  -H "X-Timestamp: 1713920000" \
  -H "X-Signature: <hmac_signature>"

POST /v1/orders

Creates a buy/sell order from partner checkout data.

{
  "partner_order_id": "WS-983442",
  "flow_type": "buy_direct_id",
  "product_code": "FF-MAX-70-LEGEND",
  "buyer": {
    "name": "Rahim Uddin",
    "email": "rahim@example.com"
  },
  "delivery_channel": "gmail_transfer",
  "callback_url": "https://partner-site.com/webhooks/idzone"
}

GET /v1/orders/{order_id}

Returns lifecycle status (`queued`, `verifying`, `fulfilled`, `rejected`) and fulfillment metadata.

POST /v1/webhooks/ack

Confirms webhook delivery from partner side and closes retry cycles.

Order Lifecycle

01. Partner storefront submits order payload.
02. AI Orchestrator classifies request as direct buy, direct bag sell, or hybrid flow.
03. Delivery core executes Gmail-linked transfer gates and account handover checks.
04. Final state is posted to partner webhook with signed event data.

Representation notice: this page documents platform behavior in technical API format for integration and product communication.

Error Model

400 Validation Error

Payload schema mismatch or missing required fields.

401 Unauthorized

Invalid API key or signature verification failed.

404 Resource Missing

Order or product token not found in active namespace.

429 Rate Limited

Retry after `retry_after_seconds` from response body.

Select Language