डिजिटल गुड्स सप्लायर API कैसे जोड़ें

सप्लायर API जोड़ना का मतलब «एक curl चला दिया और हो गया» नहीं है। यह एक अलग service layer है जिसे किसी और के outage झेलने हैं, एक ही code दो ग्राहकों को कभी नहीं देना है, और supplier के deploy के समय आपका storefront नहीं गिरने देना है। नीचे पहली key से लेकर go-live checklist तक का व्यावहारिक क्रम है।

Architecture — दो नहीं, तीन layer

Production में टिकने वाला एकमात्र ढाँचा यही है:

Supplier API → आपका middleware → storefront.

Middleware आपकी अपनी service है (या background jobs और internal endpoints का सेट) जिसके पास supplier key है, जो catalogue की local copy रखती है, orders बनाती है, उनका status poll करती है और storefront को केवल normalised data देती है।

तीन चीज़ें बिल्कुल नहीं करनी:

• Browser या mobile app से सीधे supplier API call करना। इसका मतलब है key client पर पहुँच गई। Supplier key हमेशा server-side secret है।
• हर catalogue page render पर supplier API हिट करना। Rate limit लगेगा और आपकी availability किसी और के uptime की बंधक बन जाएगी।
• Storefront controller में fulfilment logic रखना। Fulfilment एक अलग service में idempotent operation होनी चाहिए, वरना ग्राहक का double-click double order बन जाएगा।

Step 1. Credentials और environments

सबसे पहले आपको key मिलती है। Code लिखने से पहले तीन बातें पक्की करें:

1. कौन सा auth header है। X-API-Key हो सकता है, Authorization: Bearer हो सकता है, या request signature। FoxReload X-API-Key: YOUR_API_KEY इस्तेमाल करता है — कोई Bearer token, OAuth या client_id/client_secret नहीं।
2. क्या key दोबारा दिखेगी। ज़्यादातर सप्लायरों के यहाँ नहीं। FoxReload key सिर्फ़ एक बार दिखाता है, इसलिए वह सीधे secret manager (Vault, AWS Secrets Manager, Doppler) में जानी चाहिए, repo के .env में नहीं।
3. क्या IP allowlist है। अगर है तो चालू करें। FoxReload में key को IP या CIDR से सीमित किया जा सकता है, अधिकतम 10 entries; allowlist से बाहर के IP से request HTTP 403 लौटाती है — यह हर जगह से चलने वाली leaked key से कहीं बेहतर परिणाम है।

Test environment का सवाल

कई सप्लायर अलग sandbox host देते हैं। कई नहीं देते। FoxReload में अलग sandbox environment है ही नहीं — testing order body में isMock: true से होती है, जो असली order जैसी ही response structure में mock codes लौटाता है, बिना balance काटे।

यह architecture के लिहाज़ से अहम है। पहला integration test लिखने से पहले अपने सप्लायर से पूछ लें कि testing असल में कैसे होती है। अगर test mode एक request flag है न कि अलग host, तो आपके code को वह flag पूरे stack से गुज़ारना होगा और आपके database को mock orders को असली orders से अलग पहचानना होगा।

Step 2. Catalogue और price sync

Catalogue एक background job है, on-demand request नहीं।

curl "https://public-api.foxreload.com/api/categories/?limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

फिर हर category से products:

curl "https://public-api.foxreload.com/api/products/?category_id_or_slug=gift-cards&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

हर product में id, name और price आते हैं। id वही है जो बाद में order बनाते समय itemId के रूप में जाता है, इसलिए उसे अपनी table में supplier का foreign key बनाकर रखें।

व्यावहारिक नियम:

• अपने internal SKU के साथ supplier_product_id भी रखें। अपने storefront को कभी एक ही सप्लायर के identifiers से सीधे मत बाँधें, वरना दूसरा सप्लायर जोड़ना rewrite बन जाएगा।
• Prices को अलग, ज़्यादा बार चलने वाले job से refresh करें। नाम और description कम बदलते हैं, दाम लगातार।
• किसी एक response में product न दिखे तो उसे delete मत करें। उसे unavailable flag करें। एक partial response या timeout आपका पूरा catalogue मिटा नहीं सकता।
• Markup अपने system में रखें, cost price में मिलाकर नहीं। सप्लायर की कीमत input है; retail price आपके pricing engine का output।

Step 3. Balance check

थोक digital-goods API आमतौर पर prepaid balance पर चलते हैं: आप खाता fund करते हैं और orders उसमें से कटते हैं। इससे एक नया failure class आता है — order इसलिए fail हुआ कि पैसे ख़त्म हो गए, आपके code की वजह से नहीं।

क्या बनाना है:

• रक़म बड़ी हो तो order बनाने से पहले balance पढ़ें।
• Background balance monitoring दो थ्रेशोल्ड के साथ रखें — warning और critical — और alert उस channel में भेजें जिसे रात में भी कोई पढ़ता है।
• Insufficient funds error को ठीक से handle करें। FoxReload में यह BalanceNotEnough के रूप में आता है; top-up POST /api/topups/crypto/ से होता है। अपने सप्लायर से पूछें कि वह कौन-से funding तरीक़े देता है और settlement में कितना समय लगता है — यही तय करता है कि आपको कितना float रखना है।

