sandbox और production API key में फर्क: पहली बार live जाने से पहले की गाइड

मुख्य बातें

• Sandbox key का prefix sk_test_ है और production key का sk_live_। दोनों के लिए header एक ही है: Authorization: Bearer <key> या x-api-key: <key>।
• Environment आपके URL से नहीं, key से तय होता है। StampMitra का server key देखकर तय करता है कि call sandbox की है या production की।
• Sandbox calls metered और logged होती हैं, पर कभी आपका wallet नहीं घटातीं। production में हर सफल call पर wallet से कटौती होती है।
• Sandbox key signup पर तुरंत मिल जाती है। production key के लिए dashboard से production access की application देनी पड़ती है और approval के बाद ही key बनती है।
• हर key पर scopes लगते हैं, जैसे verification.pan.read या orders.create। ज़रूरत से ज़्यादा scope कभी न दें।
• संवेदनशील scopes पर IP allowlist लगती है। launch से पहले अपने server का outbound IP पता कर लें, वरना production में अचानक request रुक सकती है।
• Raw key सिर्फ एक बार दिखती है। उसे .env या secret manager में रखें, code या Git में नहीं।
• Error हमेशा { "error": { "code", "message", "requestId" } } शक्ल में आता है। requestId संभालकर रखें, support के काम आएगा।

पहली बार live जाने से पहले की checklist: क्या-क्या निपटाना है?

मान लीजिए कल आपको अपना app production में डालना है। नीचे की checklist ऊपर से नीचे चलाइए। हर बिंदु के पीछे एक असली तरह की गड़बड़ी है जो लोगों के साथ होती है, और आगे के सेक्शन में हम हर बिंदु का विस्तार देखेंगे।

Launch से पहले (कम से कम एक दिन पहले)

1. production access की application dashboard से जमा हो चुकी है, और आप जानते हैं कि किन products के लिए आवेदन किया है।
2. आपका organization approve हो चुका है और production key बनाने का विकल्प दिख रहा है।
3. API credit wallet में इतना balance है कि पहले दिन का traffic संभल जाए। पैसा Dashboard के Billing हिस्से से जोड़ा जाता है।
4. production key को सिर्फ उतने scopes दिए गए हैं जितने code को सचमुच चाहिए।
5. अपने server का outbound IP (या NAT gateway का static IP) पता है और वह key की IP allowlist में डला है।
6. production key सिर्फ production के secret store में है। laptop, chat या repo में उसकी कोई कॉपी नहीं।

Launch वाले दिन

7. app के startup पर एक guard है जो जाँचता है कि production में sk_test_ key तो नहीं लगी है, और staging में sk_live_ तो नहीं।
8. एक कम जोखिम वाली असली call (जैसे अपना ही PAN) से पहले end-to-end टेस्ट हो चुका है।
9. 401, 402, 403 और 429 के लिए आपके code में अलग-अलग handling है, सिर्फ एक "कुछ गड़बड़ हुई" नहीं।
10. हर response का referenceId और हर error का requestId आपके log में जा रहा है।

Launch के बाद (पहले हफ्ते में)

11. wallet balance पर alert है, ताकि 402 से पहले आपको पता चल जाए।
12. पुरानी sandbox key को production code से हटा दिया गया है और key rotate करने की तारीख calendar में है।

अगर इनमें से आधे बिंदु भी आपके यहाँ खाली हैं, तो launch एक दिन टाल देना सस्ता सौदा है। आगे के सेक्शन में हम देखेंगे कि हर बिंदु क्यों ज़रूरी है।

sandbox और production API key में असली फर्क क्या है?

एक ही API, दो अलग दुनिया। sandbox आपके लिए रिहर्सल का मंच है, production असली शो। नीचे की table में वही फर्क हैं जो StampMitra के docs और pricing/home pages में लिखे हैं।

"Sandbox में सब चलता है, production में नहीं" वाली गलतफहमी

इसका उल्टा भी उतना ही सच है। अक्सर sandbox में सब कुछ इसलिए चलता है कि वहाँ अनुमति और data दोनों ढीले हैं। production में तीन चीज़ें अचानक सख्त हो जाती हैं: key की scope list, IP allowlist, और wallet balance। इसलिए "मेरा code sandbox में पास हो गया" का मतलब सिर्फ इतना है कि आपका request shape सही है। यह नहीं कि आपका production setup भी सही है।

Sandbox किस काम का है

StampMitra के home page पर साफ लिखा है कि sandbox यह साबित करने के लिए है कि आपका integration काम करता है। यानी request बनाना, response पढ़ना, error संभालना और referenceId को अपने database में रखना, यह सब वहीं सीखें। असली मौसम, असली ट्रैफिक और असली ग्राहक के नाम वाला व्यवहार production में ही दिखेगा।

sk_test_ और sk_live_ को पहचानकर request कैसे भेजें?

