GSTIN वेरिफिकेशन API: GST नंबर वेरिफाई करने की पूरी गाइड

मुख्य बातें

• GSTIN जाँच का endpoint POST /v1/verify/gstin है। ज़रूरी field gstin (15 कैरेक्टर), वैकल्पिक field businessName।
• API key पर verification.gstin.read scope होना चाहिए। PAN से GSTIN खोजने के लिए verification.pan_to_gstin.read चाहिए।
• Authorization header में Bearer <api-key> भेजें। x-api-key header भी चलता है। sandbox key sk_test_ से और production key sk_live_ से शुरू होती है।
• सफल जवाब में referenceId, GSTIN, valid, legalName, tradeName, registrationStatus, principalPlaceOfBusiness और message मिलते हैं।
• गलत format का GSTIN सीधे 400 error देता है। उसे verification के लिए भेजा ही नहीं जाता।
• valid: false वाला जवाब भी पूरा हुआ और billable verification माना जाता है। इसलिए पहले अपने सर्वर पर format जाँचें।
• referenceId StampMitra का अपना transaction id है, idempotency key नहीं। इसे अपने रिकॉर्ड में audit के लिए रखें।
• हर endpoint पर rate limit है। उदाहरण वाले error में 60 सेकंड में 60 requests लिखा है, इसलिए बैच चलाते समय गति नियंत्रित रखें।
• GSTIN कारोबार की सार्वजनिक पहचान है, पर साथ में आया नाम, पता और स्थिति आपके रिकॉर्ड में पहुँचकर आपकी ज़िम्मेदारी बन जाती है। उतना ही रखें जितना ज़रूरी है।

मंडीलाइन की कहानी: वेंडर onboarding में GSTIN क्यों अटकता है?

मान लीजिए "मंडीलाइन" नाम का एक काल्पनिक B2B मार्केटप्लेस है, जहाँ थोक व्यापारी किराना, पैकेजिंग और स्टेशनरी का माल बेचते हैं। हर नए वेंडर को साइन-अप के समय अपना GSTIN भरना होता है, ताकि खरीदार को GST वाला इनवॉइस मिल सके। शुरू में टीम ने बस एक टेक्स्ट बॉक्स रखा था, जिसमें कोई भी 15 अक्षर डाल सकता था।

तीन महीने बाद सपोर्ट टीम के पास तीन तरह की शिकायतें जमा हो गईं। पहली, कुछ वेंडरों ने टाइपो वाले नंबर भरे थे, इसलिए इनवॉइस पर गलत GSTIN छप गया और खरीदार का इनपुट क्रेडिट का मामला उलझ गया। दूसरी, कुछ वेंडर ऐसे निकले जिनका registration रद्द हो चुका था। तीसरी, एक वेंडर ने किसी और कारोबारी का GSTIN अपना बताकर भर दिया था।

इन तीनों की जड़ एक ही है: नंबर का रूप-रंग सही दिखना और नंबर का असली व चालू होना दो अलग बातें हैं। पहली बात अपना कोड जाँच सकता है। दूसरी बात के लिए रजिस्ट्री से पूछना पड़ता है, और वही काम GSTIN verification API करती है।

मंडीलाइन ने तय किया कि साइन-अप फ़ॉर्म में तीन परतें होंगी। पहली परत ब्राउज़र और सर्वर पर format जाँच। दूसरी परत API से verification। तीसरी परत नतीजे को देखकर अपना फ़ैसला: स्वीकार, मैनुअल रिव्यू, या अस्वीकार। इस पूरे लेख में हम यही तीन परतें बनाएँगे।

यह समस्या सिर्फ मार्केटप्लेस की नहीं है

यही ढाँचा लॉजिस्टिक्स कंपनी में ट्रांसपोर्टर जोड़ते समय, किसी सप्लाई-चेन ऐप में सप्लायर जोड़ते समय, या अकाउंटिंग सॉफ़्टवेयर में पार्टी मास्टर बनाते समय भी काम आता है। जहाँ कहीं आप किसी कारोबारी से GST नंबर लेकर उस पर भरोसा करते हैं, वहाँ यह जाँच जगह बनाती है। एनबीएफसी या फिनटेक के KYC वाले पहलू के लिए फिनटेक और NBFC के लिए KYC API वाला लेख देखें।

GSTIN में 15 कैरेक्टर का मतलब क्या है?

GSTIN यानी Goods and Services Tax Identification Number। CBIC की registration सामग्री के मुताबिक यह 15 कैरेक्टर का होता है, जिसे चार हिस्सों में पढ़ा जा सकता है।

हमारे sandbox उदाहरण 07AAAAA1111A1Z1 में शुरुआती 07 राज्य कोड है, बीच के AAAAA1111A PAN वाला हिस्सा है, और बाकी तीन कैरेक्टर entity व check वाले हैं। यह उदाहरण नकली है और असली किसी कारोबारी से इसका संबंध नहीं।

इससे आपको क्या फ़ायदा मिलता है?

