Sandbox बनाम production: क्या टेस्ट हो सकता है और क्या नहीं

मुख्य बातें

• sandbox सैंपल डेटा लौटाता है और असली रिकॉर्ड कभी verify नहीं करता। जवाब के नाम बनावटी हैं। sandbox के नतीजे को किसी असली व्यक्ति या कारोबार का सबूत मत मानिए।
• चार जादुई इनपुट पहले से तय नतीजा देते हैं: PAN, GSTIN, CIN और bank account, हर एक की एक वैल्यू valid लौटाती है और एक not valid। बाक़ी हर इनपुट का नतीजा स्थिर पर मनमाना होता है, मोटे तौर पर तीन में से दो valid, और एक ही इनपुट पर हर बार वही जवाब।
• sandbox इन्हें साबित करने के लिए काफ़ी है: authentication, scopes, request की बनावट, इनपुट validation, जवाब पढ़ना, 400, 401, 403 और 429 की हैंडलिंग, referenceId का रूप, और यह कि wallet नहीं कटता।
• sandbox यह साबित नहीं कर सकता: डेटा की सटीकता, असली नामों पर name-match का बर्ताव, डेटा की ताज़गी, असली दुनिया में स्थितियों की विविधता, upstream की देरी या आउटेज, production की rate limits और असली लागत।
• live जाना स्विच नहीं, आवेदन है: नौ चरणों का फ़ॉर्म, अपने आप होने वाली जाँचें, दस्तावेज़ों के लिए 24 घंटे वाली अस्थायी मंज़ूरी, फिर एक बार दिखने वाली live key, और live calls से पहले wallet रिचार्ज।
• wallet रिचार्ज पर 18% GST लगता है। भुगतान की पुष्टि होते ही GST इनवॉइस ईमेल होता है और billing पेज पर सहेजा जाता है।
• production में एक छोटा smoke test रखिए, अपनी मिल्कियत वाली पहचानों के साथ, go-live के तुरंत बाद। बाक़ी टेस्ट sandbox में रखिए।

दो हफ़्ते की कहानी: पहली call से live ट्रैफ़िक तक

मान लीजिए एक छोटी ट्रेडिंग कंपनी की टीम वेंडर ऑनबोर्डिंग बना रही है। उन्हें PAN, GSTIN और bank account की जाँचें चाहिए। देखिए वे काम को दोनों माहौलों में कैसे बाँट सकते हैं।

दिन 1 से 2। एक डेवलपर साइन अप करके sandbox key लेता है और SNDBX0000A से पहली call करता है। दर्ज सैंपल जवाबों को fixture की तरह सहेजता है और parser उन्हीं के सामने लिखता है। PAN, GSTIN और bank account के क्लाइंट अलग छोटे मॉड्यूल हैं, जिनके unit tests valid, invalid, अनजानी स्थिति और हर दर्ज एरर बॉडी को कवर करते हैं।

दिन 3 से 5। ऑनबोर्डिंग का प्रवाह तीनों क्लाइंट को नक़ली (stub) रखकर बनता है। फ़ैसले का तर्क, यानी कौन-से नतीजे पास और कौन-से समीक्षा में, सिर्फ़ fixture पर परखा जाता है। नेटवर्क call शून्य। sandbox की सीमाएँ अछूती।

दिन 6। sandbox का छोटा integration सूट: हर प्रोडक्ट के लिए जादुई वैल्यू से एक सकारात्मक और एक नकारात्मक, साथ में एक ग़लत वैल्यू, एक ग़लत key और एक ग़लत scope। कुल मिलाकर क़रीब दर्जन भर calls। सूट sk_test_ key के बिना चलने से मना कर देता है।

दिन 7। कंपनी का फ़ाइनेंस प्रमुख production आवेदन शुरू करता है, क्योंकि उसमें कंपनी का PAN, GSTIN और CIN, एक हस्ताक्षरकर्ता, डोमेन और सर्वर IP, और प्रोडक्ट का चुनाव चाहिए। टीम PAN और GSTIN को कम जोखिम वाले प्रोडक्ट की तरह चुनती है और bank account को वह प्रोडक्ट जिसकी एक अतिरिक्त जाँच होगी। वे उपयोग को ठोस शब्दों में लिखते हैं: उपभोक्ता नहीं, वेंडर; अपनी तय की हुई volume band और रिटेंशन अवधि के साथ।

दिन 8 से 9। अपने आप होने वाली जाँचें पूरी होकर आवेदन अस्थायी मंज़ूरी पर पहुँचता है। दस्तावेज़ों के लिए 24 घंटे की घड़ी शुरू होती है। फ़ाइनेंस प्रमुख निगमन प्रमाणपत्र, GST प्रमाणपत्र और authorisation letter अपलोड करता है, और चूँकि हस्ताक्षरकर्ता निदेशक है, इसलिए बोर्ड प्रस्ताव नहीं लगता। live key जारी होकर एक बार दिखती है। वह secret manager में जाती है और कहीं नहीं।