हर protected endpoint पर दो में से एक header ज़रूरी है। docs का नियम सीधा है: Authorization: Bearer <key> या x-api-key: <key>। दोनों बराबर मान्य हैं, एक ही चुनें और पूरे code में वही रखें, ताकि log पढ़ना आसान रहे।

cURL से पहली call

नीचे PAN verification का वह request है जो docs में लिखा है। endpoint POST /v1/verify/pan है और इसके लिए key पर verification.pan.read scope चाहिए। Base URL https://api-b2b.stampmitra.in है।

curl -X POST "https://api-b2b.stampmitra.in/v1/verify/pan" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pan":"ABCDE1234F","name":"Rahul Kumar"}'

सफल होने पर response कुछ ऐसा आता है (docs का नमूना, आपके असली ग्राहक का data नहीं):

{
  "referenceId": "SMV-20260927-8F42K7",
  "pan": "ABCDE1234F",
  "type": "Individual",
  "valid": true,
  "registeredName": "RAHUL KUMAR",
  "fatherName": "SURESH KUMAR",
  "panStatus": "VALID",
  "panStatusCode": "E",
  "panStatusDescription": "Existing and valid PAN",
  "nameMatchResult": "MATCH",
  "nameMatchScore": "100",
  "aadhaarSeedingStatus": "y",
  "aadhaarSeedingStatusDescription": "Aadhaar linked",
  "lastUpdatedAt": "2023-04-01",
  "message": "PAN is Valid"
}

x-api-key वाला तरीका

कुछ proxies या API gateways Authorization header को अपने काम के लिए रख लेते हैं। ऐसी जगह x-api-key आसान पड़ता है। request वही रहती है, बस header बदलता है:

curl -X POST "https://api-b2b.stampmitra.in/v1/verify/pan" \
  -H "x-api-key: $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pan":"ABCDE1234F"}'

कुछ बारीकियाँ जो वक्त बचाती हैं

• Key में Bearer शब्द के बाद एक space ज़रूरी है। Bearersk_test_... जैसी गलती 401 देती है।
• Key को URL या query string में कभी न रखें। वह proxies और access logs में दिख जाती है।
• Key को कॉपी करते समय आगे-पीछे का space या newline अक्सर साथ आ जाता है। environment variable में डालते समय trim कर लें।
• PAN का नमूना ABCDE1234F सिर्फ एक sample है, असली PAN docs या लेख में कहीं न डालें।

इसी request को Node.js और Python में पूरी तरह लिखकर हम आगे के एक सेक्शन में देखेंगे। अगर आप PAN verification का पूरा flow चाहते हैं, तो हमारी Node.js और Python में PAN verify करने की गाइड देखें।

Environment तय कौन करता है: URL या key?

यह सवाल हर नए डेवलपर के मन में आता है, क्योंकि कई दूसरे services में sandbox के लिए अलग host होता है। StampMitra के docs में एक ही base URL दिखता है और home page साफ कहता है कि environment आपकी API key से server-side तय होता है। मतलब sk_test_ वाली key भेजी तो call sandbox की मानी जाएगी, sk_live_ भेजी तो production की।

इसके व्यावहारिक नतीजे

पहला नतीजा यह कि आपको staging और production के बीच URL बदलने की ज़रूरत नहीं पड़ती। आपको सिर्फ environment variable STAMPMITRA_API_KEY की value बदलनी होती है। यह सुविधा भी है और जोखिम भी। जोखिम यह कि अगर गलत key गलत जगह चली गई, तो कोई URL-स्तर की चेतावनी आपको नहीं मिलेगी। staging server पर sk_live_ key लगी रह गई तो आपका test traffic असली wallet से पैसे काटेगा।

दूसरा नतीजा यह कि आपके tests और CI में कभी production key न रखें। CI के secret में सिर्फ sk_test_ key रखें और उसे सिर्फ sandbox के काम के लिए इस्तेमाल करें।

एक छोटा guard जो दोनों गलतियाँ पकड़ता है

यह छोटा function app के शुरू होते ही चलाइए। यह key का prefix देखकर तय करता है कि वह मौजूदा environment के लिए ठीक है या नहीं।

// config/stampmitra.js
export function loadStampMitraKey(appEnv) {
  const key = (process.env.STAMPMITRA_API_KEY || "").trim();
  if (!key) throw new Error("STAMPMITRA_API_KEY missing");

  const isLive = key.startsWith("sk_live_");
  const isTest = key.startsWith("sk_test_");
  if (!isLive && !isTest) throw new Error("Unknown StampMitra key prefix");

  if (appEnv === "production" && !isLive) {
    throw new Error("production app is using a sandbox key");
  }
  if (appEnv !== "production" && isLive) {
    throw new Error("non-production app is holding a live key");
  }
  return key;
}

