कारोबार वेरिफाई API: GSTIN, CIN और Udyam से सप्लायर ऑनबोर्डिंग

मुख्य बातें

• पाँच endpoints हैं: gstin, cin, udyam, pan-to-gstin, pan-to-udyam। सबके लिए method POST है और पथ /v1/verify/<नाम> है।
• हर endpoint का अपना scope होता है, जैसे verification.gstin.read। API key में वह scope न हो तो 403 आता है।
• नंबर का format पहले ही जाँचा जाता है। गलत format पर 400 मिलता है और verification शुरू ही नहीं होती।
• नतीजा "नहीं मिला" (valid: false या found: false) भी पूरा और billable verification माना जाता है। इसे error न समझें।
• referenceId (जैसे SMV-20260927-9K21P4) StampMitra का अपना transaction id है। यह idempotency key नहीं है, इसलिए retry में दोहरी call से बचने का इंतज़ाम आपको खुद करना होगा।
• PAN मिला हो और GSTIN या Udyam नंबर न हो, तो pan-to-gstin और pan-to-udyam से खोज सकते हैं।
• CIN के जवाब में कंपनी का नाम, स्थिति और directors की सूची आती है। Udyam के जवाब में organizationType (Micro, Small, Medium) आता है।
• Sandbox में sk_test_... key से बनाइए, production में sk_live_... से। असली पहचान-डेटा कभी लॉग या स्क्रीनशॉट में मत रखिए।

सप्लायर ऑनबोर्डिंग में असली दिक्कत कहाँ आती है?

मान लीजिए "सहज ट्रेड कनेक्ट" नाम का एक काल्पनिक B2B पोर्टल है। यहाँ किराना थोक वाले, पैकेजिंग वाले और छोटे कारखानेदार अपना माल बेचने के लिए जुड़ते हैं। पोर्टल की ऑपरेशंस टीम रोज़ पचास-साठ नए आवेदन देखती है। हर आवेदन में कोई न कोई सर्टिफिकेट की फोटो लगी होती है, और हर फोटो को कोई इंसान आँख से मिलाता है।

इस तरीके में तीन दिक्कतें बार-बार आती हैं। पहली, फोटो या PDF में लिखा नंबर असली है या नहीं, यह आँख से पता नहीं चलता। दूसरी, एक ही व्यापारी के पास GSTIN, PAN और Udyam तीनों हो सकते हैं, पर आवेदन में वह सिर्फ़ एक दे देता है और बाकी का इंतज़ार चलता रहता है। तीसरी, कंपनी वाले सप्लायर के मामले में यह देखना कि कंपनी चालू है और उसके directors कौन हैं, अलग ही मेहनत माँगता है।

API इन तीनों को एक सीधे काम में बदल देती है: नंबर लीजिए, endpoint चलाइए, JSON का जवाब देखकर तय कीजिए कि आवेदन आगे जाएगा, रुकेगा या इंसान के पास जाएगा। ध्यान रखिए कि API सिर्फ़ तथ्य लौटाती है, फ़ैसला आपका नियम तय करेगा। कौन सा सप्लायर "पक्का" माना जाए, यह आपकी कंपनी की नीति है।

कितना ऑटोमेशन ठीक है?

शुरुआत में पूरी तरह अपने-आप फ़ैसला करवाने की जल्दी मत कीजिए। पहले महीने में API का जवाब ऑपरेशंस टीम को दिखाइए और उनके फ़ैसले से मिलाइए। जहाँ मेल खाए, वहाँ ऑटो-अप्रूव चालू कीजिए। जहाँ फ़र्क दिखे, वहाँ नियम सुधारिए।

पाँच endpoints एक नज़र में

नीचे की तालिका में हर endpoint का इनपुट, scope और जवाब का मुख्य हिस्सा है। सारे मान src/data/api-products.ts में दर्ज असली endpoint-विवरण से लिए गए हैं।

हर जवाब में referenceId भी होता है। इसका format SMV-YYYYMMDD-XXXXXXX है। इसे अपने डेटाबेस में आवेदन के साथ रखिए, ताकि बाद में किसी विवाद या सपोर्ट के सवाल में आप ठीक उसी call का हवाला दे सकें।

अलग-अलग endpoint की पूरी parameter सूची और error उदाहरण देखने हों तो GSTIN का दस्तावेज़, CIN का दस्तावेज़ और Udyam का दस्तावेज़ खोलिए। सभी verification endpoints की एक जगह की सूची verification docs पर है।

पहचान के लिए इनपुट कहाँ से आता है?

GSTIN आपको सप्लायर के रजिस्ट्रेशन सर्टिफिकेट या इनवॉइस से मिलता है। CIN कंपनी के दस्तावेज़ों में लिखा होता है। Udyam नंबर सर्टिफिकेट पर होता है। PAN आमतौर पर हर आवेदन में माँगा जाता है, इसीलिए PAN से आगे की खोज वाले दो endpoints काम आते हैं। इनका ज़िक्र आगे अलग हिस्से में है।

शुरू करने से पहले: API key, scope और base URL

सभी call के लिए base URL https://api-b2b.stampmitra.in है। पहचान के लिए हर request में Authorization: Bearer <api-key> header लगाइए। x-api-key header भी चलता है। Sandbox की key sk_test_ से शुरू होती है और production की sk_live_ से।

Scope की भूमिका

हर API key के साथ scopes की एक सूची जुड़ी होती है। GSTIN जाँचने के लिए verification.gstin.read चाहिए, CIN के लिए verification.cin.read, Udyam के लिए verification.udyam.read, और खोज वाले दोनों endpoints के लिए क्रमशः verification.pan_to_gstin.read और verification.pan_to_udyam.read। किसी scope के बिना call करने पर 403 आता है और संदेश कहता है कि key वैध है पर इस endpoint का scope नहीं है। संवेदनशील scopes पर IP allowlist भी लगाई जा सकती है, यह बात authentication के दस्तावेज़ में दी गई है।