दिन 10। wallet रिचार्ज होता है। GST इनवॉइस ईमेल से आता है और billing पेज पर दिखता है, जिसे फ़ाइनेंस फ़ाइल कर लेता है। टीम live key के साथ पहले staging पर deploy करती है, जो environment guard की वजह से स्टार्टअप पर ही गिर जाता है। यही guard का काम है: staging को sk_test_ इस्तेमाल करना चाहिए। वे secret की मैपिंग ठीक करके फिर deploy करते हैं।

दिन 11। production में वे कंपनी के अपने PAN और GSTIN से smoke test चलाते हैं। लौटे नाम और स्थितियाँ वही हैं जो फ़ाइनेंस ने सोचा था। एक जवाब में ऐसी स्थिति आती है जो fixtures में नहीं थी, और टीम उसे समीक्षा के रास्ते में जोड़ देती है। ठीक ऐसी ही चौंकाने वाली बात sandbox पैदा नहीं कर सकता।

दिन 12 से 14। दस्तावेज़ मंज़ूर होते हैं, अस्थायी सीमाएँ हट जाती हैं, और bank account प्रोडक्ट अपनी अतिरिक्त समीक्षा के बाद खुल जाता है। वे अपनी निगरानी में कम-बैलेंस वाला अलर्ट लगाते हैं और usage summary के एक दिन को अपने काउंटरों से मिलाते हैं। असली वेंडर आना शुरू हो जाते हैं।

उस पूरी समयरेखा में दर्जन भर से ज़्यादा sandbox calls नहीं लगीं, और असली ट्रैफ़िक से पहले live calls सिर्फ़ smoke test की थीं। यही अनुपात असली बात है।

sandbox में असल में है क्या

माहौल key से तय होता है। sk_test_ से शुरू होने वाली key sandbox में चलती है और sk_live_ से शुरू होने वाली production में, बिना किसी flag के और बिना अलग host के: दोनों https://api-b2b.stampmitra.in इस्तेमाल करती हैं। sandbox में calls गिनी और लॉग की जाती हैं ताकि आप देख सकें, पर वे आपके wallet से कभी नहीं कटतीं।

sandbox के पीछे का responder जान-बूझकर सीधा-सादा है। कुछ "जादुई" इनपुट के लिए वह तय नतीजा देता है। बाक़ी हर इनपुट के लिए वह इनपुट से ही एक स्थिर पर मनमाना नतीजा निकालता है, यानी एक ही वैल्यू पर हमेशा वही जवाब, और मोटे तौर पर तीन में से दो इनपुट valid लौटते हैं। किसी रजिस्ट्री में कुछ नहीं खोजा जाता। sandbox के जवाब का हर नाम बनावटी है, इसलिए PAN पर जो "registered name" मिलता है वह किसी का नाम नहीं है।

इसके दो नतीजे टेस्ट के तरीक़े पर असर डालते हैं। पहला, sandbox के नतीजे दोहराए जा सकते हैं, जो अच्छी बात है। आप बिना अस्थिर upstream के ऑटोमेटेड टेस्ट में उन पर assert कर सकते हैं। दूसरा, वे मनमाने हैं, जो सीमा है: अगर आपका टेस्ट कोई यूँ ही दिखने वाला PAN चुनकर उससे invalid की उम्मीद करे, तो उसके invalid निकलने की संभावना तीन में एक है और न निकलने की दो। जिस टेस्ट को कोई ख़ास नतीजा चाहिए, वह जादुई वैल्यू इस्तेमाल करे।

sandbox में e-Stamp

e-Stamp वह अकेला product है जहाँ sandbox सिर्फ़ एक lookup की नहीं, पूरी प्रक्रिया की नक़ल करता है। sandbox key से order बनाकर उसे certificate तक पहुँचते देखा जा सकता है, बिना किसी समीक्षा, भुगतान या जारी करने वाली सेवा के पीछे होने के।

इसे order worker, status mapping, पैसे का handling, certificate download और webhook handler बनाने के लिए इस्तेमाल कीजिए। यह जानने के लिए नहीं कि असली order में कितना समय लगता है, क्योंकि production के orders किसी इंसान का इंतज़ार करते हैं। हर status और test input की सूची e-Stamp order पन्ने में है, नक़ली wallets payment पन्ने में, और नमूना certificate document पन्ने में।

दर्ज sandbox टेस्ट वैल्यू

ये वैल्यू sandbox responder से ली गई हैं। जिन टेस्टों को पक्का सकारात्मक या नकारात्मक नतीजा चाहिए, उनमें इन्हें इस्तेमाल कीजिए।

तीन बातें जो आपका समय बचाएँगी।

PAN और GSTIN की वैल्यू format validation पास करती हैं: PAN के लिए पाँच अक्षर, चार अंक, एक अक्षर, और GSTIN के लिए पंद्रह अक्षर की बनावट। पर GSTIN की वैल्यू का चेक कैरेक्टर सही नहीं है, इसलिए अगर आप अपना ऑफ़लाइन चेक कैरेक्टर validation टेस्ट करते हैं, तो key के sk_test_ से शुरू होने पर उसे बंद रखिए।