यह guard मामूली दिखता है, पर यह उस रात की सबसे आम गलती रोक देता है जब कोई .env फ़ाइल गलत server पर कॉपी हो जाती है। ध्यान रहे कि error message में key का कोई हिस्सा print न करें।

Scopes क्या हैं और key को कितनी ताकत दें?

हर API key के साथ scopes की एक list जुड़ी होती है। docs इन्हें OAuth-style scopes कहते हैं। हर endpoint को एक खास scope चाहिए। अगर key वैध है पर scope नहीं है, तो आपको 403 मिलता है, जबकि key ही गलत या गायब हो तो 401 आता है। यह फर्क troubleshooting में बहुत काम आता है।

Repo में दिखने वाले scopes

पूरी सूची और हर endpoint का request/response आपको verification API docs और e-Stamp API docs में मिलेगा।

Least privilege: सिर्फ उतना जितना चाहिए

मान लीजिए आपका एक microservice सिर्फ PAN verify करता है। उसे सिर्फ verification.pan.read वाली key दीजिए। अगर वही key e-Stamp का orders.create और payments.write भी रखती है, तो चोरी होने की स्थिति में कोई उसे आपके wallet से e-Stamp order बनाने में लगा सकता है। एक service, एक key, कम से कम scopes। यह नियम नीरस लगता है, पर नुकसान को छोटे दायरे में रखता है।

अलग काम, अलग key

एक छोटी सी आदत बहुत काम की है: हर service या हर टीम के लिए अलग key बनाइए और उसे साफ नाम दीजिए, जैसे kyc-onboarding-prod या stamp-orders-worker। इससे दो फ़ायदे होते हैं। किसी एक key को revoke करना पड़े तो बाकी सेवाएँ चलती रहती हैं, और नाम देखकर आप तुरंत समझ पाते हैं कि कौन सी key किस काम की है। dashboard के API keys पेज से आप नई key बना सकते हैं, scope तय कर सकते हैं और उसे rotate कर सकते हैं।

API key IP allowlist क्या है और यह कब ज़रूरी है?

IP allowlist एक सीधी सुरक्षा परत है: key सिर्फ उन्हीं IP पतों से चलेगी जिन्हें आपने पहले से बताया है। StampMitra में इसका सार यह है कि आप किसी भी key को IP या CIDR की सूची से बाँध सकते हैं, और PAN व RC जैसे संवेदनशील scopes के लिए यह सूची default रूप से माँगी जाती है। pricing page पर भी "Per-key IP allowlisting and scopes" को Developer Suite की खूबियों में गिना गया है।

इसका फ़ायदा कैसे होता है

एक उदाहरण सोचिए। आपके एक कर्मचारी ने गलती से production key किसी public GitHub repo में डाल दी। बिना allowlist के, जिसने भी वह key देखी वह दुनिया में कहीं से भी आपके खर्चे पर PAN verification चला सकता है। allowlist लगी हो तो उसकी request उस key के लिए अनुमत IP से नहीं आएगी, इसलिए रोक दी जाएगी। यानी key का रिसाव होने पर भी आपके पास उसे revoke करने का वक्त बचता है।

IP और CIDR का सीधा मतलब

IP एक अकेला पता है, जैसे 203.0.113.10 (यह documentation के लिए रखा गया नमूना पता है)। CIDR एक पूरा दायरा बताता है, जैसे 203.0.113.0/28, जिसमें उस block के कई पते आते हैं। अगर आपके server का outbound IP तय और स्थिर है, तो एक अकेला IP काफ़ी है। अगर आपके पास कुछ servers का pool है, तो दायरा बेहतर रहता है।

कब ज़रूरी, कब नहीं

• ज़रूरी: production key, खासकर PAN, RC जैसे संवेदनशील scopes वाली।
• अच्छा रहेगा: sandbox key भी, अगर आपकी टीम बड़ी है और आप चाहते हैं कि कोई भी बाहर से आपके sandbox quota को न खाए।
• मुश्किल: ऐसे environment जहाँ outbound IP बदलता रहता है, जैसे कुछ serverless platforms। वहाँ पहले एक static egress IP का इंतज़ाम कीजिए, फिर allowlist लगाइए।

ध्यान दीजिए कि docs में यह साफ नहीं लिखा कि allowlist से बाहर के IP पर ठीक कौन सा status code या error message आता है। इसलिए इसे अपने staging में आज़माकर देखें और requestId के साथ पूरा response log करें।

IP allowlist लगाते वक्त की आम गलतियाँ कौन सी हैं?

allowlist सुरक्षा बढ़ाती है, पर launch वाले दिन सबसे ज़्यादा "यह तो चल नहीं रहा" वाली परेशानी भी यहीं से आती है। ये सबसे आम फिसलन हैं।

गलती 1: laptop का IP डालना, server का नहीं

