FoxReload Order Polling — Webhook नहीं, Polling से Real-Time Updates

FoxReload Public API में webhooks नहीं हैं। कोई X-FoxReload-Signature header नहीं, कोई HMAC callbacks नहीं, कोई order.* events नहीं। Order का status और delivered codes जानने का एकमात्र तरीका है GET /api/orders/{order_id} को poll करना।

यह article explain करता है कि reliable polling loop कैसे implement करें, और अगर आप अपने downstream systems को push notifications देना चाहते हैं तो अपनी खुद की webhook/queue layer polling के ऊपर कैसे बनाएं।

FoxReload Order Status Polling

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

Order object में status field: active | paid | processing | completed | cancelled | failed।

completed होने पर items[].externalData[] में codes मिलते हैं।

Basic Polling Loop

async function pollUntilDone(orderId: string, timeoutMs = 300_000): Promise<Order> {
  const deadline = Date.now() + timeoutMs;
  let delay = 3_000; // 3s से शुरू

  while (Date.now() < deadline) {
    const order = await getOrder(orderId); // GET /api/orders/{id}

    if (order.status === 'completed') {
      // codes मिल गए
      const codes = order.items.flatMap(i => i.externalData ?? []);
      return order;
    }

    if (order.status === 'cancelled' || order.status === 'failed') {
      throw new Error(
        `Order ${order.status}: cancelReason=${order.cancelReason}, ` +
        `errors=${order.items.map(i => i.error).filter(Boolean).join('; ')}`
      );
    }

    await sleep(delay);
    delay = Math.min(delay * 1.5, 15_000); // max 15s interval
  }

  throw new Error(`Polling timeout for order ${orderId}`);
}

Polling tips:

• 3–5 second intervals से शुरू करें, धीरे-धीरे बढ़ाएं।
• 429 मिले तो Retry-After header respect करें।
• 5 minutes के बाद आप timeout मान सकते हैं; ऑर्डर cancel/fail नहीं हुआ तो support से contact करें।

अपनी Webhook Layer बनाएं (Optional)

अगर आपके downstream systems को push notifications चाहिए — जैसे Telegram bot को instantly message देना — तो आप polling को अपने internal queue के ऊपर रख सकते हैं। यह आपकी infrastructure है, FoxReload feature नहीं।

Architecture

FoxReload API  ←─── Polling Worker ───→  आपका Internal Queue
                                                  │
                                          ┌───────┴───────┐
                                          │               │
                                   Email Worker    Bot Worker
                                   (customer)     (Telegram)

Polling Worker (Node.js + BullMQ)

import { Queue, Worker } from 'bullmq';

const orderQueue = new Queue('foxreload-orders', { connection: redis });

// ऑर्डर बनाने के बाद polling job add करें
async function createAndTrack(orderPayload: object) {
  const order = await foxreloadApi.post('/api/orders', orderPayload);
  await orderQueue.add('poll', { orderId: order.id }, {
    delay: 3000,
    attempts: 60,           // max 60 polls
    backoff: { type: 'fixed', delay: 5000 }, // 5s interval
  });
  return order;
}

// Worker जो poll करे और complete होने पर downstream notify करे
new Worker('foxreload-orders', async (job) => {
  const order = await foxreloadApi.get(`/api/orders/${job.data.orderId}`);

  if (order.status === 'completed') {
    const codes = order.items.flatMap(i => i.externalData ?? []);
    await deliverToCustomer(order, codes); // email/Telegram/etc
    return; // job done
  }

  if (order.status === 'cancelled' || order.status === 'failed') {
    await notifyFailure(order);
    return;
  }

  // अभी pending — job को fail करें ताकि retry हो
  throw new Error('order not yet complete');
}, { connection: redis });

Idempotency (Client-Side)

FoxReload API में Idempotency-Key header नहीं है। Retry से पहले हमेशा order status check करें:

async function safeCreateOrder(payload: OrderPayload, clientRef: string) {
  // क्या पहले से ऑर्डर बना? अपने DB में check करें
  const existing = await db.orders.findByClientRef(clientRef);
  if (existing) {
    // पहले से बना हुआ है — duplicate मत बनाओ
    return existing;
  }

  const order = await foxreloadApi.post('/api/orders', payload);
  await db.orders.insert({ ...order, clientRef });
  return order;
}

API में idempotency keys नहीं हैं — client-side dedup आपकी ज़िम्मेदारी है।

Best Practices

Test Orders

Production में जाने से पहले isMock: true के साथ orders test करें:

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}],"isMock":true}'

Fake codes मिलते हैं, balance debit नहीं होता।

FoxReload के साथ reliable delivery का formula simple है: ऑर्डर बनाओ, poll करो, completed पर codes निकालो, customer को deliver करो। Webhooks की ज़रूरत है तो वो layer आपकी system में polling के ऊपर बनाएं।