CIN और bank account की वैल्यू production के format का पालन नहीं करतीं। CIN इक्कीस अक्षर से लंबा है और bank account में वहाँ अक्षर हैं जहाँ production फ़ील्ड को नौ से अठारह अंक चाहिए। API का दर्ज व्यवहार है कि format की गड़बड़ी पर तुरंत 400 आता है, इसलिए अगर इन वैल्यू वाला request आपके खाते पर validation में ठुकरा दिया जाए, तो इसे दर्ज जादुई वैल्यू और format जाँच के बीच की बेमेल मानिए और production कोड में उसका जुगाड़ निकालने की जगह support से पूछिए। आपके अपने कोड को इन स्ट्रिंग के लिए कोई विशेष शाखा नहीं रखनी चाहिए।

और आख़िर में, यह सूची एक तस्वीर है। सच sandbox responder के पास है, इसलिए कोई वैल्यू लिखे अनुसार बर्ताव न करे तो मान लेने की जगह support से पूछिए कि docs ग़लत हैं या sandbox ख़राब।

input से हर नतीजा जाँचें

success और failure की जोड़ी से आगे, हर verification प्रोडक्ट की अपनी test values की तालिका है, जिसकी हर वैल्यू एक दर्ज नतीजा लौटाती है: valid, नहीं मिला, अमान्य format (वही 400), जहाँ प्रोडक्ट नाम लेता है वहाँ नाम का मेल न खाना, निष्क्रिय स्थितियाँ जैसे रद्द GSTIN, नाम हटाई गई कंपनी या समाप्त लाइसेंस, अपस्ट्रीम timeout या outage (502, तुरंत जवाब), rate limit (429) और वॉलेट बैलेंस कम (402)। वैल्यू नकली हैं पर format में सही हैं, जैसे PAN SNDBX0001F, और हर जवाब में वही status code और error code आता है जो live call में आता है। अपना क्लाइंट timeout जाँचने के लिए जवाब रोकना हो तो हैडर X-Sandbox-Delay-Ms (अधिकतम 3000) जोड़ें। तालिका हर प्रोडक्ट पेज पर "Test values" के नीचे है, जैसे PAN verification, GSTIN verification और bank account verification। sandbox call से आपका wallet फिर भी कभी नहीं कटता।

sandbox पास होने से क्या साबित होता है

नीचे की हर चीज़ sandbox में निपटाई जा सकती है और production में smoke test के अलावा दोबारा साबित करनी ज़रूरी नहीं।

rate limit वाली पंक्ति पर एक सावधानी। 429 दो तरह का हो सकता है: हर endpoint की rate limit (दर्ज उदाहरण है किसी endpoint के लिए 60 सेकंड में 60 requests) या sandbox सीमा: प्रति organisation प्रति मिनट 10 या प्रति दिन 200 requests, या सभी अकाउंट मिलाकर एक IP address से प्रति दिन 50। प्रति मिनट की सीमा एक मिनट में हट जाती है, पर दैनिक और IP सीमा आधी रात IST तक नहीं हटतीं। sandbox वाली किस्में production में नहीं दिखतीं। ऐसा retry तर्क मत बनाइए जो मानता हो कि हर 429 कुछ सेकंड रुकने पर हट जाता है; error code (SANDBOX_RATE_LIMIT, SANDBOX_DAILY_LIMIT, SANDBOX_IP_LIMIT) और Retry-After header पढ़िए।

sandbox में webhooks

webhook events API ठीक इसी तरह की टेस्टिंग के लिए है। GET /v1/webhooks/events (scope webhooks.events.read) आपके organisation की delivery attempts सूचीबद्ध करता है, और POST /v1/webhooks/events/:id/replay (scope webhooks.events.replay) किसी ख़ास delivery को उसी payload के साथ उसी रास्ते से दोबारा चलाता है। एक ही event को अपने handler पर तब तक दोहराइए जब तक signature verification, dedup और processing सब ठीक न हो जाएँ। ध्यान दीजिए कि प्रोडक्ट क्या दर्ज करता है: webhook events order और payment के जीवनचक्र पर हैं, जैसे order.created, order.payment_confirmed और order.failed। verification call synchronous है और जवाब उसी response में लौटाती है, इसलिए इंतज़ार करने लायक कोई webhook नहीं। event सूची और signing का ब्योरा webhooks पेज पर है।

sandbox पास होने से क्या साबित नहीं होता

demo से पहले यह हिस्सा अपने हितधारकों को दिखाइए।

इनमें से कोई खाई कमी नहीं है। production smoke test इसीलिए होते हैं।

हर एरर को जान-बूझकर कैसे पैदा करें

जिस एरर हैंडलिंग को कभी चलाया नहीं गया, वह अंदाज़ा है। हर दर्ज विफलता sandbox में जान-बूझकर पैदा की जा सकती है, और launch से पहले ऐसा करना सबसे सस्ता बीमा है। तरकीब यह जानना है कि कौन-सा इनपुट कौन-सा status देता है।