सबसे काम की बात यह है कि GSTIN के बीच में PAN बैठा होता है। इसलिए अगर वेंडर का PAN आपके पास पहले से है (जैसे बैंक या KYC प्रक्रिया से), तो आप GSTIN के बीच के 10 कैरेक्टर से उसे मिला सकते हैं। यह एक सस्ती लोकल जाँच है। अगर वेंडर का भरा हुआ PAN और GSTIN के भीतर वाला PAN अलग हैं, तो API call करने से पहले ही आप उसे लौटा सकते हैं।

यह लोकल मिलान कोड में बस दो पंक्तियों का है। मान लीजिए वेंडर ने साइन-अप में अपना PAN भी भरा है:

function panMatchesGstin(pan, gstin) {
  return gstin.slice(2, 12) === pan.toUpperCase();
}

अगर यह false लौटाए तो समझ लीजिए कि वेंडर ने या तो PAN गलत भरा है या GSTIN किसी और कारोबारी का है। दोनों में से कौन सा, यह यहाँ पता नहीं चलता, इसलिए उपयोगकर्ता से साफ़ शब्दों में कहिए कि "PAN और GSTIN आपस में मेल नहीं खाते, कृपया दोनों दोबारा देखें"। ध्यान रहे कि यह मिलान सिर्फ नंबरों के आकार पर टिका है। असली पुष्टि के लिए तब भी API की call चाहिए।

एक चेतावनी: राज्य कोड की पूरी सूची और check कैरेक्टर की गणना का तरीका हम यहाँ नहीं दे रहे, क्योंकि हमने उसे किसी आधिकारिक स्रोत से इस लेख के लिए पुष्ट नहीं किया है। अपने कोड में राज्य कोड की तालिका लगानी हो तो GST पोर्टल की मौजूदा सूची से ही लें, और याद रखें कि सूची बदल सकती है।

हाथ से जाँच बनाम API: असली फ़र्क कहाँ है?

GST पोर्टल पर कोई भी व्यक्ति हाथ से किसी कारोबारी का नंबर खोजकर देख सकता है। जब हफ़्ते में दस वेंडर आते हैं, तो यह चल जाता है। जब रोज़ सौ वेंडर आने लगें, तो ऑपरेशंस टीम का एक आदमी पूरा दिन टैब बदलता रहता है, और गलती की संभावना बढ़ जाती है। हाथ की जाँच का कोई स्वचालित रिकॉर्ड भी नहीं बनता, जबकि API हर बार referenceId देती है जिसे आप अपने रिकॉर्ड से जोड़ सकते हैं।

मंडीलाइन के लिए असली बदलाव गति का नहीं, निरंतरता का था। अब हर वेंडर पर वही नियम लागू होता है, चाहे सोमवार सुबह हो या रविवार की रात। इससे "इसे तो हमने देख लिया था" जैसी अनिश्चितता खत्म हुई।

सिर्फ format जाँचना काफ़ी क्यों नहीं है?

कई टीमें regex लिखकर मान लेती हैं कि काम हो गया। regex बस इतना बताता है कि स्ट्रिंग का आकार GSTIN जैसा है। वह यह नहीं बताता कि यह नंबर किसी को जारी हुआ भी है, किसका है, और अभी चालू है या नहीं।

दोनों साथ क्यों रखें?

क्योंकि हर API call पर आपकी लागत आती है और स्टेटस बैलेंस से कटता है। StampMitra का endpoint भी format की गलती पर तुरंत 400 लौटा देता है, पर आपका अपना regex उपयोगकर्ता को फ़ॉर्म में ही तुरंत बता देता है, नेटवर्क के चक्कर के बिना। इसलिए सही क्रम यह है: पहले अपना format जाँच, फिर API।

StampMitra का GSTIN endpoint कैसे काम करता है?

यह endpoint POST https://api-b2b.stampmitra.in/v1/verify/gstin पर है। आप JSON body भेजते हैं और अपनी API key Authorization header में देते हैं। GSTIN product का पन्ना और GSTIN का API reference में यही जानकारी मौजूद है।

Request के पैरामीटर

Response के field

सफल जवाब का असली रूप कुछ इस तरह का है:

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

ध्यान दें कि जवाब में GSTIN वाला field बड़े अक्षरों में GSTIN है, जबकि request में छोटे अक्षरों में gstin। अपने कोड में यह फ़र्क गलती से न बिगाड़ें।

referenceId का रूप SMV-YYYYMMDD-XXXXXXX है और यह हर call में मिलता है, valid: false वाले जवाब में भी। इसे अपने डेटाबेस में रखिए, ताकि बाद में किसी विवाद या ऑडिट में दिखा सकें कि फलाँ तारीख को फलाँ जाँच हुई थी।

Scope और मीटरिंग

API key पर verification.gstin.read scope होना चाहिए, वरना 403 आता है। usage तब दर्ज होती है जब verification सफलतापूर्वक पूरी हो जाए, और production में priced services के लिए fulfilment wallet से पैसा कटता है। इस endpoint की प्रति call कीमत अभी ₹5 है। यह मान हमेशा pricing पन्ने पर देखें, क्योंकि दरें बदल सकती हैं।

पहली call: cURL से GSTIN जाँचें