अपने पोर्टल के लिए एक सुझाव: बैकएंड की key में सिर्फ़ वही पाँच scopes रखिए जो ऑनबोर्डिंग को चाहिए। अगर वही key बाद में किसी और काम में भी लगेगी, तो उसके लिए अलग key बनाइए। एक key चोरी होने पर नुकसान उतना ही रहता है जितने scopes उसके पास हैं।

Key कहाँ रखें?

Key को सिर्फ़ सर्वर पर रखिए, किसी environment variable में, जैसे STAMPMITRA_API_KEY। ब्राउज़र के JavaScript में, मोबाइल ऐप के अंदर या GitHub के कोड में key मत डालिए। आपके पोर्टल का फ़्रंटएंड सिर्फ़ आपके अपने बैकएंड से बात करे, और आपका बैकएंड StampMitra से। key बनाने और बदलने की प्रक्रिया API keys वाले पन्ने पर है, और शुरुआती कदमों के लिए quickstart देखिए।

Rate limit

दस्तावेज़ में दिए error उदाहरण के अनुसार हर endpoint पर 60 सेकंड में 60 requests की सीमा है। सीमा पार करने पर 429 और TOO_MANY_REQUESTS मिलता है। जब आप एक साथ सैकड़ों पुराने सप्लायर दोबारा जाँचेंगे, तब यह सीमा मायने रखेगी। उस हालत में queue लगाइए और सीमा के अंदर रहकर धीरे-धीरे चलाइए।

GSTIN कैसे वेरिफाई करें?

GSTIN सप्लायर की सबसे आम पहचान है, इसलिए ऑनबोर्डिंग की शुरुआत यहीं से कीजिए। endpoint है POST /v1/verify/gstin। gstin में 15 अक्षरों का नंबर भेजना है। businessName वैकल्पिक है और यहाँ आवेदक का बताया कारोबारी नाम रखा जाता है ताकि उसे मिलाया जा सके।

curl -X POST "https://api-b2b.stampmitra.in/v1/verify/gstin" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "gstin": "07AAAAA1111A1Z1", "businessName": "Jane Doe Enterprises" }'

दस्तावेज़ में दिया असली जवाब कुछ ऐसा दिखता है:

{
  "referenceId": "SMV-20260927-9K21P4",
  "GSTIN": "07AAAAA1111A1Z1",
  "valid": true,
  "legalName": "Jane Doe Enterprises Private Limited",
  "tradeName": "Jane Doe Enterprises",
  "registrationStatus": "Active",
  "principalPlaceOfBusiness": "123, MG Road, Bengaluru, Karnataka, 560001",
  "message": "GSTIN Exists"
}

जवाब से क्या तय करें

सबसे पहले valid देखिए। true हो तो अगला सवाल registrationStatus का है। नमूने में यह Active है। जो भी और मान आए, उसे आपके नियमों में साफ़ बताया हुआ होना चाहिए कि आगे जाने देना है या नहीं। अपने कोड में सिर्फ़ Active को "पास" मानिए और बाकी सब मानों को समीक्षा की कतार में डाल दीजिए। इस तरह नया या अनजाना मान आने पर भी आप गलती से किसी को पास नहीं करेंगे।

फिर legalName और tradeName देखिए। सहज ट्रेड कनेक्ट के उदाहरण में आवेदक ने लिखा "जेन डो एंटरप्राइज़ेज़" और रजिस्ट्री में tradeName भी यही है, जबकि legalName में "Private Limited" जुड़ा है। यानी आवेदन में जो नाम लिखा गया, वह ट्रेड नाम से मिला, कानूनी नाम से नहीं। यह सामान्य बात है। इसलिए नाम की तुलना में दोनों fields को देखिए, सिर्फ़ एक से सख़्ती से मिलान मत कीजिए।

principalPlaceOfBusiness से आप आवेदक के पते की मोटी जाँच कर सकते हैं, जैसे शहर या राज्य का मेल। पूरा पता अक्षरशः मिलने की उम्मीद मत रखिए, क्योंकि लोग पता अलग-अलग ढंग से लिखते हैं।

GSTIN का राज्य कोड

दस्तावेज़ के नमूने में GSTIN 07 से शुरू होता है और pan-to-gstin के जवाब में उसी नंबर के आगे राज्य "Delhi" लिखा है। यानी शुरुआती दो अंक राज्य से जुड़े हैं। पर राज्य-कोड की पूरी तालिका या GSTIN की पूरी बनावट मैंने यहाँ नहीं दी, क्योंकि उसे GST पोर्टल के आधिकारिक पन्ने से मिलाना ज़रूरी है। अपने फ़ॉर्म की जाँच के लिए 15 अक्षर की लंबाई काफ़ी है, बाकी वेरिफिकेशन API संभालती है। इस endpoint का एक और विस्तृत गाइड GSTIN verification API गाइड में है।

CIN से कंपनी और उसके directors की जाँच

जब सप्लायर प्राइवेट लिमिटेड या कोई और कंपनी हो, तो उसकी कंपनी-पहचान cin से जाँचिए। endpoint POST /v1/verify/cin है और इनपुट बस एक cin है। नमूना CIN दस्तावेज़ में U74999DL2015PTC284009 है।

curl -X POST "https://api-b2b.stampmitra.in/v1/verify/cin" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "cin": "U74999DL2015PTC284009" }'

{
  "referenceId": "SMV-20260927-6R38Y3",
  "valid": true,
  "companyName": "JANE DOE ENTERPRISES PRIVATE LIMITED",
  "incorporationDate": "2015-03-12",
  "cinStatus": "ACTIVE",
  "companyStatus": "Active",
  "directors": [
    { "din": "01234567", "name": "RAHUL KUMAR", "designation": "Director" }
  ],
  "email": "[email protected]",
  "registrationNumber": "U74999DL2015PTC284009",
  "incorporationCountry": "India"
}

इन fields का इस्तेमाल कैसे करें