दो मामले तालिका में नहीं हैं क्योंकि उन्हें यूँ ही पैदा नहीं करना चाहिए। 402 के लिए ख़ाली wallet चाहिए, जो sandbox कभी नहीं बनाता क्योंकि वह कभी नहीं काटता, इसलिए अपनी 402 की शाखा को सहेजे हुए fixture से परखिए और wallet पहली बार कम होने पर production में पुष्टि कीजिए। 502 के लिए पहुँच से बाहर upstream सेवा चाहिए, जिसे आप माँगने पर पैदा नहीं कर सकते; उस शाखा को ऐसे क्लाइंट से परखिए जो किसी लोकल सर्वर की ओर इशारा करे जो दर्ज बॉडी के साथ 502 लौटाता हो।

कुछ आदतें इन टेस्टों को ईमानदार बनाती हैं। HTTP status और error.code पर assert कीजिए, और संदेश के शब्दों को संकेत मानिए, अनुबंध नहीं, क्योंकि शब्द सुधारे जा सकते हैं। हमेशा assert कीजिए कि requestId मौजूद है, क्योंकि वही आप support को देंगे। और नकारात्मक-पर-सफल मामले को एरर वाले मामलों से अलग परखिए: valid: false वाला जवाब 200 के साथ आता है और production में पूरी हुई, बिल होने वाली lookup है, इसलिए उसे आपके एरर वाले रास्ते से नहीं सँभालना चाहिए।

टेस्ट की योजना जो दोनों माहौलों का सही इस्तेमाल करे

तीन परतों में सोचिए, और हर जोखिम को उस सबसे सस्ती परत में रखिए जो उसे निपटा सके।

रिकॉर्ड किए fixtures पर unit tests। दर्ज सैंपल जवाब सहेजिए (reference डेटा में हर endpoint का सटीक बॉडी है, एरर बॉडी समेत) और अपना parsing, mapping और फ़ैसले का कोड उन पर चलाइए। इन टेस्टों को नेटवर्क और sandbox की सीमाएँ नहीं चाहिए, और इन्हें हर शाखा कवर करनी चाहिए: valid, invalid, अनजानी स्थिति, छूटा वैकल्पिक फ़ील्ड, हर एरर code। आपके ज़्यादातर assertions यहीं रहते हैं।

sandbox में integration tests। एक छोटा समूह, जादुई वैल्यू के साथ, जो असली HTTP रास्ता साबित करे: authentication, scopes, headers, timeouts, हर उस प्रोडक्ट का सफल और विफल नतीजा जिसे आप बुलाते हैं, और वे एरर जो माँगने पर पैदा हो सकते हैं। इस समूह को छोटा रखिए। sandbox में प्रति organisation प्रति दिन केवल 200 requests मिलती हैं और acceptable use policy sandbox के दुरुपयोग को निषिद्ध मानती है, इसलिए 400 पर लूप चलाने वाला टेस्ट कुछ साबित किए बिना requests जलाता है।

production smoke tests। मुट्ठी भर calls उन पहचानों पर जिन्हें जाँचने का आपको हक़ है (आपका अपना PAN, आपकी कंपनी का GSTIN और CIN, आपके अपने कारोबार का बैंक खाता), go-live के बाद एक बार चलाई गईं और चाहें तो canary की तरह तय समय पर। सिर्फ़ यही calls बताती हैं कि आपके लिए असली डेटा कैसा दिखता है। क्योंकि इनमें असली निजी डेटा है, नतीजों को वैसे ही सँभालिए: लॉग में मास्क कीजिए और टिकट में मत चिपकाइए।

नीचे sandbox वाली परत Python के pytest में है।

# test_sandbox.py  (चलाएँ: pytest -q, environment में sandbox key के साथ)
import os, re, pytest, requests

KEY = os.environ.get("STAMPMITRA_API_KEY", "")
BASE = "https://api-b2b.stampmitra.in/v1/verify"

pytestmark = pytest.mark.skipif(not KEY.startswith("sk_test_"), reason="sandbox key चाहिए")