पहले अपनी key पर्यावरण चर में रखें। key को कोड में सीधे न लिखें। नया खाता बनाने और key पाने के लिए quickstart देखें।

export STAMPMITRA_API_KEY="sk_test_xxxxxxxxxxxx"

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

ऊपर businessName वैकल्पिक है, इसलिए सिर्फ gstin भेजना भी ठीक है। अगर आपको जवाब में 401 दिखे तो header की वर्तनी और key की जाँच करें। 403 दिखे तो वह key बनाते समय verification.gstin.read scope चुना गया था या नहीं, यह देखें। API keys पर लेख में scope और IP allowlist की बात है।

खराब नंबर भेजने पर क्या दिखता है?

अगर gstin का आकार गलत है, तो endpoint verification करने ही नहीं जाता और सीधे यह error देता है:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "gstin must match the format 07AAAAA1111A1Z1",
    "requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
  }
}

यह API का हर error एक ही ढाँचे में आता है: error.code, error.message, error.requestId। सपोर्ट को लिखते समय requestId ज़रूर दें। आपके लॉग में इसे संभालकर रखना बाद में समय बचाता है।

जवाब की स्थिति कोड में कैसे पढ़ें?

ऊपर के cURL जवाब से तीन बातें पहले निकालिए: HTTP status, valid और registrationStatus। इन तीन से ही ज़्यादातर फ़ैसले हो जाते हैं। बाकी field, यानी नाम और पता, मिलान और रिकॉर्ड के काम आते हैं। एक आम आदत यह है कि res.ok देखे बिना सीधे data.valid पढ़ लिया जाए। error की हालत में बॉडी का आकार अलग होता है (error वाला), इसलिए data.valid तब undefined निकलेगा, और if (!data.valid) जैसी शर्त गलती से वेंडर को अस्वीकृत कर देगी। इसी जाल से बचने के लिए नीचे के कोड में पहले status जाँचा गया है।

Node.js में वेंडर onboarding का फ़ंक्शन

अब मंडीलाइन के साइन-अप वाले सर्वर पर लौटते हैं। नीचे का कोड Node.js 18 या उससे नए संस्करण के built-in fetch पर चलता है। इसमें दो परतें हैं: पहले format जाँच, फिर API call।

// vendor-gstin.js
const API = "https://api-b2b.stampmitra.in/v1/verify/gstin";
const GSTIN_SHAPE = /^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z]{3}$/;

export async function verifyVendorGstin(gstin, businessName) {
  const cleaned = String(gstin).trim().toUpperCase();

  if (!GSTIN_SHAPE.test(cleaned)) {
    return { ok: false, reason: "FORMAT" };
  }

  const res = await fetch(API, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STAMPMITRA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ gstin: cleaned, businessName }),
  });

  const data = await res.json();

  if (!res.ok) {
    return {
      ok: false,
      reason: "API_ERROR",
      status: res.status,
      code: data.error?.code,
      requestId: data.error?.requestId,
    };
  }

  return {
    ok: true,
    referenceId: data.referenceId,
    valid: data.valid,
    status: data.registrationStatus,
    legalName: data.legalName,
    tradeName: data.tradeName,
    address: data.principalPlaceOfBusiness,
  };
}

इस कोड में regex जानबूझकर सिर्फ आकार जाँचता है, राज्य कोड की सूची या check कैरेक्टर नहीं। वजह ऊपर बताई जा चुकी है: जो चीज़ हमने आधिकारिक स्रोत से पक्की नहीं की, उसे यहाँ हार्डकोड नहीं किया।

साइन-अप route में इसे कैसे जोड़ें?

मंडीलाइन का बैकएंड Express पर है। नीचे का route ऊपर वाले फ़ंक्शन को बुलाता है और नतीजे को तीन में से एक फ़ैसले में बदलता है। ध्यान दें कि API के error वाले हाल में हम वेंडर को "अस्वीकृत" नहीं, "जाँच बाकी" दिखाते हैं।

import express from "express";
import { verifyVendorGstin } from "./vendor-gstin.js";
import { nameLooksSame } from "./names.js";

const app = express();
app.use(express.json());

app.post("/vendors/signup", async (req, res) => {
  const { gstin, businessName } = req.body;
  const r = await verifyVendorGstin(gstin, businessName);

  if (!r.ok && r.reason === "FORMAT") {
    return res.status(422).json({ message: "GSTIN का आकार सही नहीं है" });
  }
  if (!r.ok) {
    // 402, 429, 502 वगैरह: वेंडर की गलती नहीं
    await saveCheck({ gstin, decision: "PENDING", requestId: r.requestId });
    return res.status(202).json({ message: "जाँच बाकी है, हम जल्द बताएँगे" });
  }

  let decision = "REJECT";
  if (r.valid && r.status === "Active") {
    decision = nameLooksSame(businessName, r.legalName, r.tradeName)
      ? "ACCEPT"
      : "REVIEW";
  } else if (r.valid) {
    decision = "REVIEW";
  }

  await saveCheck({ gstin, decision, referenceId: r.referenceId, status: r.status });
  return res.json({ decision });
});