companyStatus और cinStatus दोनों देखिए। नमूने में दोनों चालू दिखाते हैं। अगर किसी कंपनी की स्थिति "Active" के अलावा कुछ और आए, तो उसे अपने-आप पास मत कीजिए। यहाँ भी वही नियम चलाइए: सिर्फ़ जिसे आप जानते हैं उसे पास कीजिए।

incorporationDate से कंपनी की उम्र निकाल सकते हैं। कई पोर्टल नई-नई बनी कंपनियों को शुरुआत में कम क्रेडिट लिमिट देते हैं। यह आपकी अपनी जोखिम-नीति है, API का नियम नहीं।

directors एक सूची है, जिसमें हर director का din, name और designation होता है। ऑनबोर्डिंग में इसका एक सीधा इस्तेमाल है: आवेदन भरने वाला व्यक्ति कौन है? अगर वह कंपनी का director है, तो भरोसा ज़्यादा बनता है। अगर वह कोई कर्मचारी है, तो आप उससे अधिकार-पत्र माँग सकते हैं। यह तुलना आपको अपने कोड में करनी होगी, क्योंकि cin endpoint में नाम मिलाने वाला कोई parameter नहीं है।

कंपनी का नाम और GSTIN का नाम

एक अच्छी जाँच यह है कि CIN से मिले companyName की तुलना उसी सप्लायर के GSTIN के legalName से की जाए। दोनों अलग सरकारी रजिस्ट्रियों से आते हैं और मामूली फ़र्क (जैसे "Private Limited" बनाम "Pvt. Ltd.") सामान्य है। इसलिए तुलना से पहले दोनों नामों को बड़े अक्षरों में बदलकर विराम-चिह्न हटा दीजिए। पूरा मेल न मिले तो मामला इंसान को दीजिए, खारिज मत कीजिए।

कंपनी के रजिस्ट्रेशन के आधिकारिक आँकड़े MCA पोर्टल से भी देखे जा सकते हैं। मेरी तरफ़ से इस ड्राफ़्ट के समय MCA की साइट खुल नहीं पाई, इसलिए CIN की बनावट की व्याख्या यहाँ नहीं दी गई। कृपया उसे सीधे MCA के आधिकारिक स्रोत से मिलाइए।

Udyam रजिस्ट्रेशन कैसे जाँचें?

छोटे कारोबारियों के लिए Udyam नंबर सबसे आम दस्तावेज़ है। endpoint POST /v1/verify/udyam है और इनपुट udyamNumber है, जैसे UDYAM-MH-12-1234567।

curl -X POST "https://api-b2b.stampmitra.in/v1/verify/udyam" \
  -H "Authorization: Bearer $STAMPMITRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "udyamNumber": "UDYAM-MH-12-1234567" }'

{
  "referenceId": "SMV-20260927-5U29V7",
  "found": true,
  "udyamStatus": "Active",
  "enterpriseName": "Jane Doe Enterprises",
  "enterpriseType": "Proprietorship",
  "organizationType": "Micro",
  "certificateUrl": "https://udyamregistration.gov.in/Udyam_Download/UDYAM-MH-12-1234567.pdf"
}

यहाँ valid नहीं, found है

ध्यान दीजिए कि Udyam, pan-to-gstin और pan-to-udyam के जवाब में valid की जगह found आता है। GSTIN और CIN के जवाब में valid आता है। अगर आप एक ही कोड-ब्लॉक से सब संभालना चाहें, तो हर endpoint के हिसाब से सही field पढ़िए। गलत field पढ़ने पर undefined मिलेगा, और undefined को "false" मान लेने पर असली सप्लायर बेवजह रुक जाएँगे।

organizationType का मतलब

organizationType में Micro, Small या Medium लिखा आता है। Udyam पोर्टल के अनुसार वर्गीकरण निवेश और टर्नओवर पर टिका है। मैंने 2026-10-16 को पोर्टल का मुख्य पन्ना देखा, जिसमें 01-04-2025 से लागू सीमाएँ ये बताई गई थीं: Micro में निवेश ₹2.5 करोड़ और टर्नओवर ₹10 करोड़ तक, Small में ₹25 करोड़ और ₹100 करोड़ तक, Medium में ₹125 करोड़ और ₹500 करोड़ तक। ये सीमाएँ समय के साथ बदल सकती हैं, इसलिए अपने नियम में इन्हें हार्डकोड मत कीजिए। API जो organizationType लौटाए, उसी को मानिए।

पोर्टल यह भी कहता है कि रजिस्ट्रेशन मुफ़्त है और स्व-घोषणा पर आधारित है। इसका मतलब यह निकलता है कि Udyam की मौजूदगी इस बात का सबूत है कि रजिस्ट्रेशन हुआ है, कारोबार की गुणवत्ता या भुगतान की क्षमता का सबूत नहीं। इसे अपने जोखिम-आकलन का एक हिस्सा मानिए, पूरा आकलन नहीं।

certificateUrl का क्या करें

जवाब में सर्टिफिकेट का लिंक आता है। चाहें तो उसे ऑपरेशंस टीम के रिव्यू पन्ने पर "सर्टिफिकेट देखें" बटन बना दीजिए। पर यह लिंक किसी बाहरी साइट का है, इसलिए उसे अपनी तरफ़ से सहेजकर रखने से पहले सोचिए कि आपको वाकई ज़रूरत है या नहीं।

PAN से GSTIN और Udyam नंबर खोजना

व्यापारी के पास PAN हो और बाकी नंबर उसे याद न हों, तब ये दो endpoints काम आते हैं। इनमें इनपुट सिर्फ़ pan होता है, ABCDE1234F के format में।

pan-to-gstin

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

{
  "referenceId": "SMV-20260927-1L67Z5",
  "found": true,
  "gstins": [
    { "gstin": "07AAAAA1111A1Z1", "state": "Delhi", "status": "Active" }
  ]
}

