FoxReload ऑर्डर फ़्लो — Order बनाने से कोड डिलीवरी तक

FoxReload API पर ऑर्डर एक state machine से गुज़रते हैं। समझना कि कौन सा state कब आता है — पार्टनर को बेहतर UX और troubleshooting करने में मदद करता है।

State machine

Step-by-step flow

1. ऑर्डर create करें (active)

curl -X POST https://public-api.foxreload.com/api/orders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "itemId": "product_01krgfgww8eth9xvvysd6y7r4j",
        "quantity": 1,
        "note": {"player_id": "123456"}
      }
    ],
    "isMock": false
  }'

Response में id (UUID), status: "active", और paymentExpiresAt मिलेगा।

itemId वही product id है जो GET /api/products/ से मिलता है।

2. Payment (paid)

POST /api/orders/{order_id}/pay से payment शुरू करें:

curl -X POST https://public-api.foxreload.com/api/orders/{order_id}/pay \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"paymentProvider": "pally", "paymentReturnUrl": "https://yourshop.com/return"}'

अगर balance पर्याप्त है तो ऑर्डर सीधे paid → processing जाता है। कम balance होने पर BalanceNotEnough error आती है — पहले crypto top-up (POST /api/topups/crypto/) से balance बढ़ाएं।

3. Processing & Delivery (completed)

processing में supplier से कोड fetch होते हैं। जब status completed हो जाए, GET /api/orders/{order_id} से कोड लें:

curl https://public-api.foxreload.com/api/orders/{order_id} \
  -H "X-API-Key: YOUR_API_KEY"

Response में items[].externalData[] में delivered codes होंगे।

FoxReload API में webhooks नहीं हैं। Delivery जानने का एकमात्र तरीका polling है।

Polling pattern

async function waitForCompletion(orderId: string, maxWaitMs = 300_000) {
  const start = Date.now();
  while (Date.now() - start < maxWaitMs) {
    const order = await fetchOrder(orderId);
    if (order.status === 'completed') return order;
    if (order.status === 'cancelled' || order.status === 'failed') {
      throw new Error(`Order ${order.status}: ${order.cancelReason ?? order.items.map(i => i.error).join(', ')}`);
    }
    await sleep(5000); // 5 seconds प्रति poll
  }
  throw new Error('Timeout waiting for order completion');
}

Failure scenarios

Test orders (isMock)

Sandbox environment नहीं है। Test के लिए "isMock": true के साथ ऑर्डर बनाएं — real charges नहीं होते, fake codes मिलते हैं।

Best practices

• Retry से पहले status check: Double-order से बचने के लिए retry से पहले GET /api/orders/{id} से status verify करें।
• Exponential backoff: Network errors और 429 पर exponential backoff के साथ retry।
• Order log: हर ऑर्डर का state track करें — auditing के लिए।
• Error display: cancelled और failed orders customer को अलग-अलग clearly दिखाएं।

FoxReload API के order flow को समझना आपके reseller बिज़नेस में reliability का foundation है। isMock से testing, polling से delivery, और balance management — यह तीनों basics आपके customer experience को directly affect करते हैं।