saveCheck आपका अपना फ़ंक्शन है जो ऊपर बताई गई जाँच-इतिहास टेबल में पंक्ति डालता है। उपयोगकर्ता को वापस भेजे जवाब में पूरा नाम या पता न लौटाएँ, जब तक फ़ॉर्म में उसकी सच में ज़रूरत न हो।

इस फ़ंक्शन के बारे में तीन बातें

पहली, वापसी में हमने referenceId शामिल किया ताकि कॉल करने वाला उसे वेंडर के रिकॉर्ड के साथ सहेज सके। दूसरी, API error की हालत में हम code और requestId लौटाते हैं, पूरा error बॉडी नहीं, ताकि लॉग में अनजाने में ज़्यादा डेटा न जाए। तीसरी, key केवल process.env से पढ़ी जा रही है, इसलिए वह रिपॉज़िटरी में नहीं जाएगी।

अगर आप अपने ऐप में SDK इस्तेमाल करना चाहें तो SDKs का पन्ना देखें, पर ऊपर का सीधा fetch हर जगह चल जाता है।

Python में पुराने वेंडरों की बैच जाँच

मंडीलाइन के पास साइन-अप के बाद पुराने वेंडर भी थे, जिनके GSTIN कभी जाँचे नहीं गए थे। टीम ने तय किया कि हर रात कुछ सौ रिकॉर्ड दोबारा देखे जाएँगे। यहाँ rate limit का ध्यान रखना पड़ता है। हमारे API के उदाहरण वाले 429 error में संदेश है कि इस endpoint पर 60 सेकंड में 60 requests की सीमा लागू है, इसलिए नीचे का कोड प्रति सेकंड एक call से तेज़ नहीं चलता।

# recheck_vendors.py
import os
import time
import requests

URL = "https://api-b2b.stampmitra.in/v1/verify/gstin"
HEADERS = {
    "Authorization": f"Bearer {os.environ['STAMPMITRA_API_KEY']}",
    "Content-Type": "application/json",
}

def check(gstin, name=None):
    body = {"gstin": gstin}
    if name:
        body["businessName"] = name
    r = requests.post(URL, headers=HEADERS, json=body, timeout=20)
    return r.status_code, r.json()

def run(vendors):
    results = []
    for v in vendors:
        status, data = check(v["gstin"], v.get("name"))
        if status == 429:
            time.sleep(60)
            status, data = check(v["gstin"], v.get("name"))
        results.append({"vendor_id": v["id"], "http": status, "body": data})
        time.sleep(1.1)
    return results

if __name__ == "__main__":
    sample = [{"id": 1, "gstin": "07AAAAA1111A1Z1", "name": "Jane Doe Enterprises"}]
    for row in run(sample):
        print(row)

बैच के नतीजे कैसे जाँचें?

रात की बैच खत्म होने पर सबसे पहले यह देखिए कि कितनी पंक्तियाँ 200 के बजाय किसी और कोड के साथ लौटीं। अगर 402 कई बार दिखे तो wallet खाली हो चुका है और बाकी कॉल बेकार जाएँगी, इसलिए बैच को वहीं रोकना बेहतर है। अगर बहुत सारे 429 दिखें तो आपकी गति तय सीमा से ऊपर है और sleep का मान बढ़ाना होगा।

दूसरी चीज़ वे वेंडर हैं जिनकी registrationStatus अब Active नहीं रही। इनकी एक अलग सूची बनाकर ऑपरेशंस टीम को भेजिए, ताकि वे उनके नए ऑर्डर कुछ समय के लिए रोक सकें। ऑर्डर रोकना या न रोकना व्यवसाय का फ़ैसला है, और बेहतर यही है कि इसे स्वचालित कार्रवाई की जगह इंसानी मंज़ूरी के बाद लागू किया जाए।

तीसरी, हर बैच के आखिर में एक छोटा सारांश लॉग करें: कुल कितने वेंडर, कितने सफल, कितने valid: false, कितने 429, कितने 502। हफ़्ते भर का यह सारांश देखकर आप समझ पाएँगे कि कहीं कोई पैटर्न तो नहीं बन रहा।

बैच चलाते समय सावधानियाँ

हर रात सब वेंडरों को दोबारा जाँचने की ज़रूरत नहीं होती, क्योंकि हर call का पैसा लगता है। जोखिम के हिसाब से छाँटिए: बड़े ऑर्डर वाले वेंडर, हाल में बैंक खाता बदलने वाले वेंडर, या जिनका आखिरी चेक बहुत पुराना हो गया है। चेक कितने अंतराल पर दोहराना है, यह आपकी अपनी जोखिम नीति और अनुपालन टीम का फ़ैसला है, API का नहीं।

यह भी याद रखें कि 429 पर इंतज़ार करना काम चलाऊ तरीका है। असली प्रोडक्शन सिस्टम में कतार (queue) और रिट्राई की सीमा रखना बेहतर रहता है। त्रुटियों को संभालने के पैटर्न API errors और handling वाले गाइड में विस्तार से हैं।