एक PAN पर कई GSTIN हो सकते हैं, हर राज्य के लिए अलग। इसलिए जवाब gstins की एक सूची है। हर आइटम में gstin, state और status आता है। अपने पोर्टल में आप आवेदक से कह सकते हैं: "इनमें से कौन सा GSTIN इस सप्लाई के लिए है?" और फिर चुने हुए नंबर पर ऊपर वाला gstin endpoint चलाकर पूरा ब्योरा ले सकते हैं। यानी खोज और जाँच दो अलग कदम हैं।

pan-to-udyam

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

{
  "referenceId": "SMV-20260927-0A44B2",
  "found": true,
  "status": "Active",
  "udyamNumber": "UDYAM-MH-12-1234567"
}

दस्तावेज़ के नमूने में जवाब का एक ही udyamNumber है। इसमें सूची नहीं दिखाई गई, इसलिए अपने कोड को इस बात पर टिकाइए कि जवाब का आकार वही है जो दस्तावेज़ में दर्ज है, और नमूने से हटकर कुछ मानकर मत चलिए। Udyam पोर्टल के अनुसार एक उद्यम एक ही Udyam रजिस्ट्रेशन करा सकता है, पर उसमें कई गतिविधियाँ जोड़ सकता है। यह सामान्य जानकारी है और API के जवाब के आकार के बारे में कोई वादा नहीं।

PAN की जाँच और इन खोजों का रिश्ता

अगर आपको पहले यह भी देखना है कि PAN खुद असली है और नाम से मिलता है, तो वह अलग pan endpoint है। उसके बारे में PAN verification API गाइड में पूरा ब्योरा है। ध्यान रखिए कि खोज वाले endpoints "PAN असली है" यह साबित करने के लिए नहीं बने। वे सिर्फ़ यह बताते हैं कि इस PAN से कौन से GSTIN या Udyam जुड़े मिले।

कौन सा सप्लायर किस रास्ते से जाएगा: फ़ैसले का नक्शा

सहज ट्रेड कनेक्ट पर तीन तरह के सप्लायर आते हैं, और हर एक के लिए रास्ता अलग है। नीचे की तालिका में एक सीधा नियम है।

नियम बनाते समय तीन सवाल पूछिए

पहला, क्या यह सप्लायर GST में रजिस्टर्ड होना ज़रूरी है? अगर आपके पोर्टल पर बिक्री पर इनवॉइस बनता है, तो शायद हाँ। पर कई छोटे कारोबारी GST रजिस्ट्रेशन की सीमा से नीचे रहते हैं, और अगर आपने GSTIN अनिवार्य कर दिया तो वे पोर्टल पर आ ही नहीं पाएँगे। यह कारोबारी फ़ैसला है और आपके सलाहकार से पूछकर तय होना चाहिए।

दूसरा, क्या इसी सप्लायर के लिए एक से ज़्यादा दस्तावेज़ देखने की ज़रूरत है? जितनी बड़ी क्रेडिट लिमिट, उतने ज़्यादा स्रोत।

तीसरा, जब API "नहीं मिला" कहे, तो आगे क्या होगा? हम आगे के हिस्से में इस पर लौटेंगे। बस इतना याद रखिए कि "नहीं मिला" का मतलब "फ़र्ज़ी" नहीं है।

तीन आवेदकों की काल्पनिक कहानी

अब इसे एक दिन के काम में उतारकर देखते हैं। सुबह दस बजे तीन आवेदन आते हैं। सभी नाम और नंबर काल्पनिक हैं।

पहला आवेदन "मीरा पैकेजिंग" का है, जो एक रजिस्टर्ड व्यापारी है। उसने सिर्फ़ GSTIN दिया है। आपका बैकएंड gstin चलाता है और registrationStatus "Active" लौटता है। tradeName आवेदन के नाम से मिल जाता है। नियम के अनुसार आवेदन सीधे APPROVE हो जाता है और referenceId आवेदन के साथ सहेज लिया जाता है। इसमें एक ही call लगी।

दूसरा आवेदन "उत्तम फूड्स प्राइवेट लिमिटेड" नाम की कंपनी का है। उसने CIN और GSTIN दोनों दिए हैं। cin से कंपनी का नाम और directors की सूची मिलती है, gstin से legalName। दोनों नाम सफ़ाई के बाद एक जैसे निकलते हैं। आवेदन भरने वाले का नाम directors की सूची में है, इसलिए यह भी पास होता है। दो call लगीं।

तीसरा आवेदन "राजू की दुकान" का है, एक छोटा दुकानदार, जिसके पास सिर्फ़ Udyam सर्टिफिकेट और PAN है। आपका बैकएंड udyam चलाता है और found: true के साथ organizationType: "Micro" मिलता है। फिर यह जानने के लिए कि दुकानदार GST में भी है या नहीं, pan-to-gstin चलता है और found: false आता है। आपके नियम में GSTIN अनिवार्य नहीं है, इसलिए आवेदन "सीमित क्रेडिट" की श्रेणी में जाता है। यहाँ found: false का मतलब दुकानदार का रिजेक्शन नहीं, बस इतना है कि उसके पास GST नहीं मिला।

इस कहानी का सबक यह है कि एक ही नतीजे के अलग-अलग मतलब हो सकते हैं, और मतलब तय करने वाला आपका नियम है। API सिर्फ़ तथ्य देती है।

सही क्रम

सस्ती और सीधी जाँच पहले चलाइए। उदाहरण के लिए, आवेदक ने GSTIN दिया हो तो सीधे gstin चलाइए। कुछ भी चलाने से पहले अपनी तरफ़ से format की जाँच कर लीजिए, ताकि गलत टाइप हुए नंबरों पर पैसे न खर्च हों। हर वेरिफिकेशन की कीमत आज के हिसाब से ₹5 रुपये प्रति सफल call है (GSTIN के लिए), और CIN के लिए ₹5, Udyam के लिए ₹5। ताज़ा दरें हमेशा pricing पन्ने पर देख लीजिए।

Node.js और Python में पूरी ऑनबोर्डिंग सर्विस