def post(path, body, key=KEY):
    return requests.post(f"{BASE}/{path}", json=body, timeout=10,
                         headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"})

def test_pan_magic_success():
    r = post("pan", {"pan": "SNDBX0000A", "name": "Test User"})
    assert r.status_code == 200
    body = r.json()
    assert body["valid"] is True
    assert re.match(r"^SMV-\d{8}-[A-Z0-9]+$", body["referenceId"])

def test_pan_magic_failure_is_negative_not_error():
    r = post("pan", {"pan": "SNDBX9999F"})
    assert r.status_code == 200 and r.json()["valid"] is False

def test_malformed_pan_400():
    r = post("pan", {"pan": "12345"})
    assert r.status_code == 400
    assert r.json()["error"]["code"] == "BAD_REQUEST"
    assert r.json()["error"]["requestId"]

def test_wrong_key_is_401():
    assert post("pan", {"pan": "SNDBX0000A"}, key="sk_test_wrong").status_code == 401

और वही बुनियादी call cURL से, जिसे आप टर्मिनल में सबसे पहले चलाकर देखें:

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

फ़ाइल के शुरू का guard देखिए। जो sandbox टेस्ट live key के सामने चल जाए, वह असली पैसा ख़र्च करेगा और, उससे बुरी बात, असली डेटा स्रोतों को call करेगा। prefix sk_test_ न हो तो चलने से मना कर दीजिए।

अपने ऐप्लिकेशन में सीमा पर पहरा

यही prefix की जाँच आपके ऐप्लिकेशन में स्टार्टअप पर उलटी दिशा में भी चाहिए: production को sandbox key के साथ शुरू नहीं होना चाहिए, और staging को live key के साथ नहीं।

// env-guard.mjs
const key = process.env.STAMPMITRA_API_KEY ?? "";
const expected = process.env.APP_ENV === "production" ? "sk_live_" : "sk_test_";
if (!key.startsWith(expected)) {
  console.error(`STAMPMITRA_API_KEY must start with ${expected} when APP_ENV=${process.env.APP_ENV}`);
  process.exit(1);
}

production deployment में छूटी sandbox key इस इलाक़े का सबसे चुपचाप बैठा bug है। calls सफल होती हैं, जवाब सही दिखते हैं, और असली ग्राहक सैंपल डेटा के सामने verify हो जाते हैं। इस जाँच की क़ीमत तीन पंक्तियाँ है।

live जाने पर क्या बदलता है

go-live के दो हिस्से हैं: मंज़ूरी मिलना और wallet में पैसा होना। दोनों असली चरण हैं जिनमें असली इंतज़ार लगता है, और कोई भी स्विच नहीं। आवेदन जल्दी शुरू कीजिए।

आवेदन

production access का आवेदन नौ चरणों का है: आवेदक का प्रकार, हस्ताक्षरकर्ता, कारोबार, आपका उपयोग, compliance, संपर्क और डोमेन, दस्तावेज़, प्रोडक्ट और समीक्षा। फ़ॉर्म वे पहचानें माँगता है जो आपका आवेदक-प्रकार रख सकता है। व्यक्ति या प्रोपराइटरशिप निजी PAN देता है। पार्टनरशिप फ़र्म का PAN। LLP फ़र्म का PAN और रजिस्ट्रेशन नंबर। कंपनी अपना PAN, GSTIN और CIN। PAN का चौथा अक्षर आवेदक के प्रकार से मिलाया जाता है, इसलिए कंपनी के नाम से निजी PAN भरने वाले को जल्दी ही बता दिया जाता है।

"आपका उपयोग" और "compliance" वाले चरण पूछते हैं कि आप verification कैसे इस्तेमाल करेंगे और डेटा का क्या करेंगे: किसे verify करेंगे (अपने ग्राहक, वेंडर, आवेदक, कर्ज़दार), क्यों (ग्राहक ऑनबोर्डिंग, वेंडर ऑनबोर्डिंग, कर्ज़ का फ़ैसला, कर्मचारी जाँच, करार या e-stamp का प्रवाह, धोखाधड़ी की जाँच), महीने की अपेक्षित मात्रा और प्रति मिनट चरम requests, क्या नतीजे सहेजेंगे और कितने समय, क्या आप नियंत्रित संस्था हैं, और क्या आपके पास privacy notice है। कुछ जवाबों पर flag लगते हैं। ऊँची मात्रा की श्रेणियों में ज़्यादा तर्क माँगा जाता है, और सबसे बड़ी श्रेणियाँ कस्टम प्लान की ओर इशारा करती हैं। संपर्क वाला चरण उन लोगों के नाम माँगता है जो घटना की सूचना, इनवॉइस और डेटा अनुरोध पाते हैं, वह राज्य जिससे तय होता है कि GST इनवॉइस पर CGST और SGST दिखे या IGST, और वे डोमेन और सर्वर IP जो API को बुलाएँगे। इस पूरे प्रवाह में कहीं Aadhaar का फ़ील्ड नहीं है।

प्रोडक्ट वाले चरण में आप चुनते हैं कि क्या live चाहिए। PAN, GSTIN, CIN, Udyam और e-Stamp कम जोखिम के माने जाते हैं। Bank account verification और e-Sign ऊँचे जोखिम के चिह्नित हैं और एक छोटी अतिरिक्त जाँच के बाद खुलते हैं।

अपने आप होने वाली जाँचें, फिर अस्थायी key

जमा करने पर आवेदन लॉक हो जाता है और प्लेटफ़ॉर्म आपके दिए ब्योरे पर जाँचें चलाता है: हस्ताक्षरकर्ता का PAN, कारोबार का PAN, GSTIN, कंपनी या LLP का रजिस्ट्रेशन, Udyam और बैंक खाता, जहाँ आपने दिए हों। हर जाँच पास, "कोई इंसान इसे देखेगा", प्रगति में, या लागू नहीं, इनमें से कुछ दिखाती है। status verifying से in review पर, फिर अस्थायी मंज़ूरी पर जाता है जहाँ आपकी live key सीमित सीमाओं के साथ जारी होती है। आप बाद में अपने जवाब पढ़ सकते हैं, पर सुधार support के ज़रिए होते हैं ताकि कोई नामित व्यक्ति बदलाव दर्ज करे।

24 घंटे की दस्तावेज़ खिड़की

अस्थायी मंज़ूरी के साथ एक काउंटडाउन शुरू होता है: आपके दस्तावेज़ उस अवधि में चाहिए जिसे bundled configuration में 24 घंटे रखा गया है, और ख़त्म होने से 12, 4 और 1 घंटे पहले याद दिलाए जाते हैं। दस्तावेज़ आवेदक के प्रकार पर निर्भर हैं।

फ़ाइलें JPEG, PNG या PDF हो सकती हैं, हर एक अधिकतम 5 MB की। हमारी ऑनबोर्डिंग टीम आपकी तरफ़ से अपलोड कर सकती है और आपके कहने पर खिड़की बढ़ा सकती है, कारण और व्यक्ति का नाम दर्ज करके; bundled configuration में अधिकतम दो बार बढ़ाने की छूट है। दस्तावेज़ों के बिना समय बीत जाए तो आवेदन अपने आप बंद हो जाता है और आप जवाब पहले से भरे हुए नए आवेदन में दे सकते हैं, सिर्फ़ PAN दोबारा टाइप करने होंगे। support एक सीमित अवधि तक बंद आवेदन दोबारा खोल सकता है।

दस्तावेज़ लंबित रहने के दौरान अस्थायी सीमाएँ लागू रहती हैं। bundled डिफ़ॉल्ट हैं प्रति मिनट 60 requests और प्रति दिन 5,000 calls, और status पेज आपके आवेदन के लिए असली संख्याएँ दिखाता है। दस्तावेज़ मंज़ूर होते ही सीमाएँ हट जाती हैं।

live key और wallet

live key जारी होने पर वह एक बार दिखती है। owner को उसे देखने के लिए एक बार वाला लिंक भी ईमेल होता है, और बाद में key rotate करें तो नई key API keys पेज पर दिखती है। live calls चलने से पहले wallet में पैसा चाहिए। रिचार्ज की एक न्यूनतम रकम है (रिचार्ज बॉक्स उसे दिखाता है) और उसके ऊपर 18% GST। StampMitra दिल्ली, राज्य कोड 07, से इनवॉइस करता है, इसलिए दूसरे राज्य के ग्राहक को IGST देना पड़ता है, जबकि दिल्ली के ग्राहक को CGST और SGST दिखते हैं। भुगतान की पुष्टि होते ही GST इनवॉइस आपको ईमेल होता है और billing पेज पर सहेजा जाता है।

फिर wallet चार हालतें बनाता है जो आपको पहले से पता होनी चाहिए। पर्याप्त बैलेंस हो तो live calls चलती हैं। जितनी calls की योजना है उसके लिए बैलेंस कम हो तो शुरू करने से पहले रिचार्ज के लिए कहा जाता है। इस्तेमाल के दौरान घटने पर बैनर बताता है। बैलेंस शून्य होने पर live calls रुक जाती हैं जब तक आप रिचार्ज न करें, और sandbox चलता रहता है। पैसे की कमी से विफल होने वाली call 402 PAYMENT_REQUIRED लौटाती है, संदेश Insufficient fulfilment wallet balance to cover this call. के साथ, जिसे आपकी एरर हैंडलिंग को ऑपरेशन की समस्या मानना चाहिए, retry का उम्मीदवार नहीं।

पहले दिन जो फ़र्क दिखेंगे

पहले दिन production की checklist

1. पक्का कीजिए कि deploy हुई key sk_live_ से शुरू होती है और आपका guard पास होता है।
2. पहली call से पहले wallet का बैलेंस और रिचार्ज की स्थिति देखिए, और पुष्टि कीजिए कि billing ईमेल पर GST इनवॉइस आता है।
3. हर प्रोडक्ट पर अपनी मिल्कियत वाली पहचान से एक call कीजिए। जवाब की अपनी उम्मीद से तुलना कीजिए। referenceId दर्ज कीजिए।
4. उन calls के request logs को dashboard या logs endpoint से पढ़िए और मिलाइए कि वे वही हैं जो आपने भेजा था।
5. एक एरर जान-बूझकर पैदा कीजिए, जैसे ग़लत PAN, और देखिए कि आपका अलर्ट उसे पकड़ता है।
6. जाँचिए कि आपके logs PAN और खाता संख्या मास्क करते हैं।
7. आवेदन की स्थिति तब तक देखते रहिए जब तक दस्तावेज़ मंज़ूर न हों और अस्थायी सीमाएँ न हटें।
8. अपनी निगरानी में, सिर्फ़ dashboard के बैनर में नहीं, कम-बैलेंस का अलर्ट लगाइए।

टेस्ट डेटा की सफ़ाई

sandbox में "बस देखने के लिए" असली पहचानें टाइप करने का मन करता है। रुकिए, तीन कारणों से। असली PAN पर sandbox का जवाब बेमानी है, तो आप कुछ नहीं सीखते। असली नंबर और बनावटी "valid" वाला स्क्रीनशॉट या लॉग की पंक्ति बाद में verification रिकॉर्ड समझी जा सकती है। और आपके साथियों के अपने PAN और बैंक खाते वह निजी डेटा है जिसे रखने का आपके पास कोई मक़सद नहीं।

टेस्ट पहचानों की एक छोटी, संस्करण वाली फ़ाइल रखिए: ऊपर की जादुई वैल्यू और validation टेस्ट के लिए कुछ ठीक-ठाक बनावट वाली गढ़ी हुई वैल्यू। स्क्रीनशॉट, टिकट विवरण और साझा Postman collections में वही दर्ज placeholder इस्तेमाल कीजिए। production smoke test में ऐसी पहचानें इस्तेमाल कीजिए जिन्हें जाँचने का आपको हक़ है, उन्हें रिपॉज़िटरी में नहीं बल्कि secrets की तरह रखिए, और लॉग में मास्क कीजिए।

logs पढ़कर पुष्टि करना कि आपके टेस्ट ने क्या किया

हर call आपके organisation के नाम लॉग होती है, और logs को API key से खोजा जा सकता है। GET /v1/logs पन्नों में items लौटाता है जिनमें id, createdAt समय, actorType, pan.verify जैसा service code और metadata होता है, और उन्हें from, to, service और status (success या failure) से छाना जा सकता है, limit अधिकतम 200 और अगले पन्ने के लिए nextCursor के साथ। GET /v1/usage/summary मौजूदा बिलिंग अवधि के कुल, सेवा-वार calls और दिन-वार calls देता है।

इन्हें टेस्ट चलाने के बाद assertion की तरह इस्तेमाल कीजिए। अगर आपके integration सूट को pan.verify पर चौदह calls करनी थीं और usage summary चालीस दिखाए, तो कुछ retry, लूप या वहाँ समानांतर चल रहा है जहाँ आपने नहीं सोचा था। production में यही दो endpoint आपको इनवॉइस से मिलाने से पहले अपने काउंटर प्लेटफ़ॉर्म के काउंटरों से मिलाने देते हैं। logs कितने समय रखे जाते हैं, यह आपके प्लान पर निर्भर है, sandbox प्लान की छोटी अवधि से लेकर सबसे ऊँचे self-serve प्लान के एक साल तक, इसलिए जो भी आपकी compliance नीति को चाहिए उसे निर्यात कीजिए, यह मानकर मत चलिए कि dashboard आपका संग्रह है। इस पर फ़ैसला verification कॉल से क्या लॉग करें में है।

ईमानदार demo की स्क्रिप्ट

demo वह जगह है जहाँ sandbox को production समझ लिया जाता है। अगर आप StampMitra से चलने वाला verification किसी ग्राहक, निवेशक या अपने नेतृत्व को दिखाते हैं, तो बताइए कि स्क्रीन क्या कर रही है।

शुरुआत माहौल बताकर कीजिए: "यह sandbox key है, इसलिए जवाब सैंपल डेटा हैं।" जादुई वैल्यू इस्तेमाल कीजिए ताकि नतीजा पहले से पता हो, और दोनों को बोलकर बताइए: valid PAN बनावटी नाम लौटाता है, invalid एक पूरा हुआ नकारात्मक नतीजा। एरर हैंडलिंग को जान-बूझकर दिखाइए: ग़लत वैल्यू और ग़लत key भेजकर। किसी असली व्यक्ति का PAN मत डालिए। श्रोता पूछें "क्या यह असली कंपनी है?" तो किसी भी sandbox जवाब के लिए सही उत्तर है: नहीं।

अंत में बताइए कि live संस्करण क्या जोड़ेगा: असली रिकॉर्ड, असली नाम जिन्हें आपको निजी डेटा की तरह सँभालना होगा, wallet की कटौती और मंज़ूरी के दौरान की अस्थायी सीमाएँ। जो demo इस पर साफ़ है, वह भरोसा कमाता है; जो श्रोताओं को sandbox डेटा को असली मान लेने देता है, वह ऐसी समस्या बनाता है जिसे बाद में सुधारना पड़ेगा।

टेस्ट के लिए लागत और सीमाओं की सोच

sandbox में wallet नहीं कटता, पर वह असीमित नहीं है: प्रति organisation प्रति मिनट 10 और प्रति दिन 200 requests। उसे बजट मानिए: fixtures रिकॉर्ड कीजिए, integration tests कम रखिए, और लूप के अंदर टेस्ट मत कीजिए। production में पूरा हुआ नकारात्मक नतीजा भी बिल होने वाली call है, इसलिए अवैध PAN जाँचने वाले टेस्ट को उसकी क़ीमत देनी पड़ती है। pay-as-you-go पर PAN जैसी standard verification ₹5 और bank account ₹4 प्रति call है। मौजूदा प्लान और दरें pricing पेज पर हैं।

आम ग़लतियाँ

• sandbox के "valid" को असली रिकॉर्ड का सबूत मान लेना। कुछ खोजा ही नहीं गया।
• जिस टेस्ट को ख़ास नतीजा चाहिए, उसमें जादुई वैल्यू की जगह मनमानी वैल्यू इस्तेमाल करना।
• sandbox में ऑफ़लाइन GSTIN चेक कैरेक्टर का टेस्ट चलाना और उसका दर्ज वैल्यू को ठुकरा देना।
• production deployment में sandbox key छोड़ देना, या डेवलपर की लोकल फ़ाइल में live key।
• 429 के आसपास ऐसा retry तर्क बनाना जो मानता है कि वह हमेशा हट जाता है, जबकि sandbox की दैनिक सीमा वाला 429 आधी रात IST तक नहीं हटता।
• production के लिए देर से आवेदन करना, और फिर पाना कि दस्तावेज़ की खिड़की, ऊँचे जोखिम वाले प्रोडक्ट की समीक्षा और wallet रिचार्ज, सबमें समय लगता है।
• production smoke test छोड़ देना, ताकि पहली असली name-match score किसी ग्राहक को दिखे।
• असली production जवाबों को टिकट या चैट में चिपकाना।

आगे क्या करें

अगर sandbox key नहीं है तो quickstart में पाँच मिनट लगते हैं। विफलताओं की हैंडलिंग सही कीजिए एरर, retry और idempotency से। हर call से क्या रखना है, यह verification कॉल से क्या लॉग करें से तय कीजिए। तैयार हों तो dashboard से production के लिए आवेदन कीजिए और pricing तथा wallet का ब्योरा pricing पेज पर पढ़िए। इस लेख में आए सैंपल मानों के लिए PAN और GSTIN के endpoint पेज देखिए।

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"
}