डेवलपर अपने घर या दफ़्तर का IP देखकर allowlist में डाल देता है, curl से टेस्ट करता है, सब चलता है। फिर code cloud server पर जाता है और वहाँ का outbound IP अलग निकलता है। हमेशा उस machine से curl https://ifconfig.me जैसी कोई call चलाकर देखिए जहाँ से असली traffic जाएगा। आपका server जो IP दिखाता है वही allowlist में जाना चाहिए।

गलती 2: अलग-अलग outbound IP

Kubernetes या auto-scaling वाले setup में हर नया pod अलग IP से बाहर निकल सकता है। सही तरीका यह है कि सारा outbound traffic एक NAT gateway या egress proxy से निकले जिसका static IP हो, और वही IP allowlist में रहे।

गलती 3: IPv4 और IPv6 का घालमेल

कुछ environments बाहर जाते समय IPv6 चुन लेते हैं, जबकि आपने सिर्फ IPv4 पता डाला होता है। जो पता आपका server असल में दिखाता है, वही डालिए, और ज़रूरत हो तो दोनों।

गलती 4: CIDR का दायरा बहुत बड़ा

सुविधा के चक्कर में कोई 0.0.0.0/0 जैसा दायरा डाल देता है, यानी सारी दुनिया। इससे allowlist का मकसद ही खत्म हो जाता है। अगर आपको यह करना पड़ रहा है तो समझिए कि egress IP का इंतज़ाम अभी बाकी है।

गलती 5: नया server जोड़ा, allowlist भूल गए

आज आपके पास एक server है, अगले महीने आप दूसरा region जोड़ते हैं। नई जगह से पहली call 4xx में गिरती है और आप code खँगालते रह जाते हैं। इसे अपनी deployment checklist में लिख दीजिए: "नया outbound IP आया तो key की allowlist अपडेट करो।"

गलती 6: पुराना IP हटाना भूल जाना

server बदलने के बाद पुराने IP को सूची में छोड़ देना भी जोखिम है, क्योंकि वह IP कल किसी और को मिल सकता है। हर तिमाही सूची की सफ़ाई करें।

हमारा सुझाव यह है कि allowlist को किसी रविवार रात की जगह किसी कामकाजी दिन की सुबह बदलिए, जब आपकी टीम मौजूद हो और support जवाब दे सके।

Sandbox में क्या-क्या टेस्ट करें, और क्या नहीं?

sandbox में आपको "सफल रास्ता" और "गलत रास्ता" दोनों आज़माने हैं। नीचे का क्रम आपको production से पहले अच्छा आत्मविश्वास देगा।

ज़रूर टेस्ट करें

1. सफल call और response parsing। referenceId, valid, panStatus जैसे fields को अपने model में सही map कीजिए। docs बताते हैं कि referenceId का format SMV-YYYYMMDD-XXXXXXX है और यह नकारात्मक नतीजे में भी हमेशा मौजूद रहता है।
2. गलत format का input। pan को ABCDE1234F ढाँचे में न भेजें तो 400 आना चाहिए, और message कुछ ऐसा होगा: "pan must match the format ABCDE1234F"। यह call सत्यापन के लिए जाने से पहले ही रुक जाती है।
3. गलत key। जानबूझकर key में एक अक्षर बदलकर भेजें। आपको 401 और UNAUTHORIZED कोड दिखना चाहिए।
4. कम scope वाली key। एक ऐसी sandbox key बनाइए (scopes आप key बनाते समय चुन सकते हैं) जिसमें verification.gstin.read न हो, फिर GSTIN call कीजिए। 403 और FORBIDDEN दिखेगा। इससे आपके code की 403 handling जाँची जाती है।
5. 429 का व्यवहार। अपने client में retry और backoff लगाइए, और देखिए कि बार-बार 429 पर वह थम जाता है या नहीं।
6. नेटवर्क टूटना। timeout सेट कीजिए, और 502 जैसे upstream त्रुटि के संदेश को ग्राहक को सीधे मत दिखाइए।

sandbox में मत मानिए कि सब कुछ असली जैसा है

sandbox आपके साथ sandbox data पर चलता है, और signup पेज साफ कहता है कि टेस्ट के लिए असली दस्तावेज़ की ज़रूरत नहीं। इसलिए नतीजे की सामग्री (जैसे नाम, पता) असली व्यक्ति से मेल नहीं खा सकती। इसके आधार पर अपने business rules, जैसे "नाम मेल नहीं खाया तो reject", का अंतिम निर्णय मत लीजिए। उन्हें production के नज़दीकी, पर अपने ही data पर परखिए।

sandbox की सीमा को लेकर सतर्क रहें

home page पर लिखा है कि sandbox की एक अपनी call सीमा है और उसे पार करने पर आपको साफ 429 मिलता है, silent failure नहीं। सटीक संख्या हम यहाँ नहीं देते क्योंकि वह बदल सकती है। अपनी वर्तमान स्थिति dashboard में देखिए, और अपने CI में sandbox calls को सोच-समझकर खर्च कीजिए। हर commit पर पूरा suite चलाकर sandbox भर देना अच्छी आदत नहीं है। अपने tests में असली API की जगह एक mock रखिए, और हफ्ते में एक बार या release से पहले ही असली sandbox पर "smoke test" चलाइए।