अब ऊपर के सारे टुकड़े जोड़कर एक छोटा बैकएंड लिखते हैं जो सप्लायर के आवेदन को लेकर एक नतीजा बनाता है। दोनों उदाहरण वही endpoints, headers और fields इस्तेमाल करते हैं जो दस्तावेज़ में दर्ज हैं।

Node.js (18 या उससे ऊपर)

const BASE = "https://api-b2b.stampmitra.in";
const KEY = process.env.STAMPMITRA_API_KEY;

async function verify(path, body) {
  const res = await fetch(`${BASE}/v1/verify/${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  const data = await res.json();
  if (!res.ok) {
    const e = data.error || {};
    const err = new Error(e.message || "verification failed");
    err.status = res.status;
    err.code = e.code;
    err.requestId = e.requestId;
    throw err;
  }
  return data;
}

async function onboardSupplier(app) {
  const result = { checks: [], decision: "REVIEW" };

  if (app.gstin) {
    const g = await verify("gstin", { gstin: app.gstin, businessName: app.businessName });
    result.checks.push({ type: "gstin", ref: g.referenceId, ok: g.valid && g.registrationStatus === "Active" });
  }
  if (app.cin) {
    const c = await verify("cin", { cin: app.cin });
    result.checks.push({ type: "cin", ref: c.referenceId, ok: c.valid && c.companyStatus === "Active" });
  }
  if (app.udyamNumber) {
    const u = await verify("udyam", { udyamNumber: app.udyamNumber });
    result.checks.push({ type: "udyam", ref: u.referenceId, ok: u.found && u.udyamStatus === "Active" });
  }
  if (!app.gstin && app.pan) {
    const p = await verify("pan-to-gstin", { pan: app.pan });
    result.checks.push({ type: "pan-to-gstin", ref: p.referenceId, ok: p.found, gstins: p.gstins });
  }

  if (result.checks.length && result.checks.every((c) => c.ok)) result.decision = "APPROVE";
  return result;
}

Python (requests के साथ)

import os
import requests

BASE = "https://api-b2b.stampmitra.in"
KEY = os.environ["STAMPMITRA_API_KEY"]


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


def verify(path, body):
    r = requests.post(
        f"{BASE}/v1/verify/{path}",
        headers={"Authorization": f"Bearer {KEY}"},
        json=body,
        timeout=30,
    )
    data = r.json()
    if not r.ok:
        e = data.get("error", {})
        raise VerifyError(r.status_code, e.get("code"), e.get("message"), e.get("requestId"))
    return data


def check_udyam(urn):
    d = verify("udyam", {"udyamNumber": urn})
    return {
        "ref": d["referenceId"],
        "ok": bool(d.get("found")) and d.get("udyamStatus") == "Active",
        "category": d.get("organizationType"),
    }

इस कोड में क्या ध्यान देने लायक है

पहला, decision का डिफ़ॉल्ट REVIEW है, APPROVE नहीं। सब जाँचें पास हों तभी APPROVE बनता है। यही "सुरक्षित डिफ़ॉल्ट" का सिद्धांत है।

दूसरा, हर check के साथ referenceId सहेजा जा रहा है, ताकि ऑडिट के समय काम आए।

तीसरा, error में requestId भी पकड़ा गया है। हर error का शरीर { "error": { "code", "message", "requestId" } } के आकार में आता है। requestId आपके सपोर्ट अनुरोध में सबसे काम की चीज़ है। इसे लॉग कीजिए। अन्य भाषाओं में SDK का ब्योरा SDKs पन्ने पर देखिए, और PAN के साथ दोनों भाषाओं का उदाहरण Node.js और Python में PAN verify गाइड में है।

नतीजे को कैसे पढ़ें: valid false बनाम error

नए डेवलपर यहाँ सबसे ज़्यादा गड़बड़ करते हैं, इसलिए इसे अलग से देखते हैं। तीन अलग स्थितियाँ होती हैं और तीनों का मतलब अलग है।

स्थिति एक: HTTP 200 और valid: true या found: true

verification पूरी हुई और रिकॉर्ड मिला। अब आप fields पढ़कर नियम चलाएँगे।

स्थिति दो: HTTP 200 और valid: false या found: false

verification पूरी हुई, पर रिकॉर्ड नहीं मिला या वैध नहीं निकला। दस्तावेज़ के अनुसार यह भी एक पूरी और billable verification है, और इसमें भी referenceId आता है। इसे error की तरह try/catch में पकड़ने की कोशिश मत कीजिए, क्योंकि यह exception है ही नहीं। यह एक नतीजा है।

इस नतीजे के बाद आवेदक को क्या कहना है? "आपका GSTIN नहीं मिला। कृपया नंबर दोबारा जाँचकर डालें।" पहली बार में सीधे "आप धोखेबाज़ हैं" जैसा कुछ मत कहिए। टाइपिंग की गलती सबसे आम कारण है। दो बार की कोशिश के बाद मामला इंसान को दीजिए।

स्थिति तीन: HTTP 4xx या 5xx

यह असली error है। 400 में नंबर का format गलत है, 401 में key गलत है, 402 में wallet का पैसा कम है, 403 में scope नहीं है, 429 में rate limit पार हुई, और 502 में ऊपरी verification सेवा तक पहुँच नहीं हुई। 502 के शरीर में code "INTERNAL_ERROR" और संदेश "Unable to reach the order/customer service right now" दिखाया गया है। इन मामलों में आवेदक को "फ़र्ज़ी" मत ठहराइए। यह आपकी या सेवा की तकनीकी समस्या है, उसकी नहीं। आवेदन को "जाँच बाकी" में रखिए और बाद में दोबारा चलाइए।

आवेदक को संदेश कैसे दिखाएँ

तकनीकी नतीजे को सीधे आवेदक के सामने मत रखिए। हर स्थिति के लिए एक साफ़, नरम संदेश तैयार रखिए। valid: true पर: "आपका GSTIN सत्यापित हो गया है, अगला कदम चुनिए।" found: false पर: "यह नंबर हमें नहीं मिला। कृपया सर्टिफिकेट से देखकर दोबारा डालें।" 400 पर: "नंबर का रूप ठीक नहीं लगता, GSTIN में 15 अक्षर होते हैं।" 402, 429 और 502 पर आवेदक को तकनीकी वजह बताने की ज़रूरत नहीं: "आपका आवेदन मिल गया है, जाँच पूरी होते ही हम बताएँगे।" यानी आपकी अंदरूनी गड़बड़ी आवेदक पर न आए। संदेश हिंदी में दिखाना हो तो उन्हें अपने फ़ॉर्म की भाषा-फ़ाइल में अलग रखिए, ताकि API के जवाब के message field पर भरोसा न करना पड़े। वह field आपके लॉग के काम का है, आवेदक के पढ़ने के लिए नहीं बना।

दोनों नतीजों को अलग रखिए

अपने डेटाबेस में status के कम से कम चार मान रखिए: VERIFIED, NOT_FOUND, CHECK_FAILED (तकनीकी समस्या) और NEEDS_REVIEW। जिस दिन ये अलग-अलग होंगे, उस दिन से ग्राहक-सपोर्ट के सवाल आधे हो जाएँगे, क्योंकि आप ठीक बता पाएँगे कि किस आवेदन में क्या हुआ।

आम गलतियाँ और उनके कारण

ऑनबोर्डिंग पोर्टलों में ये गलतियाँ बार-बार दिखती हैं।

दोहरी call की समस्या को ज़रा खोलकर समझिए

मान लीजिए आवेदक ने "सबमिट" बटन दो बार दबा दिया, या आपके बैकएंड ने timeout के बाद अपने-आप retry कर दिया। StampMitra का दस्तावेज़ साफ़ कहता है कि referenceId idempotency key नहीं है। इसलिए एक ही नंबर पर दो बार call जाए तो उसे दो अलग verification समझना सुरक्षित है, और दोनों का खर्च लग सकता है। इसका सीधा बचाव यह है: अपने आवेदन पर एक यूनिक id रखिए और जब तक एक check "चल रहा है" की स्थिति में है, तब तक उसी आवेदन पर दूसरा check शुरू मत होने दीजिए। साथ ही हर check का नतीजा referenceId के साथ सहेजिए, ताकि वही नतीजा दोबारा इस्तेमाल हो सके।

फ़ॉर्म में पहले से जाँच कैसे करें

API तक पहुँचने से पहले अपने फ़ॉर्म में हल्की जाँच लगाइए। GSTIN के लिए 15 अक्षर की लंबाई देखिए। Udyam के लिए यह देखिए कि नंबर UDYAM- से शुरू होता है और दस्तावेज़ के नमूने UDYAM-MH-12-1234567 जैसे रूप में है। PAN के लिए पाँच अक्षर, चार अंक और एक अक्षर का रूप देखिए। अंतिम फ़ैसला फिर भी सर्वर का होगा, इसलिए फ़ॉर्म की जाँच को पूरी जाँच मत समझिए। उसका मक़सद सिर्फ़ टाइपिंग की गलती जल्दी पकड़ना है। कॉपी-पेस्ट में अक्सर आगे-पीछे खाली जगह आ जाती है, तो नंबर भेजने से पहले उसे साफ़ कर लीजिए। इससे 400 कम आएँगे और बेकार call भी नहीं जाएँगी।

नाम की तुलना में सख़्ती

RAHUL KUMAR और Rahul Kumar एक ही व्यक्ति हैं, पर सीधी string तुलना उन्हें अलग बताएगी। तुलना से पहले दोनों तरफ़ का नाम एक जैसे रूप में लाइए: अक्षर बड़े, अतिरिक्त खाली जगह हटाई हुई, विराम-चिह्न हटे हुए। इसके बाद भी मेल न बैठे तो मामला इंसान के पास जाए।

Errors और troubleshooting

सारे errors का आकार एक जैसा है: { "error": { "code", "message", "requestId" } }। नीचे उन्हीं मामलों की सूची है जो इन endpoints के दस्तावेज़ में दर्ज हैं। इनके अलावा किसी और code या शरीर का अंदाज़ा मत लगाइए। गहराई से पढ़ने के लिए API errors संभालने वाला गाइड देखिए।

जब कुछ समझ न आए तो इस क्रम में जाँचिए

सबसे पहले, क्या हम सही environment की key इस्तेमाल कर रहे हैं? sk_test_ और sk_live_ अलग हैं। फिर, क्या key में उस endpoint का scope है? फिर, क्या JSON का शरीर वही नाम इस्तेमाल करता है जो दस्तावेज़ में है, जैसे udyamNumber, gstin, cin, pan? एक आम गलती udyamNumber की जगह udyam या urn लिखना है। आख़िर में जवाब का requestId नोट करके सपोर्ट को भेजिए। सपोर्ट का पता [email protected] है, और आम सवालों के लिए contact पन्ना भी है।

डेटा, सहमति और सुरक्षा

GSTIN, CIN और Udyam कारोबार के रिकॉर्ड हैं, पर PAN और directors के नाम जैसी चीज़ें किसी व्यक्ति से जुड़ी होती हैं। इसलिए कुछ आदतें शुरू से ही डाल लीजिए। यहाँ मैं डिजिटल व्यक्तिगत डेटा संरक्षण अधिनियम, 2023 की सामान्य भावना भर बता रहा हूँ। मेरी तरफ़ से इस ड्राफ़्ट के समय अधिनियम का मूल पाठ खुल नहीं पाया, इसलिए धाराओं के नंबर या बारीक शर्तें नहीं लिखी हैं। अपने मामले में लागू शर्तों के लिए योग्य सलाहकार से पूछिए।

सहमति और मक़सद

आवेदक को साफ़ बताइए कि आप उसका GSTIN, PAN या Udyam नंबर किस काम के लिए जाँच रहे हैं। सहमति का एक रिकॉर्ड (कब, किसने, किस मक़सद से) रखिए। जिस मक़सद के लिए जाँचा, उसी के लिए इस्तेमाल कीजिए। सप्लायर की जाँच के लिए माँगा गया डेटा बाद में मार्केटिंग लिस्ट में मत डालिए।

कम से कम रखिए

जवाब में जो सचमुच चाहिए, वही सहेजिए। उदाहरण के लिए, ज़्यादातर पोर्टलों को directors की पूरी सूची रखने की ज़रूरत नहीं पड़ती, सिर्फ़ यह कि "आवेदक director है या नहीं।" referenceId, नतीजा और जाँच की तारीख़ आम तौर पर ऑडिट के लिए काफ़ी होते हैं। रखे हुए डेटा की एक समय-सीमा तय कीजिए और उसके बाद मिटाइए।

लॉग और स्क्रीनशॉट

लॉग में पूरे request-शरीर मत छापिए। किसी बग की रिपोर्ट में असली GSTIN, PAN या CIN चिपकाने से बचिए। इस गाइड के सभी नमूने काल्पनिक मानों के हैं, और आपके टेस्ट में भी यही रखिए। अगर सपोर्ट को कुछ भेजना हो, तो requestId और referenceId भेजिए, असली दस्तावेज़ नंबर नहीं।

पुराने सप्लायरों की दोबारा जाँच

ऑनबोर्डिंग के दिन का नतीजा हमेशा सही नहीं रहता। कोई GSTIN बाद में बदल सकता है और कोई कंपनी अपनी स्थिति बदल सकती है। इसलिए कई पोर्टल साल में एक बार या बड़े ऑर्डर से पहले सप्लायर की दोबारा जाँच करते हैं। यह करना हो तो हर सप्लायर पर नई call चलेगी और उसका खर्च भी लगेगा। इसलिए सबको एक साथ चलाने की जगह पहले उन सप्लायरों को चुनिए जिनसे बड़ा लेन-देन होने वाला है। पुराने नतीजे के साथ तारीख़ रखिए, ताकि हर कोई देख सके कि जाँच कितनी पुरानी है। दोबारा जाँच का हर नतीजा नए referenceId के साथ अलग रिकॉर्ड बनाए, पुराने को मिटाए नहीं। इस तरह आप किसी भी दिन बता सकते हैं कि उस दिन आपके पास कौन सी जानकारी थी।

StampMitra की नीतियाँ

प्लेटफ़ॉर्म के इस्तेमाल के नियम API acceptable use policy में हैं, डेटा-संभाल के नियम developer privacy policy और data processing addendum में, और सुरक्षा के तरीके API security policy में। इन्हें आपके वकील या अनुपालन टीम को एक बार पढ़ लेना चाहिए।

Sandbox में टेस्टिंग और production में जाना

हर नया इंटीग्रेशन पहले sandbox में चलाइए। sk_test_ key बनाने के लिए signup पर खाता खोलिए। प्लेटफ़ॉर्म के पन्नों के अनुसार sandbox मुफ़्त है और उसकी call से आपके wallet से पैसा नहीं कटता। Sandbox की सीमा को लेकर कुछ पन्नों में अलग-अलग शब्द मिलते हैं (कहीं "lifetime sandbox call quota", कहीं "unlimited test-mode calls"), इसलिए अपनी योजना बनाते समय मान्य सीमा pricing पन्ने से ही पक्की कर लीजिए। साथ ही sandbox बनाम production keys वाला गाइड पढ़ लीजिए।

Sandbox में क्या टेस्ट करें

सहज ट्रेड कनेक्ट जैसे पोर्टल के लिए एक छोटी टेस्ट सूची बनाइए:

1. चारों endpoints पर दस्तावेज़ वाले नमूना मान से "सही" रास्ता चलाइए।
2. जानबूझकर गलत format भेजिए और 400 के लिए फ़ॉर्म का संदेश जाँचिए।
3. key से एक scope हटाकर 403 वाला रास्ता जाँचिए।
4. एक नकली "नहीं मिला" नतीजे पर अपना NOT_FOUND वाला रास्ता चलाइए। इसे अपने कोड में mock कीजिए ताकि आपका नियम परखा जा सके।
5. timeout और 502 के मामले को भी mock से टेस्ट कीजिए, ताकि आवेदन "जाँच बाकी" में जाए और खारिज न हो।

Production में जाने से पहले

पहले जाँच लीजिए कि production की key अलग है और केवल बैकएंड के secret manager में रखी है। फिर wallet का शेष देखिए, क्योंकि 402 पर आपके आवेदक अटकेंगे। फिर निगरानी लगाइए: हर endpoint पर 4xx और 5xx की गिनती, और 402 या 429 आने पर अलर्ट। आख़िर में पहले कुछ दिन ऑटो-अप्रूव बंद रखिए, और जाँचिए कि असली आवेदनों पर नतीजे आपकी उम्मीद के हिसाब से आ रहे हैं। Production की पहुँच पाने के चरण developer onboarding verification policy और आपके डैशबोर्ड में बताए गए हैं।

Postman और MCP

अगर टीम कोड लिखने से पहले हाथ से कुछ call आज़माना चाहती है, तो Postman collection तैयार है। AI टूल के साथ काम करने वालों के लिए MCP server का पन्ना और build-with-ai मददगार हैं। यहाँ भी sandbox key ही इस्तेमाल कीजिए।

कब इस्तेमाल करें, कब नहीं

हर टूल हर जगह सही नहीं बैठता। नीचे उन स्थितियों की साफ़ सूची है जहाँ ये endpoints उपयोगी हैं, और जहाँ नहीं।

कब इस्तेमाल करें

• आपके पोर्टल पर नए सप्लायर, डीलर या वेंडर जुड़ते हैं और आप उनके नंबर असली स्रोत से मिलाना चाहते हैं।
• आपको आवेदक की कंपनी की स्थिति और उसके directors एक नज़र में चाहिए।
• आप ऑपरेशंस टीम का हाथ से सर्टिफिकेट मिलाने का समय घटाना चाहते हैं।
• आवेदक के पास सिर्फ़ PAN है और आपको उससे जुड़े GSTIN या Udyam खोजने हैं।
• आप साल में एक बार पुराने सप्लायरों की स्थिति दोबारा जाँचना चाहते हैं (अपनी रफ़्तार की सीमा के अंदर)।

कब नहीं (या सावधानी से)

• आप किसी की क्रेडिट-योग्यता या भुगतान की क्षमता जानना चाहते हैं। ये endpoints सिर्फ़ रजिस्ट्रेशन-जानकारी देते हैं, भुगतान-व्यवहार नहीं।
• आपको बैंक खाते की जाँच चाहिए। उसके लिए अलग bank-account endpoint है, उसका दस्तावेज़ देखिए।
• आप सिर्फ़ एक API के भरोसे कोई बड़ा कानूनी या वित्तीय फ़ैसला लेना चाहते हैं। नतीजे को अपनी नीति और सलाहकार की राय के साथ जोड़िए।
• आपको API के जवाब को सार्वजनिक रूप से किसी व्यक्ति के नाम के साथ दिखाना है। ऐसा करने से पहले गोपनीयता की शर्तें जाँचिए।
• आप जवाब की गारंटी चाहते हैं कि "यह कारोबार भरोसेमंद है।" API ऐसी गारंटी नहीं देती।

KYC से तुलना

अगर आपका काम व्यक्तियों के KYC का है, जैसे NBFC या फिनटेक में ग्राहक जोड़ना, तो वह अलग तरह का प्रवाह है। उसका ब्योरा fintech और NBFC के KYC वाले use-case में है। इस गाइड का केंद्र कारोबार और कंपनी की पहचान है।

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

StampMitra, Bani Global Industries LLP (LLPIN ACI-6373) का चलाया हुआ एक प्राइवेट LegalTech प्लेटफ़ॉर्म है। यह कोई सरकारी एजेंसी या लॉ फ़र्म नहीं है, और यहाँ दी गई बातें सामान्य जानकारी हैं, कानूनी सलाह नहीं।

आज की तारीख़ में StampMitra की developer API आपको इतना देती है। एक ही base URL पर पाँच कारोबार-जाँच endpoints मिलते हैं: gstin, cin, udyam, pan-to-gstin और pan-to-udyam। सबकी authentication एक जैसी है, यानी Bearer key या x-api-key। हर endpoint का scope अलग है, इसलिए आप key को उतने ही अधिकार दे सकते हैं जितने ज़रूरी हों। जवाबों का आकार स्थिर और दस्तावेज़ में दर्ज है, और हर जवाब में एक referenceId आता है जिसे आप अपने ऑडिट-रिकॉर्ड में रख सकते हैं। सभी errors एक ही { error: { code, message, requestId } } आकार में आते हैं, जिससे आपकी error-handling एक ही जगह लिखी जा सकती है।

कीमत सीधी रखी गई है। Sandbox में मुफ़्त टेस्ट होता है, और production में हर सफल call पर तय दर से wallet से कटता है। GSTIN के लिए आज की दर ₹5 रुपये प्रति सफल call है, और बाकी endpoints की दरें pricing पन्ने पर हैं। नकारात्मक नतीजा (जैसे found: false) भी पूरी verification होने की वजह से गिना जाता है, इसलिए पहले अपनी तरफ़ से format जाँचना पैसे बचाता है।

आपके काम के लिए कुछ और पन्ने: ज़्यादा ब्योरे के लिए सभी products की सूची, एक-एक endpoint पर GSTIN, CIN और Udyam के उत्पाद-पन्ने, और वेबहुक की जानकारी के लिए webhooks पन्ना। इन्हें टीम के साथ बाँटिए।

आगे क्या (केवल योजना)

हम इन चीज़ों पर काम करने की सोच रहे हैं, पर ये आज उपलब्ध वादा नहीं हैं: इस तरह के कारोबार-जाँच के नतीजों को एक ही संयुक्त जवाब में जोड़ने का आसान तरीका, और आपके ऑनबोर्डिंग प्रवाह के उदाहरणों का और बड़ा संग्रह। जब कोई चीज़ उपलब्ध होगी, तो वह दस्तावेज़ों और products के पन्नों पर दर्ज होगी। तब तक ऊपर दिए तरीके से, यानी अपने बैकएंड में नियम लिखकर, इन endpoints को जोड़िए।

शुरू करने के लिए मुफ़्त sandbox key बनाइए, पहले GSTIN पर एक call चलाइए, फिर अपने सप्लायर-फ़ॉर्म के हर रास्ते पर ऊपर की तालिका के मुताबिक़ endpoint जोड़ते जाइए। अटकें तो [email protected] पर requestId के साथ लिखिए।

API reference एक नज़र में

{
  "referenceId": "SMV-20260927-6R38Y3",
  "valid": true,
  "companyName": "JANE DOE ENTERPRISES PRIVATE LIMITED",
  "incorporationDate": "2015-03-12",
  "cinStatus": "ACTIVE",
  "companyStatus": "Active",
  "directors": [
    {
      "din": "01234567",
      "name": "RAHUL KUMAR",
      "designation": "Director"
    }
  ],
  "email": "[email protected]",
  "registrationNumber": "U74999DL2015PTC284009",
  "incorporationCountry": "India"
}

{
  "referenceId": "SMV-20260927-5U29V7",
  "found": true,
  "udyamStatus": "Active",
  "enterpriseName": "Jane Doe Enterprises",
  "enterpriseType": "Proprietorship",
  "organizationType": "Micro",
  "certificateUrl": "https://udyamregistration.gov.in/Udyam_Download/UDYAM-MH-12-1234567.pdf"
}

{
  "referenceId": "SMV-20260927-9K21P4",
  "GSTIN": "07AAAAA1111A1Z1",
  "valid": true,
  "legalName": "Jane Doe Enterprises Private Limited",
  "tradeName": "Jane Doe Enterprises",
  "registrationStatus": "Active",
  "principalPlaceOfBusiness": "123, MG Road, Bengaluru, Karnataka, 560001",
  "message": "GSTIN Exists"
}

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