नतीजा पढ़कर फ़ैसला कैसे लें?

API आपको तथ्य देती है, फ़ैसला आपका सिस्टम लेता है। मंडीलाइन ने अपने नियम इस तरह लिखे, जो आप अपने हिसाब से बदल सकते हैं।

अंतिम पंक्ति सबसे अहम है। 502 या 429 का मतलब यह नहीं कि वेंडर का GSTIN गलत है। इसका मतलब बस इतना है कि जाँच पूरी नहीं हो सकी। ऐसे में वेंडर की स्थिति "जाँच बाकी" रखें, न कि "अस्वीकृत"।

वेंडर को संदेश कैसे दिखाएँ?

नतीजे जितने सटीक हों, वेंडर को दिखाया जाने वाला संदेश उतना ही सावधान होना चाहिए। "आपका GSTIN फ़र्ज़ी है" जैसा वाक्य कभी न लिखें, क्योंकि valid: false का मतलब बस इतना है कि हमारी जाँच में यह नंबर नहीं मिला। इसके पीछे टाइपो, नया registration या कोई और कारण हो सकता है।

इस तरह के संदेश दो फ़ायदे देते हैं: सही वेंडर नाराज़ नहीं होते, और आप ऐसा कोई दावा नहीं करते जिसे साबित न कर सकें।

registrationStatus के मान

हमारे दस्तावेज़ में registrationStatus का उदाहरण Active है। दूसरे मानों की पूरी सूची api-products वाले दस्तावेज़ में नहीं दी गई है, इसलिए हम उन्हें यहाँ गिनाएँगे नहीं। अपने कोड में Active से सीधी तुलना रखें और बाकी हर मान को "ध्यान से देखो" वाली श्रेणी में डालें। यह तरीका सुरक्षित है, क्योंकि कोई नया मान आए तो भी वेंडर अपने आप पास नहीं होगा।

businessName से मिलान कैसे करें?

businessName वैकल्पिक field है और इसका काम "मिलान के लिए नाम" देना है। हमारे दस्तावेज़ में जवाब का जो उदाहरण है, उसमें अलग से कोई match-score वाला field नहीं दिखता। इसलिए सुरक्षित रास्ता यह है कि आप जवाब के legalName और tradeName को अपने कोड में खुद भी मिलाएँ, और सिर्फ किसी एक field पर निर्भर न रहें।

नाम मिलाते समय सामान्य दिक्कतें

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

function normalise(name) {
  return String(name || "")
    .toLowerCase()
    .replace(/&/g, " and ")
    .replace(/\bpvt\b/g, "private")
    .replace(/\bltd\b/g, "limited")
    .replace(/[^a-z0-9 ]/g, " ")
    .replace(/\s+/g, " ")
    .trim();
}

export function nameLooksSame(entered, legalName, tradeName) {
  const e = normalise(entered);
  return [legalName, tradeName].some((n) => {
    const x = normalise(n);
    return x && (x === e || x.includes(e) || e.includes(x));
  });
}

यह सिर्फ एक सरल नियम है। यह किसी को "धोखेबाज़" साबित नहीं करता। नाम न मिलने पर सबसे अच्छा कदम इंसानी रिव्यू है: कई सही कारोबारी ट्रेड नाम और कानूनी नाम अलग रखते हैं।

PAN है, GSTIN नहीं: pan-to-gstin का इस्तेमाल

कभी-कभी वेंडर पहले अपना PAN देता है और GSTIN बाद में, या आप किसी कंपनी की सभी GST registration गिनना चाहते हैं। इस हाल में POST /v1/verify/pan-to-gstin काम आता है। इसमें सिर्फ pan ज़रूरी है, और key पर verification.pan_to_gstin.read scope चाहिए। इसकी प्रति call कीमत ₹5 है। विस्तार के लिए 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" }
  ]
}

यहाँ found बताता है कि कुछ मिला या नहीं, और gstins एक सूची है, जिसकी हर प्रविष्टि में gstin, state और status हैं। एक PAN पर अलग-अलग राज्यों के कई GSTIN हो सकते हैं, इसलिए इसे सूची की तरह ही संभालें, एक मान की तरह नहीं।

दोनों endpoints को कैसे जोड़ें?

मंडीलाइन ने onboarding को दो रास्तों में बाँटा। जिस वेंडर ने GSTIN दिया, उसके लिए सीधे gstin endpoint। जिसने सिर्फ PAN दिया, उसके लिए पहले pan-to-gstin, फिर सूची में से उस राज्य का GSTIN चुनकर gstin endpoint पर पूरी जानकारी। एक वेंडर के लिए दो call का मतलब दो बार लागत, इसलिए जहाँ वेंडर खुद GSTIN दे सकता है वहाँ पहला रास्ता ही रखें।

कई राज्यों वाले वेंडर का क्या करें?