यही बात API errors को संभालने की गाइड में और विस्तार से है।

Production access के लिए आवेदन कैसे करें?

production key सीधे signup से नहीं मिलती। docs कहते हैं कि production keys के लिए KYC-approved organization चाहिए, और pricing page कहता है कि आप dashboard से production access के लिए apply करते हैं, approval मिलने पर production API key बना सकते हैं। यानी रास्ता ऐसा है:

1. Sandbox में काम पूरा करें। signup के बाद आपको sk_test_ key मिल चुकी है।
2. Dashboard में production access के हिस्से पर जाएँ और आवेदन भरें।
3. बताइए कि आप किन products के लिए आवेदन कर रहे हैं। production access हर product के हिसाब से दी जाती है, यानी PAN verification की अनुमति मिलना और e-Stamp की अनुमति मिलना अलग बातें हैं। अगर किसी product की अनुमति नहीं है और आप उसे call करते हैं, तो docs में वर्णित 400 "Validation error / not entitled" जैसी स्थिति बन सकती है।
4. Approval का इंतज़ार करें। आप इस बीच sandbox पर काम जारी रख सकते हैं।
5. Approval के बाद production key बनाइए, उसके scopes चुनिए और IP allowlist लगाइए।
6. Wallet में balance जोड़िए, क्योंकि production में हर सफल call का भुगतान वहीं से होता है।

आवेदन में क्या साफ रखें

आपका use case एक वाक्य में समझ आना चाहिए। उदाहरण के लिए: "हम अपने गृह-ऋण आवेदन में ग्राहक का PAN जाँचते हैं ताकि नाम और स्थिति मिल सके।" जिस वेबसाइट या app से calls जाएँगी उसका पता, और जहाँ तक हो सके अपने ग्राहक के लिए दिखने वाली privacy जानकारी भी तैयार रखें। यह सब आपके onboarding को तेज़ करता है। इसकी विस्तृत शर्तें developer onboarding verification policy में हैं, और उपयोग की सीमाएँ API acceptable use policy में।

क्या production की मंज़ूरी की कोई गारंटी है?

नहीं। StampMitra एक private LegalTech platform है जिसे Bani Global Industries LLP चलाती है, यह कोई सरकारी संस्था नहीं है, और approval की समय-सीमा या नतीजे का कोई वादा नहीं किया जा सकता। इसलिए launch की तारीख approval से पहले पक्की मत कीजिए। अपने ग्राहक से जो वादा करें, वह approval के बाद करें।

Key को सुरक्षित कैसे रखें और rotate या revoke कब करें?

Key आपके organization की पहचान है। उसे वैसे ही संभालिए जैसे बैंक का PIN।

सिर्फ एक बार दिखती है

Quickstart और home page दोनों कहते हैं कि raw key सिर्फ एक बार दिखाई जाती है। उसी वक्त उसे अपने secret manager या अपने hosting platform के environment secrets में रख लीजिए। बाद में उसे वापस देखना संभव नहीं है, इसलिए खो जाए तो नई key बनानी होगी।

कहाँ रखें और कहाँ नहीं

आख़िरी बिंदु बहुत मायने रखता है। हमारी सलाह है कि API key सिर्फ server-side कोड में रहे। अगर आपका app mobile या browser में चलता है, तो call अपने backend से कीजिए और backend में key रखिए।

Rotate और revoke

Rotate का मतलब है नई key बनाकर पुरानी को बंद कर देना। यह नियमित सफ़ाई है। Revoke तुरंत की कार्रवाई है, जब key के रिसाव का शक हो। home page के अनुसार आप dashboard से key rotate और scope कर सकते हैं। एक तरीका जो आराम से चलता है:

1. नई key बनाइए, उसके scopes पुरानी जैसे रखिए।
2. नई key को अपने secret store में डालिए और deploy कीजिए।
3. देखिए कि सब कुछ नई key से चल रहा है।
4. तब पुरानी key को revoke कीजिए।

अगर रिसाव का शक है तो क्रम उलट दीजिए: पहले पुरानी key revoke कीजिए, फिर नई जारी कीजिए। थोड़ी देर का व्यवधान चोरी हुई key के चलने से बेहतर है।

जब key सार्वजनिक हो जाए

अगर key कभी GitHub, चैट या किसी screenshot में दिख गई, तो उसे तुरंत revoke कीजिए, चाहे वह सिर्फ कुछ मिनट दिखी हो। फिर अपने wallet के transaction और usage को देखिए कि कहीं अनजानी calls तो नहीं हुईं। अगर कुछ गड़बड़ लगे तो StampMitra support को [email protected] पर requestId के साथ लिखिए। इसके लिए StampMitra की API security policy भी देखिए।