{
  "referenceId": "SMV-20260927-9K21P4",
  "verificationId": "VRF-4M8Q2T7XB9KD",
  "gstin": "29AAICP2912R1ZR",
  "GSTIN": "29AAICP2912R1ZR",
  "valid": true,
  "legalNameOfBusiness": "UJJIVAN SMALL FINANCE BANK LIMITED",
  "tradeNameOfBusiness": "UJJIVAN SMALL FINANCE BANK",
  "centerJurisdiction": "I-A RANGE",
  "stateJurisdiction": "GUWAHATI - A - 1",
  "dateOfRegistration": "2017-09-30",
  "constitutionOfBusiness": "Public Limited Company",
  "taxpayerType": "Regular",
  "gstinStatus": "Active",
  "lastUpdateDate": "2022-03-01",
  "natureOfBusinessActivities": [
    "Retail Business",
    "Supplier of Services",
    "Recipient of Goods or Services",
    "Office / Sale Office",
    "Others"
  ],
  "principalPlaceAddress": "First Floor 3512-DISPUR Prithivi Mansion opp. KFC building G.S. Road, Lachit Nagar Assam 781007",
  "principalPlaceSplitAddress": {
    "buildingName": "Prithivi Mansion",
    "street": "G.S. Road",
    "location": "Lachit Nagar",
    "buildingNumber": "3512-DISPUR",
    "district": "Guwahati",
    "state": "Assam",
    "city": "Dispur",
    "flatNumber": "First Floor",
    "latitude": "26.1445",
    "longitude": "91.7362",
    "pincode": "781007"
  },
  "additionalAddresses": [
    {
      "address": "Mirza Santipur NH-37 Dist-Kamrup Rural PS-Palashbari, PO  Mirza Kamrup Assam 781125",
      "splitAddress": {
        "buildingName": "",
        "street": "NH-37",
        "location": "Santipur, Mirza",
        "buildingNumber": "",
        "district": "Kamrup Rural",
        "state": "Assam",
        "city": "Palashbari",
        "flatNumber": "",
        "latitude": "26.0926",
        "longitude": "91.5069",
        "pincode": "781125"
      }
    },
    {
      "address": "N.A.C.C.I. Foundation 3559-Tezpur CHAMBER BHAWAN Binjraj Road, P. o. and P.S. - Tezpur, Dist. Binjraj Road, P. o. and P.S. - Tezpur, Dist. Sonitpur Assam 784154",
      "splitAddress": {
        "buildingName": "CHAMBER BHAWAN",
        "street": "Binjraj Road",
        "location": "Tezpur",
        "buildingNumber": "3559-Tezpur",
        "district": "Sonitpur",
        "state": "Assam",
        "city": "Tezpur",
        "flatNumber": "",
        "latitude": "26.6338",
        "longitude": "92.8006",
        "pincode": "784154"
      }
    }
  ],
  "message": "GSTIN Exists",
  "legalName": "UJJIVAN SMALL FINANCE BANK LIMITED",
  "tradeName": "UJJIVAN SMALL FINANCE BANK",
  "registrationStatus": "Active",
  "principalPlaceOfBusiness": "First Floor 3512-DISPUR Prithivi Mansion opp. KFC building G.S. Road, Lachit Nagar Assam 781007"
}

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