मान लीजिए मंडीलाइन का एक वेंडर दिल्ली और महाराष्ट्र दोनों में माल रखता है। उसके पास एक ही PAN पर दो अलग GSTIN होंगे, जिनके शुरुआती दो अंक अलग होंगे। pan-to-gstin का जवाब दोनों दिखाएगा। अब सवाल यह है कि इनवॉइस पर कौन सा GSTIN जाएगा। इसका जवाब माल कहाँ से भेजा जा रहा है और खरीदार कहाँ है, इस पर निर्भर करता है, और यह टैक्स का सवाल है, जिसे अपने CA या कर सलाहकार से तय कीजिए।

तकनीकी तौर पर आप वेंडर के प्रोफ़ाइल में एक से ज़्यादा GSTIN का रिकॉर्ड रख सकते हैं, हर एक के साथ अपनी reference_id और स्थिति। इससे एक राज्य का registration रद्द होने पर बाकी राज्यों का कारोबार अपने आप ठप नहीं होता। वेंडर की सूची में status देखकर आप यह भी समझ सकते हैं कि कौन सा GSTIN चालू है।

लागत पर काबू कैसे रखें?

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

PAN की जाँच के लिए अलग गाइड भी है: PAN verification API। और GSTIN के साथ CIN व Udyam को मिलाकर पूरे कारोबार की जाँच के लिए बिज़नेस वेरिफिकेशन: GSTIN, CIN, Udyam पढ़ें।

आम गलतियाँ और error कैसे सुलझाएँ?

नीचे की तालिका में वे HTTP status हैं जो इस endpoint के दस्तावेज़ में दर्ज हैं।

गड़बड़ी हो तो किस क्रम में जाँचें?

जब कोई वेंडर कहे कि "मेरा सही GSTIN रिजेक्ट हो गया", तो एक छोटा क्रम अपनाइए। पहले अपने लॉग में उसकी requestId या referenceId ढूँढिए। फिर देखिए कि API ने कौन सा HTTP status दिया था। अगर 400 था, तो भेजा गया स्ट्रिंग असल में क्या था, उसमें खाली जगह, O और 0 का घालमेल, या I और 1 का घालमेल तो नहीं। अगर 200 के साथ valid: false था, तो वेंडर से नंबर की तस्वीर (उसके registration प्रमाणपत्र से) मँगवाकर अक्षर-अक्षर मिलाइए।

अगर 402, 429 या 502 था तो वेंडर की कोई गलती नहीं, उसका मामला "जाँच बाकी" में जाना चाहिए था। अगर आपके सिस्टम ने उसे अस्वीकृत दिखा दिया था, तो असली बग आपके कोड में है। इस मामले को ठीक करके वेंडर को बताइए और उसकी जाँच दोबारा चलाइए। इसके बाद भी बात न बने तो requestId के साथ [email protected] पर लिखिए।

हमारे देखे हुए ठोस जाल

पहला जाल, GSTIN के आसपास की खाली जगह या छोटे अक्षर। स्प्रेडशीट से कॉपी किए गए नंबर में अक्सर पीछे खाली जगह चिपकी होती है, इसलिए trim() और toUpperCase() हमेशा लगाएँ।

दूसरा जाल, valid: false को "API फेल" मान लेना। यह API की असफलता नहीं, एक पूरा किया गया जवाब है, और इसकी भी गिनती होती है। इसलिए एक ही गलत नंबर पर उपयोगकर्ता से बार-बार call न करवाएँ, पहले format जाँच और फिर उपयोगकर्ता से एक बार नंबर दोबारा देखने को कहें।

तीसरा जाल, referenceId को idempotency key समझना। यह वैसा नहीं है। अगर आपका सर्वर timeout के बाद वही अनुरोध दोहराता है, तो दूसरी call अलग verification गिनी जा सकती है, इसलिए अपने पक्ष में डुप्लिकेट रोकने का तरीका बनाएँ, जैसे एक ही GSTIN की जाँच को कुछ मिनट के लिए कैश करना।

चौथा जाल, 502 को स्थायी नतीजा मान लेना। यह अस्थायी समस्या है। वेंडर को "जाँच बाकी" दिखाएँ और कुछ देर बाद फिर कोशिश करें।

GSTIN डेटा के साथ security और अनुपालन में क्या ध्यान रखें?

GSTIN, कारोबार का नाम और पता आम तौर पर सार्वजनिक कारोबारी जानकारी माना जाता है, पर एक प्रोप्राइटरशिप के मामले में कारोबार और व्यक्ति के बीच की रेखा धुंधली हो जाती है। जब किसी व्यक्ति के नाम पर चल रहे कारोबार का पता आपके रिकॉर्ड में आता है, तो उसे निजी डेटा की तरह सँभालना समझदारी है। यह कानूनी सलाह नहीं है, सामान्य जानकारी है। अपने मामले में Digital Personal Data Protection Act, 2023 कैसे लागू होता है, यह किसी योग्य वकील या अनुपालन सलाहकार से पूछिए।

व्यावहारिक अच्छी आदतें

पहली, उद्देश्य तय रखें। आप GSTIN इसलिए जाँच रहे हैं कि वेंडर की पहचान और कर-पंजीकरण की स्थिति सही है। उसी काम के लिए डेटा रखें, किसी और मकसद (जैसे मार्केटिंग) के लिए नहीं।

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