Node.js और Python में environment-aware client कैसे लिखें?

अब वही बात code में। लक्ष्य यह है कि आपका client key से environment पहचाने, सही header भेजे, और errors को साफ तरीके से बाहर लाए।

Node.js (fetch)

// stampmitra-client.js
const BASE_URL = "https://api-b2b.stampmitra.in";

export async function verifyPan({ pan, name }) {
  const key = process.env.STAMPMITRA_API_KEY;
  const res = await fetch(`${BASE_URL}/v1/verify/pan`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${key}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ pan, name }),
  });

  const body = await res.json();
  if (!res.ok) {
    const { code, message, requestId } = body.error || {};
    const err = new Error(message || "StampMitra request failed");
    err.status = res.status;
    err.code = code;
    err.requestId = requestId;
    throw err;
  }
  return body; // body.referenceId, body.valid, body.panStatus ...
}

Python (requests)

# stampmitra_client.py
import os
import requests

BASE_URL = "https://api-b2b.stampmitra.in"

class StampMitraError(Exception):
    def __init__(self, status, code, message, request_id):
        super().__init__(message)
        self.status = status
        self.code = code
        self.request_id = request_id

def verify_pan(pan, name=None):
    key = os.environ["STAMPMITRA_API_KEY"]
    payload = {"pan": pan}
    if name:
        payload["name"] = name

    res = requests.post(
        f"{BASE_URL}/v1/verify/pan",
        headers={"Authorization": f"Bearer {key}"},
        json=payload,
        timeout=15,
    )
    body = res.json()
    if not res.ok:
        err = body.get("error", {})
        raise StampMitraError(
            res.status_code, err.get("code"), err.get("message"), err.get("requestId")
        )
    return body

इस code में क्या सोचकर लिखा गया है

पहली बात, key हमेशा environment variable से आती है। दूसरी, error का रूप वही है जो docs बताते हैं: error.code, error.message और error.requestId। तीसरी, requestId को exception के साथ आगे भेजा जाता है ताकि आपका log उसे पकड़ सके। चौथी, Python में एक timeout है। बिना timeout के request अटकी रहे तो आपका worker अटक जाता है।

एक बात जो इन नमूनों में जानबूझकर नहीं है, वह है retry। 429 पर retry करना हो तो बढ़ते अंतराल के साथ और सीमित बार करें। और 402 पर कभी retry न करें, क्योंकि वह wallet balance की कमी है, अस्थायी नेटवर्क गड़बड़ नहीं। PAN के पूरे flow के लिए हमारी PAN verification API गाइड पढ़ें।

एक कहानी: रेवा क्रेडिट का पहला live दिन

यह एक काल्पनिक उदाहरण है, ताकि checklist ज़मीन पर उतरकर दिखे। "रेवा क्रेडिट" एक छोटी, काल्पनिक NBFC-स्टार्टअप है जो ऑनलाइन छोटे कर्ज़ देती है। उसकी टीम में तीन बैकएंड डेवलपर हैं, और वे ग्राहक का PAN जाँचकर onboarding पूरा करना चाहते हैं।

तीन हफ्ते पहले

टीम ने signup करके sk_test_ key ली, और PAN verification का पूरा flow sandbox में बनाया। उन्होंने verification.pan.read scope वाली अलग sandbox key बनाई, ताकि उनकी बाकी जाँचें किसी और key से हों। उसी दिन उन्होंने production access की application भेज दी, क्योंकि approval में वक्त लग सकता है।

launch से दो दिन पहले

Approval आ गया। टीम ने production key बनाई और उसमें सिर्फ verification.pan.read रखा। फिर बारी आई allowlist की। एक डेवलपर ने अपने दफ़्तर का IP डालकर curl टेस्ट किया, सब चला। मगर टीम की checklist में लिखा था "server से IP जाँचो"। उन्होंने staging server पर curl https://ifconfig.me चलाया और देखा कि पता अलग है। अगर वे दफ़्तर के IP पर रुक जाते, तो launch की सुबह हर call फेल होती।

launch वाली सुबह

उन्होंने secret manager में sk_live_ key रखी और startup guard चलाया। guard ने एक गलती पकड़ी: staging की deployment में गलती से production key का नाम इस्तेमाल हो रहा था। ठीक किया गया। फिर उन्होंने अपने ही PAN पर एक असली call की। response में referenceId आया और log में वह requestId के साथ दर्ज हुआ।

launch के बाद

पहले दिन एक दोपहर wallet balance कम हुआ और alert बजा। टीम ने Billing से पैसा जोड़ दिया और किसी ग्राहक ने 402 नहीं देखा। अगर alert न होता, तो ग्राहकों को "कुछ गड़बड़ हुई" दिखता। हफ्ते भर बाद उन्होंने sandbox key को production code की कॉन्फ़िग से पूरी तरह हटाया।

