FoxReload Order Polling और अपना Notification Layer

संक्षिप्त उत्तर

FoxReload में webhooks नहीं हैं। Order का status और codes पाने का एकमात्र तरीका है GET /api/orders/{order_id} poll करना। जब status completed हो, items[].externalData में codes मिलते हैं। Customer को notify करने के लिए अपना notification layer build करें — polling loop complete होने पर email/Telegram/queue trigger करें। यह guide FoxReload-specific polling pattern और अपना notification layer build करने की architecture explain करती है।

महत्वपूर्ण: FoxReload में कोई webhook endpoint register करने का option नहीं है, कोई HMAC signature नहीं, कोई order.fulfilled events नहीं। Codes के लिए GET /api/orders/{order_id} poll करें। यह design choice है — reliable polling से ही order status मिलता है।

मुख्य निष्कर्ष: FoxReload polling-based है। Order create होने के बाद उसे poll करें जब तक completed, failed, या cancelled status न मिले। Completed orders के items[].externalData में codes होते हैं। Double-buying से बचने के लिए retry से पहले हमेशा GET /api/orders/ से existing order check करें।

यह Guide किसके लिए है

• Developers जो FoxReload API integrate कर रहे हैं और order fulfillment automate करना चाहते हैं
• Store operators जो pending orders को reliably handle करना चाहते हैं
• High-volume digital goods pipeline build करने वाले

FoxReload Order Flow

POST /api/orders/          ← order create करें
  { items: [{ itemId, quantity }] }
→ { id: "ord_...", status: "active" }

GET /api/orders/{order_id}  ← status poll करें
→ { status: "processing" }  ← फिर poll करें

GET /api/orders/{order_id}  ← poll करते रहें
→ { status: "completed",
    items: [{ externalData: ["XXXXX-YYYYY-ZZZZZ"] }] }

Polling loop (Python example):

import time, requests

BASE = "https://public-api.foxreload.com"
HEADERS = {"X-API-Key": "YOUR_API_KEY"}

def poll_order(order_id, max_attempts=30, interval=3):
    for _ in range(max_attempts):
        resp = requests.get(f"{BASE}/api/orders/{order_id}", headers=HEADERS)
        order = resp.json()
        status = order["status"]
        if status == "completed":
            codes = [item["externalData"] for item in order["items"]]
            return {"status": "completed", "codes": codes}
        elif status in ("failed", "cancelled"):
            return {"status": status, "error": order.get("items")}
        time.sleep(interval)
    raise TimeoutError(f"Order {order_id} still pending after {max_attempts} attempts")

isMock — Test Orders

FoxReload में sandbox environment नहीं है। Test orders के लिए isMock: true use करें:

POST /api/orders/
{
  "items": [{"itemId": "product_01k...", "quantity": 1}],
  "isMock": true
}

isMock orders real balance deduct नहीं करते और test codes return करते हैं।

Balance और BalanceNotEnough Error

FoxReload prepaid model पर चलता है। Balance कम होने पर order creation BalanceNotEnough error return करती है। Balance top up करने के लिए:

POST /api/topups/crypto/
{ "chain": "...", "asset": "USDT", "balanceCurrency": "USD", "quoteAmount": 100 }

Production में balance monitor करें — BalanceNotEnough पर orders तुरंत fail होती हैं।

Codes कहाँ मिलते हैं

Completed order में:

{
  "status": "completed",
  "items": [
    {
      "itemId": "product_01k...",
      "externalData": ["XXXXX-YYYYY-ZZZZZ"],
      "error": null
    }
  ]
}

• externalData: array of codes/pins
• error: per-item error अगर कोई हो

अपना Notification Layer

FoxReload के पास customer notifications नहीं हैं — यह आपकी responsibility है। Polling complete होने पर:

Architecture:

[Payment confirmed]
      ↓
[POST /api/orders/ → order_id मिला]
      ↓
[Background job: poll until completed/failed]
      ↓
[completed → codes extract → customer को deliver]
[failed → ops alert → refund flow]

Double-Buy से बचाव

FoxReload में idempotency keys नहीं हैं। Retry करने से पहले:

# order create करने से पहले pending orders check करें
existing = requests.get(
    f"{BASE}/api/orders/?statuses=active,paid,processing",
    headers=HEADERS
).json()
# same item का pending order exist करता है? तो नया मत बनाएं

Network error पर blindly retry करने से double-buying हो सकता है।

Error Handling

Implementation Checklist

• POST /api/orders/ से order create करें (X-API-Key header)
• Polling loop implement करें (हर 3-5s, max 30 attempts)
• Completed order के items[].externalData से codes extract करें
• Customer delivery: email/Telegram/in-app
• Failed/cancelled orders के लिए ops alerting
• Balance monitoring और low-balance alert
• Retry से पहले existing orders check (double-buy prevention)
• isMock: true से test करें
• 429 errors के लिए exponential backoff