तीसरी, कम से कम रखें। हर बार पूरा JSON जवाब रखना ज़रूरी नहीं। अक्सर referenceId, valid, registrationStatus, जाँच की तारीख और अंतिम फ़ैसला काफ़ी होता है। जितना कम रखेंगे, उतना कम खतरा होगा।

चौथी, API key की सुरक्षा। key सिर्फ सर्वर पर रखें, ब्राउज़र या मोबाइल ऐप में नहीं। संवेदनशील scope के लिए IP allowlist लगाई जा सकती है, यह API keys के दस्तावेज़ में है। लॉग में key कभी न छापें।

पाँचवीं, उपयोग की सीमा। StampMitra के API स्वीकार्य उपयोग नीति, Developer Privacy Policy, API Security Policy और Data Processing Addendum को अपनी टीम के साथ एक बार पढ़ लें। इनसे पता चलता है कि कौन सा उपयोग मान्य है और डेटा कैसे संभाला जाता है।

दस्तावेज़ों में असली नंबर न डालें

अपने टिकट, चैट या सार्वजनिक रिपॉज़िटरी में असली वेंडर का GSTIN न चिपकाएँ। टेस्ट और ट्यूटोरियल में 07AAAAA1111A1Z1 जैसे नकली मान काम में लें।

Sandbox में टेस्ट करें, फिर production जाएँ

साइन-अप के बाद आपको तुरंत sk_test_ वाली sandbox key मिल जाती है। pricing पन्ने के अनुसार sandbox की call sandbox डेटा पर चलती है और आपके wallet से कुछ नहीं काटती। यानी अपना पूरा onboarding फ़्लो बिना खर्च के बना सकते हैं। sandbox की मात्रा-सीमा के शब्द हमारी साइट पर अलग-अलग जगह अलग हैं, इसलिए अपनी सीमा का सटीक ब्यौरा अपने खाते में या सपोर्ट से देखें।

ऑटोमेटेड टेस्ट कैसे लिखें?

हर टेस्ट में असली API बुलाना ज़रूरी नहीं। अपने verifyVendorGstin को टेस्ट करते समय fetch को नकली (mock) जवाब से बदल दीजिए, और ऊपर दिखाए गए असली JSON ढाँचे के आधार पर चार-पाँच स्थितियाँ बनाइए: सफल जवाब, valid: false, 400, 402 और 502। हर स्थिति पर देखिए कि फ़ैसला सही निकल रहा है या नहीं, खासकर यह कि 402 और 502 कभी REJECT में न बदलें। इन टेस्टों से आपको भरोसा रहता है कि कोड बदलने पर यह नियम चुपचाप नहीं टूटेगा।

उसके अलावा, एक छोटा integration टेस्ट sandbox key के साथ रखिए, जो हफ़्ते में एक बार चले। इससे पता चलेगा कि API के जवाब का रूप बदला तो नहीं। यह टेस्ट production key या असली वेंडर के नंबर के साथ कभी न चलाएँ।

टेस्ट की जाँच-सूची

• सही आकार का GSTIN भेजकर valid और बाकी field पढ़ने वाला कोड चलाएँ।
• जानबूझकर 14 कैरेक्टर का नंबर भेजकर 400 वाला रास्ता देखें।
• key हटाकर 401 और गलत scope वाली key से 403 का बर्ताव जाँचें।
• सूची वाले pan-to-gstin जवाब में एक से ज़्यादा प्रविष्टि वाली स्थिति के लिए अपना कोड पक्का करें।
• 429 और 502 पर आपका UI वेंडर को "अस्वीकृत" तो नहीं दिखा रहा, यह देखें।

ध्यान रखें कि sandbox का डेटा असली रजिस्ट्री का नहीं है, इसलिए असली वेंडर का नंबर वहाँ डालकर नतीजे पर भरोसा न करें।

Go-live से पहले की अंतिम जाँच

लॉन्च वाले दिन से पहले एक बार पूरी सूची पर नज़र डाल लीजिए। क्या key सिर्फ सर्वर के environment variable में है? क्या GSTIN और PAN लॉग में पूरे छपते हैं, और अगर हाँ तो क्या आप उन्हें आंशिक रूप से छिपा सकते हैं? क्या 402, 429 और 502 पर वेंडर को "जाँच बाकी" दिखता है? क्या वेंडर को साइन-अप के समय बता दिया गया है कि उसका GSTIN जाँचा जाएगा? और क्या आपकी टीम में कोई एक व्यक्ति तय है जो requestId के साथ सपोर्ट से बात करेगा?

अगर आपका कारोबार किसी नियामक के दायरे में है (जैसे NBFC), तो उनके अपने KYC व रिकॉर्ड रखने के नियम अलग हो सकते हैं। यहाँ दी गई सलाह उनकी जगह नहीं ले सकती, इसलिए अनुपालन टीम से पुष्टि कर लीजिए।

Production में जाने के कदम