इस कहानी की सीख यह नहीं कि कुछ भी गलत नहीं होता, बल्कि यह कि हर गलती की कीमत तभी छोटी रहती है जब वह launch से पहले पकड़ ली जाए। इसी वजह से लेख की शुरुआत में checklist रखी गई थी।

401, 402, 403, 429 और 400: errors का मतलब और इलाज

StampMitra का हर error एक ही रूप में आता है:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key.",
    "requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
  }
}

नीचे की table docs में दिए उदाहरणों पर आधारित है। जहाँ docs में कोई बात नहीं है, वहाँ हमने साफ लिखा है।

401 और 403 का फर्क पकड़िए

401 का मतलब है "आप कौन हैं, यह समझ नहीं आया"। 403 का मतलब है "आप कौन हैं, यह पता है, पर यह काम आपके लिए नहीं"। 401 पर key और header जाँचिए, 403 पर scopes।

अगर allowlist से रुके तो

इस बारे में docs में कोई अलग उदाहरण नहीं है। इसलिए अगर sandbox में call चली और production में उसी तरह की call नहीं चली, तो सबसे पहले यह जाँचिए कि आपका server उसी IP से निकल रहा है जो allowlist में है। फिर requestId और response का पूरा body लेकर support को भेजिए।

429 पर क्या करें

docs का नमूना संदेश कहता है "Rate limit exceeded: 60 requests per 60 seconds for this endpoint।" यह उदाहरण है, और असली सीमा हर endpoint के हिसाब से server तय करता है। इसलिए अपने code में कोई स्थिर संख्या मत लिख लीजिए। सीमा पार होने पर थोड़ा रुकिए, backoff के साथ दोबारा कोशिश कीजिए, और अपनी calls को queue में लगाइए। batch में काम करने वाली jobs के लिए यह खास तौर पर ज़रूरी है।

402 पर क्या करें

यह सबसे ज़्यादा नुकसान वाली गलती है, क्योंकि इसका असर सीधे आपके ग्राहक पर पड़ता है। 402 का इलाज retry नहीं, पैसा जोड़ना है। wallet का alert लगाइए, और ग्राहक को एक विनम्र संदेश दिखाइए जैसे "अभी हम आपकी जाँच पूरी नहीं कर पा रहे, कुछ देर बाद कोशिश करें" और अंदर से अपनी टीम को सूचना भेजिए।

इन सब के लिए और विस्तार से API errors और handling गाइड देखिए।

कब कौन सी key चलानी है? एक फ़ैसला-गाइड

कई बार सवाल "key क्या है" का नहीं, बल्कि "इस वक्त कौन सी key सही है" का होता है। नीचे का छोटा फ़ैसला-वृक्ष काम आएगा।

कब production key मत लीजिए

अगर आप अभी सिर्फ यह देख रहे हैं कि API आपके काम की है या नहीं, तो production की ज़रूरत नहीं है। sandbox आपके लिए काफ़ी है। production तभी लीजिए जब आपके पास असली ग्राहक हों, और आप अपने use case का उद्देश्य साफ बता सकें।

कब sandbox पर्याप्त नहीं है

जब आपको असली व्यक्ति या कंपनी का असली नतीजा चाहिए, जैसे किसी ग्राहक का नाम मिलान, तब sandbox का data आपके काम नहीं आएगा। उस स्थिति में production ही रास्ता है।

ग्राहक का data और key: privacy के लिहाज़ से क्या सोचें?

PAN, GSTIN या vehicle RC जैसी जानकारी निजी या संवेदनशील हो सकती है। इसलिए key की सुरक्षा सिर्फ पैसे की बात नहीं, ग्राहक के data की भी बात है। यह सेक्शन सामान्य जानकारी के तौर पर है और कानूनी सलाह नहीं है। अपने मामले में किसी योग्य वकील या compliance विशेषज्ञ से राय लीजिए।

सहमति और उद्देश्य

भारत में डिजिटल व्यक्तिगत डेटा संरक्षण कानून (Digital Personal Data Protection Act, 2023) व्यक्तिगत data के इस्तेमाल पर लागू होता है। इसकी हर धारा का हमने यहाँ विश्लेषण नहीं किया है। व्यावहारिक नियम सीधा है: ग्राहक से साफ तौर पर पूछिए कि आप उसके PAN या दूसरे दस्तावेज़ का क्या करेंगे, और उसी काम के लिए इस्तेमाल कीजिए। सटीक कानूनी ज़रूरतों के लिए आधिकारिक पाठ और अपने कानूनी सलाहकार को देखिए।

कम से कम जमा करें

