SPECIFICATION v1.0 • REST API v1

Developer Portal & API Reference

Welcome to the sans.uz Developer Portal. This documentation covers all endpoints for the REST API v1, enabling programmatic account management, live stock queries, and atomic license order fulfillment.

YOUR DEVELOPER CREDENTIALS

Status: Public Guest (Demo Mode)

Account: Public Visitor • Unit Price: $0.80 • Balance: $50.00 USDT • Available Stock: 931

Open Reseller Dashboard

Base URLs & Protocols

All requests must be issued over HTTPS. Non-TLS traffic is strictly rejected by our edge firewall.

Production Gateway: https://sans.uz/api/v1

Direct Bot Host: https://sans.uz/api/v1

Accepted Format: application/json

Authentication

API access is authenticated via a unique cryptographic key. Include your key in the X-API-Key request header, or as a Bearer token.

Primary Header Method (Recommended)

X-API-Key: sans_live_demo_developer_2026

Standard Authorization Header

Authorization: Bearer sans_live_demo_developer_2026

Quickstart Integration Guide

Send your first authenticated request to verify your connection and check your wallet balance.

cURL Command

curl -X GET "https://sans.uz/api/v1/me" \
  -H "X-API-Key: sans_live_demo_developer_2026" \
  -H "Accept: application/json"

Python Requests

import requests

url = "https://sans.uz/api/v1/me"
headers = {
    "X-API-Key": "sans_live_demo_developer_2026",
    "Accept": "application/json"
}
response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/me

Requires Auth

Returns account details, current wallet balance (USDT), custom wholesale tier, and API status.

Example 200 OK Response

{
  "status": "success",
  "user_id": 999999,
  "username": "developer_demo",
  "balance": 50.00,
  "api_price_per_link": 0.80,
  "api_enabled": 1,
  "timestamp": "2026-10-01T03:00:00Z"
}

GET /api/v1/products

Public / Optional Auth

Fetches real-time catalog SKUs, live inventory counts, unit wholesale prices, and maximum batch allowances.

Example 200 OK Response

{
  "status": "success",
  "products": [
    {
      "service_id": "gemini_18m",
      "name": "Google Gemini Advanced 18 Months",
      "category": "AI",
      "price": 0.80,
      "in_stock": 931,
      "max_order": 100
    }
  ]
}

GET /api/v1/categories

Public / Discovery

Returns all active catalog categories, display icons, sort rankings, and effective pricing markup configurations.

Example 200 OK Response

{
  "status": "success",
  "categories": [
    {
      "id": "cat_ai",
      "name": "Artificial Intelligence",
      "icon": "🤖",
      "sort_order": 1,
      "markup": 0.0,
      "enabled": true
    },
    {
      "id": "cat_vpn",
      "name": "VPN & Privacy",
      "icon": "🛡️",
      "sort_order": 2,
      "markup": 0.50,
      "enabled": true
    }
  ]
}

POST /api/v1/order

Requires Auth & Balance

Atomically purchases and dispenses digital product licenses. Deducts user balance and delivers activation URLs immediately in the response.

JSON Request Body

{
  "service_id": "gemini_18m",
  "quantity": 1,
  "custom_id": "YOUR_INTERNAL_TRANSACTION_ID"
}

Example 200 OK Response

{
  "status": "success",
  "order_id": "ORD-2026-A89B4C2D",
  "custom_id": "YOUR_INTERNAL_TRANSACTION_ID",
  "unit_price": 0.80,
  "total_cost": 0.80,
  "remaining_balance": 49.20,
  "links": [
    "https://serviceactivation.google.com/subscription/new/EXAMPLE_TOKEN"
  ]
}

GET /api/v1/stats

Requires Auth

Returns global platform health, user transaction totals, order counts, and system metrics.

ADMIN Category & Product Management API

Requires X-Admin-Secret or Admin API Key

Programmatically create, edit, reorder, restock, and delete categories and custom products. Provide header X-Admin-Secret or an admin X-API-Key.

POST /api/v1/admin/categories — Create Category

Payload: {"category_id": "cat_vpn", "name": "VPN Services", "icon": "🛡️", "markup": 0.50, "sort_order": 3}

PUT /api/v1/admin/categories/{id} — Update Category

Payload: {"name": "Ultra VPN", "icon": "⚡", "markup": 0.75, "sort_order": 1, "enabled": true}

DELETE /api/v1/admin/categories/{id} — Delete Category

Safely deletes the category and reassigns all associated products to cat_other.

POST /api/v1/admin/products — Create Product & Stock

Payload: {"key": "nord_vpn_1y", "name": "NordVPN 1 Year", "category": "cat_vpn", "price": 4.99, "stock_items": ["KEY_1", "KEY_2"]}

PUT /api/v1/admin/products/{key} — Update Product & Stock

Payload: {"name": "NordVPN Ultimate", "price": 5.49, "category": "cat_vpn", "add_stock": ["KEY_3"]}

DELETE /api/v1/admin/products/{key} — Delete Product

Deletes the product and stock from active inventory.

Error Codes & Handling

Standard RFC 7807 compliant HTTP status codes are used across all API responses.

Status Code	Meaning	Description
400 Bad Request	INVALID_PAYLOAD	Missing quantity or insufficient account balance to complete purchase.
401 Unauthorized	INVALID_KEY	Missing or invalid X-API-Key token.
403 Forbidden	API_DISABLED	API access has been revoked or frozen for your account.
429 Too Many Requests	RATE_LIMITED	Exceeded 60 requests/minute tier limit. Implement exponential backoff.
502 / 503 Bad Gateway	UPSTREAM_RETRY	Upstream supplier failover in progress. Automatically retried by system.