ग्राहक की तरफ़ का पहलू भी सोचें। Balance ख़त्म होने पर खरीदार को 500 error नहीं मिलना चाहिए। उसे स्पष्ट मना मिलना चाहिए — या बेहतर, वह item checkout में दिखे ही नहीं जिसे आप अभी ख़रीद ही नहीं सकते।

Step 4. Order बनाना

Order एक POST है जिसमें line items का array जाता है:

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": false
  }'

Response में order object आता है — id, price, status, createdAt, paymentExpiresAt और items[] array के साथ।

Idempotency पर ज़रूरी चेतावनी

कुछ API Idempotency-Key header स्वीकार करते हैं ताकि वही request दोबारा भेजने पर दूसरा order न बने। ज़रूर जाँचें कि आपका सप्लायर वाक़ई इसे implement करता है या नहीं — बहुत से नहीं करते। FoxReload Idempotency-Key header को support नहीं करता।

Support न होने पर duplicate protection आप ख़ुद बनाते हैं:

1. अपनी तरफ़ एक unique operation key बनाएँ और supplier को call करने से पहले उसे database में save करें।
2. Network error या timeout पर आँख मूँदकर दोबारा order मत बनाएँ — पहले supplier की order list माँगकर देखें कि order बना तो नहीं।
3. पक्का हो जाए कि order मौजूद नहीं है, तभी retry करें।

Order creation पर timeout अनिश्चितता है, failure नहीं। उसे failure मानकर तुरंत retry करना यह फ़र्क़ सीखने का सबसे महँगा तरीक़ा है।

Step 5. Status retrieval — baseline के रूप में polling

Polling वह mechanism है जो हमेशा काम करता है। Webhooks एक optional सुविधा है।

जाँचें कि आपका सप्लायर webhooks देता है या नहीं और उन्हें sign करता है या नहीं (HMAC या कोई और स्कीम)। अगर देता है, तो webhook को accelerator मानें — पर polling safety net के तौर पर बनी रहनी चाहिए, क्योंकि delivery की गारंटी कभी नहीं होती और आपका endpoint ठीक ग़लत वक़्त पर down हो सकता है। FoxReload webhooks देता ही नहीं; order result सिर्फ़ polling से मिलता है।

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

काम करने वाला polling schedule:

FoxReload में order active → paid → processing → completed से गुज़रता है, और terminal शाखाएँ हैं cancelled (cancelReason के साथ) और failed (हर item की error items[].error में)। completed पर codes items[].externalData में होते हैं। पूरी state walkthrough order flow वाले लेख में है।

Step 6. Error handling

Errors को तीन हिस्सों में बाँटें और अलग-अलग बरतें:

• कभी retry न करें। HTTP 400, 401, 403, 404 आपकी bug या configuration की ग़लती है। दोबारा भेजने पर वही जवाब आएगा। Log करें और ठीक करें।
• Backoff के साथ retry करें। HTTP 429 (rate limit) और 5xx। Jitter के साथ exponential backoff, सीमित attempts, interval पर ceiling।
• Retry से पहले जाँचें। Mutating calls पर network timeout। पहले पता करें supplier की तरफ़ क्या हुआ, फिर कार्रवाई करें।

Order के अंदर per-item errors अलग मामला है। Order आंशिक रूप से पूरा हो सकता है: एक line delivered, दूसरी नहीं। आपके data model को partial fulfilment दिखाना आना चाहिए, वरना refund logic ग़लत निकलेगी।

Step 7. Go-live checklist

• Key secret manager में है, git में नहीं, और repo history जाँची जा चुकी है।
• सप्लायर support करता हो तो IP allowlist चालू है।
• जिन-जिन product types को आप बेचते हैं, सब पर mock (या sandbox) orders चलाए जा चुके हैं।
• Catalogue sync scheduled है और partial response पर catalogue मिटता नहीं।
• Balance दो alert थ्रेशोल्ड के साथ monitor होता है।
• Order placement आपकी तरफ़ duplicate-protected है।
• Polling में deadline है और stuck-order queue पर alert है।
• Retry सिर्फ़ 429 और 5xx पर चलता है।
• हर supplier request और response आपके internal order ID के साथ log होता है — विवाद में यही आपका सबूत है।
• एक manual runbook मौजूद है: order अटक जाए और ग्राहक support में लिख चुका हो, तब operator क्या करेगा।

माल कहाँ से लें

Integration layer एक बार बनाना समझदारी है, और ऐसे catalogue के सामने जो आपकी अधिकांश range कवर कर ले। FoxReload एक थोक digital-goods सप्लायर है जिसके पास 900+ SKU हैं — game keys, gift cards, game top-ups, eSIM और software licences — सब एक ही REST API के पीछे, automated delivery और multi-region SKUs के साथ। पाँच अलग auth schemes वाले पाँच integrations की जगह एक key, एक response shape और पूरी range पर एक order model।

आगे पढ़ें

• FoxReload API quickstart 2026
• Order flow की पूरी व्याख्या
• Webhooks की जगह polling
• API पर digital goods store लॉन्च करना
• Gift-card API — code retrieval और automated delivery