API के response में कई fields आते हैं, जैसे fatherName या aadhaarSeedingStatus। अगर आपके काम को सिर्फ valid और nameMatchResult चाहिए, तो बाकी को अपने database में रखने की ज़रूरत नहीं है। जो आपके पास नहीं है, वह लीक भी नहीं हो सकता।

Log में क्या न जाए

debug के वक्त पूरी request और response log करने का मन होता है, पर वहाँ ग्राहक का PAN और आपकी API key दोनों आ सकते हैं। log में referenceId और requestId रखिए, key कभी नहीं, और संवेदनशील fields को ढककर या हटाकर रखिए। StampMitra की developer privacy policy और data processing addendum में बताया गया है कि प्लेटफ़ॉर्म इस data को कैसे संभालता है।

Sandbox में असली data मत डालिए

sandbox इसलिए है कि आप असली दस्तावेज़ के बिना टेस्ट कर सकें। अपने असली ग्राहकों के PAN या GSTIN को sandbox में डालकर देखने की ज़रूरत नहीं। नमूना values, जैसे docs में दिया ABCDE1234F, यही काम करती हैं।

StampMitra आपकी कैसे मदद करता है

StampMitra एक private LegalTech platform है, जिसे Bani Global Industries LLP (LLPIN ACI-6373) चलाती है। हम कोई सरकारी संस्था या law firm नहीं हैं। हमारा काम है भारत में identity verification और e-Stamp के काम को एक API के पीछे सरल बनाना, ताकि आपको अलग-अलग स्रोतों से जूझना न पड़े।

आज के हिसाब से, यानी इस लेख की तारीख (16 अक्टूबर 2026) तक, ये चीज़ें docs में उपलब्ध हैं:

• Free sandbox। signup पर तुरंत sk_test_ key, बिना card और बिना manual approval के। sandbox calls metered और logged हैं, पर आपका wallet नहीं घटातीं।
• Environment-scoped keys। sk_test_ और sk_live_, दोनों के लिए एक जैसे header (Authorization: Bearer या x-api-key), और environment का फ़ैसला server पर, key के आधार पर।
• Scopes। हर endpoint का अपना scope, ताकि आप key को ज़रूरत भर की ताकत दें।
• Per-key IP allowlisting। IP या CIDR सूची, और PAN व RC जैसे संवेदनशील scopes के लिए default रूप से ज़रूरी।
• एक जैसा error का रूप। हर error में code, message और requestId, जिससे troubleshooting आसान होती है।
• Verification और e-Stamp APIs। PAN, GSTIN, vehicle RC, Voter ID, Driving Licence, Passport, CIN, Udyam और bank account जैसी verification के साथ e-Stamp के catalog, duty, parties, orders, payments और documents के endpoints। विस्तार products पेज पर है।
• Per-call pricing। production में सफल call का भुगतान API credit wallet से होता है। उदाहरण के लिए PAN verification की कीमत ₹5 प्रति call है, और बाकी products की कीमतें pricing पेज पर हैं।
• Tooling। quickstart, SDKs, Postman collection, webhooks, MCP server और AI के साथ build करने के prompts।

जो StampMitra नहीं करता

हम किसी नतीजे या मंज़ूरी की गारंटी नहीं देते। production access की मंज़ूरी समीक्षा पर निर्भर है। हम कानूनी सलाह भी नहीं देते। जहाँ इस लेख में कानूनी मुद्दे आए हैं, वे सामान्य जानकारी हैं।

आगे की योजनाएँ

हमारी योजना है कि docs और guides का दायरा बढ़ता रहे, और ज़्यादा विषयों पर हिंदी में सामग्री आए। ये योजनाएँ हैं, वादे नहीं, और इनकी कोई तारीख हम तय नहीं कर रहे। जो आज उपलब्ध है, वही ऊपर की सूची में है।

मदद के लिए

अगर आप अटक जाएँ, तो support पेज देखिए या [email protected] पर लिखिए, और अपने साथ requestId ज़रूर भेजिए। शुरुआत के लिए मुफ़्त sandbox key लीजिए। e-Stamp का पूरा क्रम समझना हो तो e-Stamp API order flow की गाइड पढ़िए, और कंपनी की जाँच के लिए GSTIN, CIN और Udyam वाली गाइड।

API reference एक नज़र में

{
  "referenceId": "SMV-20260927-8F42K7",
  "pan": "ABCDE1234F",
  "type": "Individual",
  "valid": true,
  "registeredName": "RAHUL KUMAR",
  "fatherName": "SURESH KUMAR",
  "panStatus": "VALID",
  "panStatusCode": "E",
  "panStatusDescription": "Existing and valid PAN",
  "nameMatchResult": "MATCH",
  "nameMatchScore": "100",
  "aadhaarSeedingStatus": "y",
  "aadhaarSeedingStatusDescription": "Aadhaar linked",
  "lastUpdatedAt": "2023-04-01",
  "message": "PAN is Valid"
}

अक्सर पूछे जाने वाले सवाल