production के लिए डैशबोर्ड से production access का आवेदन करना होता है। मंज़ूरी के बाद आप sk_live_ वाली production key बना सकते हैं, और हर सफल call की रकम API credit wallet से कटती है। जाने से पहले wallet में पर्याप्त शेष रखें, 402 की स्थिति पर अलर्ट लगाएँ, और key को अपने सीक्रेट मैनेजर में रखें। sandbox और production key का फ़र्क समझने के लिए sandbox बनाम production key वाला गाइड पढ़ें।

Go-live के बाद पहले कुछ दिन referenceId, HTTP status और requestId का लॉग देखते रहें। अनुमान से ज़्यादा 400 आएँ, तो अक्सर फ़ॉर्म की समस्या होती है, API की नहीं।

GSTIN verification API कब इस्तेमाल करें और कब नहीं?

तीन अलग परिस्थितियाँ, तीन अलग फ़ैसले

पहली परिस्थिति: एक छोटा थोक व्यापारी, जो पहली बार मंडीलाइन पर आया है और बस 20,000 रुपये के ऑर्डर की उम्मीद करता है। यहाँ gstin की एक call, नाम का मिलान और अपने नियम काफ़ी हो सकते हैं।

दूसरी परिस्थिति: एक बड़ी पैकेजिंग कंपनी, जिससे लाखों का रोज़ का माल लिया जाना है। यहाँ GSTIN की जाँच के साथ कंपनी का CIN, बैंक खाते का मिलान और अनुबंध की औपचारिकताएँ भी रखना समझदारी है। यह सब मिलाकर कैसे करें, यह GSTIN, CIN और Udyam वाले गाइड में है।

तीसरी परिस्थिति: एक वेंडर जिसका नाम और GSTIN का legalName बिल्कुल अलग निकले। यहाँ स्वचालित अस्वीकार की जगह इंसानी रिव्यू रखें, और वेंडर से registration प्रमाणपत्र माँगें। यह तरीका सही वेंडरों को बेवजह परेशान होने से बचाता है।

इसे किसी बड़ी जाँच का अकेला आधार न बनाएँ

GSTIN का चालू होना यह साबित नहीं करता कि कारोबार भरोसेमंद है, वेंडर की डिलीवरी अच्छी है, या उसका बैंक खाता सही है। यह सिर्फ एक परत है। भुगतान से पहले बैंक खाते की जाँच (हमारे पास bank-account endpoint है), कंपनी के लिए CIN, और छोटे कारोबार के लिए Udyam जैसी परतें साथ जोड़ी जा सकती हैं।

अपने सिस्टम में डेटा कैसे सहेजें?

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

निगरानी के लिए क्या गिनें?

production में जाने के बाद कुछ गिनतियाँ आपको जल्दी बता देती हैं कि कुछ बिगड़ रहा है। रोज़ की कुल call, 400 की दर, valid: false की दर, 402/429/502 की गिनती, और "जाँच बाकी" में अटके वेंडरों की संख्या। अगर "जाँच बाकी" वाली सूची दिन-ब-दिन लंबी हो रही है, तो या तो रिट्राई चल नहीं रही या upstream में कोई दिक्कत है।

एक और उपयोगी संकेत है wallet का शेष। चूँकि शेष कम होने पर 402 आने लगता है और वेंडर onboarding रुक जाता है, इसलिए शेष एक सीमा से नीचे जाते ही अपनी टीम को सूचना भेजिए। सीमा क्या हो, यह आपके औसत रोज़ के उपयोग से तय कीजिए।

पुरानी जाँच पर भरोसा कब न करें?

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

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

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

आज की तारीख़ में StampMitra Developers पर GSTIN से जुड़ी दो चीज़ें उपलब्ध हैं। पहली POST /v1/verify/gstin, जो gstin और वैकल्पिक businessName लेकर valid, legalName, tradeName, registrationStatus और principalPlaceOfBusiness जैसे field लौटाती है। दूसरी POST /v1/verify/pan-to-gstin, जो एक PAN से जुड़े GSTIN की सूची देती है। दोनों में Bearer API key, scope-आधारित अनुमति, सफल call पर ही मीटरिंग और हर जवाब में referenceId मिलता है। हर error एक ही { error: { code, message, requestId } } ढाँचे में आता है, जिससे आपका कोड सरल रहता है।

शुरू करने के लिए quickstart पर sandbox खाता बनाइए, GSTIN product पन्ना और API reference पढ़िए, और अगर आप AI की मदद से कोड लिखते हैं तो Build with AI और MCP के पन्ने देखिए। कोई अटकाव हो तो सपोर्ट पन्ने से या [email protected] पर लिखिए। लिखते समय अपनी requestId साथ दीजिए, इससे मामला जल्दी समझ आता है।

आगे की योजनाओं की बात करें तो हम दस्तावेज़ों में और उदाहरण, ज़्यादा भाषाओं में कोड के नमूने और जाँच के नतीजों से जुड़ी जानकारी को बेहतर बनाने पर काम करने की सोच रहे हैं। ये योजनाएँ हैं, वादे नहीं, और इनकी कोई तय तारीख़ हम नहीं बता रहे। आज क्या उपलब्ध है, उसकी सही सूची के लिए हमेशा products का पन्ना देखें।

API reference एक नज़र में

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

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

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