e-Stamp API India: catalogue से certificate तक का पूरा flow

मुख्य बातें

• पूरा flow आठ कदमों का है: catalogue, schema, राज्य और article की खोज, duty की जाँच और दाम, पक्षकार, order बनाना, पैसे का इंतज़ाम, और status के साथ certificate। पहले तीन कदम मुफ़्त lookups हैं।
• duty calculation और parties मीटर वाली calls हैं। जिन खातों में per-order fee चालू है, वहाँ order बनाना भी चार्ज हो सकता है। सरकारी duty और राज्य की procurement fee actuals पर आगे पास की जाती हैं, वे API fee का हिस्सा नहीं हैं।
• POST /v1/estamp/orders के लिए Idempotency-Key header ज़रूरी है। उसी key और उसी body से दोबारा भेजने पर पुराना जवाब ही लौटता है, और उसी key के साथ अलग body भेजने पर 422 IDEMPOTENCY_KEY_REUSED आता है।
• नया order vendor के पास नहीं, समीक्षा में पहुँचता है। उसकी शुरुआती status PENDING_REVIEW जैसी होती है और placement की पुष्टि operations का reviewer अलग से करता है।
• पैसा order बनते समय कटता है: duty Stamp Duty Wallet से (GST नहीं लगता) और procurement व convenience fee Service Fee Wallet से। कोई भी balance कम हो तो order ठुकरा दिया जाता है और कुछ नहीं बनता।
• certificate हर stamp के हिसाब से GET /v1/estamp/stamps/:stampId/certificate से मिलता है। जब तक वह नहीं आया, यह call HTTP 200 के साथ available: false देती है, और download link सिर्फ़ पाँच मिनट चलता है।
• sandbox key से कोई wallet नहीं कटता और वह नक़ली lifecycle चलाती है: order क़रीब तीस सेकंड में ISSUED हो जाता है और certificate watermark वाला नमूना होता है, इसलिए आप हर कदम मुफ़्त में परख सकते हैं। catalogue और दाम नमूना डेटा हैं, और असली समीक्षा का इंतज़ार व असली certificate देखने के लिए production का एक अभ्यास चाहिए।

e-Stamp API असल में क्या करती है और क्या आप पर छोड़ती है?

e-stamp एक इलेक्ट्रॉनिक certificate है जो काग़ज़ वाले stamp paper की जगह लेता है। उस पर एक unique certificate number होता है जिसे जारी करने वाली व्यवस्था से मिलाया जा सकता है, और वह किसी तय राज्य, उस राज्य की stamp सूची के किसी तय article और किसी तय duty रकम के लिए बनता है। हर राज्य में हर article electronic रूप में नहीं मिलता। state detail endpoint यह सीधे बता देता है: उसमें eStampAvailable और traditionalAvailable नाम के दो flags होते हैं। इसलिए आपका प्रोडक्ट शुरू में ही यूज़र को बता सकता है कि यह combination उपलब्ध नहीं है, आख़िरी स्क्रीन पर जाकर फ़ेल होने की ज़रूरत नहीं।

StampMitra की API इस प्रक्रिया का "ख़रीदने वाला" हिस्सा सँभालती है। एक API key से आप राज्यों और articles की सूची पढ़ सकते हैं, एक stamp line को vendor की कसौटी पर जाँच सकते हैं, order का दाम निकाल सकते हैं, order बना सकते हैं, उसे ट्रैक कर सकते हैं और certificate उतार सकते हैं। यह आपका एग्रीमेंट नहीं लिखती, यह तय नहीं करती कि कौन-सा article लगेगा, duty तय नहीं करती, दस्तख़त या registration नहीं करवाती, और कानूनी सलाह नहीं देती। सेवा की शर्तें साफ़ कहती हैं कि सही दस्तावेज़ श्रेणी और article चुनने की ज़िम्मेदारी और जमा करने से पहले transaction की जानकारी जाँचने की ज़िम्मेदारी आपकी है, और API जो रकम दिखाए वह उस लेन-देन पर लागू कानूनी ज़रूरत को नहीं बदलती।

इस बँटवारे से आपका design तय होता है। कानूनी सवाल और यूज़र से रिश्ता आपके प्रोडक्ट के पास रहता है। catalogue, service charges और GST का हिसाब, पैसे की आवाजाही और certificate की डिलीवरी API के पास। स्क्रीन बनाते समय कानूनी चुनाव (दस्तावेज़ का प्रकार, article, duty का आधार) किसी ऐसे इंसान के सामने रखें जो उनका जवाब दे सके, और बाक़ी सब API से validate करवाएँ।

एक किराएदारी की पूरी कहानी: आठ कदमों का नक्शा

कल्पना कीजिए कि इंदौर की एक काल्पनिक कंपनी "किरायानामा" अपने ऐप में leave and licence एग्रीमेंट stamp करवाती है। उसके backend को पहले यह देखना है कि कौन-सी service खुली है, फिर यूज़र से क्या-क्या पूछना है, फिर रकम का दाम, फिर order, फिर पैसा, फिर इंतज़ार। नीचे की तालिका वही नक्शा है, हर कदम के endpoint, scope और इस बात के साथ कि StampMitra उस call पर शुल्क लगाती है या नहीं।

product reference इन्हीं कदमों से मेल खाते आठ पन्नों में बँटा है: catalogue discovery, schema और options, राज्य, instrument और article की खोज, duty और value की गणना, parties, order बनाना, payment और order status व document। हर पन्ने पर वह गहराई मिलेगी जो यहाँ छोड़ दी गई है।

एक क्रम की बात। reference की timeline में parties, order से पहले दिखती है, पर parties वाला route order id माँगता है, इसलिए तार पर असल क्रम यह है: पहले order बनाइए, फिर parties जोड़ या सुधारिए। order की stamp lines में firstParty और secondParty पहले से रहते हैं, और certificate पर आम तौर पर यही नाम छपते हैं। parties route ग्राहक और दूसरे पक्ष की संपर्क जानकारी और सुधार के लिए है।

शुरू करने से पहले क्या चाहिए?

आपको चाहिए: e-Stamp चालू वाली organisation, सही scopes वाली API key, और production के लिए funded खाते। चीज़ें छोटी हैं, पर हर एक के फ़ेल होने का तरीका ऐसा है जिसे ग़लत समझना आसान है।

Entitlement। हर /v1/estamp/* route पर estamp.enabled entitlement की जाँच लगती है। जिस organisation के पास यह नहीं है उसे इन routes पर HTTP 400 मिलता है, संदेश में लिखा होता है कि वह entitled नहीं है। e-Stamp का production access verification APIs से अलग मंज़ूरी है, और आठों reference पन्ने एक ही estamp service code पर टिके हैं, इसलिए एक मंज़ूरी पूरी सतह को कवर करती है।

Keys और scopes। keys environment के हिसाब से बनती हैं: sk_test_ sandbox की और sk_live_ production की। हर key पर OAuth जैसे scopes होते हैं, और संवेदनशील scopes पर IP allowlist भी लगाई जा सकती है। पहचान Authorization: Bearer <key> या x-api-key: <key> से होती है। key ग़लत या ग़ायब हो तो 401 और code UNAUTHORIZED; key सही पर scope नहीं तो 403 और code FORBIDDEN। हर service के लिए अलग key बनाइए: quote वाली service को services.read, estamp.read और estamp.duty.calculate चाहिए; order वाले worker को estamp.orders.validate, estamp.orders.create, estamp.parties.write और wallet वाले scopes; status देखने वाले poller को estamp.orders.read और estamp.stamps.read। key बनाने और बदलने का तरीका authentication reference में है।

Errors। हर route की हर ग़लती एक ही ढाँचे में आती है:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "stampDutyAmount must be one of 100, 200, 500, 1000 for ART1 in MH",
    "requestId": "a1b2c3d4-e5f6-4a1b-8c2d-9f0e1a2b3c4d"
  }
}

हर ग़लती के साथ requestId अपने log में रखिए, support सबसे पहले वही माँगेगा। e-Stamp routes में काम की चीज़ संदेश का text है। code HTTP status से बनता है (BAD_REQUEST, NOT_FOUND, CONFLICT, FORBIDDEN, PAYMENT_REQUIRED), इसलिए पहले status पर branch कीजिए और संदेश को इंसान के पढ़ने की जानकारी मानिए, पक्का machine code नहीं।

Rate limits। lookups पर हर endpoint के लिए 60 सेकंड में 60 requests की छूट है। duty calculation, parties, validate, create और cancel पर 60 सेकंड में 30। 429 आए तो रुकिए, तंग loop में दोबारा मत भेजिए।

कदम 1 और 2: catalogue से शुरू, फिर schema से फ़ॉर्म

सबसे पहले service catalogue देखिए। GET /v1/services वे सारी services लौटाता है जो organisation को मिली हैं, verification और e-Stamp दोनों, और GET /v1/services/:serviceCode उनमें से एक। e-Stamp की services का serviceCode estamp. से शुरू होता है।

curl -s "$BASE/v1/services" -H "Authorization: Bearer $STAMPMITRA_API_KEY"

response की हर entry में serviceCode, name, category, basePrice, currency, isActive, gstRatePercent, defaultGovernmentFee, processingTimeHours, guestCheckoutEnabled, requiresDocuments, uiSchema, entitled और entitlementUpdatedAt आते हैं। यूज़र को कोई service दिखाने से पहले entitled और isActive देखिए। processingTimeHours को अपेक्षा की तरह दिखाइए, वादे की तरह लागू मत कीजिए। catalogue entry का basePrice एक सामान्य service field है; e-Stamp के असली order का दाम कदम 4 की गणना से आता है, जो हर stamp का duty और service charges अलग से निकालती है। e-Stamp के लिए सूची ख़ाली हो तो इसका मतलब है कि organisation अभी entitled नहीं है। यह एक configuration की हालत है, error नहीं, इसलिए retry मत कीजिए; dashboard में production access की स्थिति देखिए या developer support को लिखिए।

अब schema। GET /v1/estamp/schema/:serviceCode फ़ॉर्म बनाने का metadata देता है। e-Stamp का schema एक ही है, इसलिए path का serviceCode सिर्फ़ route की एकरूपता के लिए है, जवाब नहीं बदलता। response में field की परिभाषाओं की सूची होती है: name, label, type, required, और जहाँ ज़रूरी हो pattern व placeholder। आज उसमें पाँच fields हैं: stateCode, articleCode, districtCode, sroValue और stampDutyAmount।

ध्यान दीजिए कि schema किसका वर्णन करता है: quote के inputs का, यानी duty calculation के पाँच fields का। यह पूरे order का फ़ॉर्म नहीं है। पक्षकारों के नाम, मक़सद और stamp line की बाक़ी बातें कदम 6 के order contract से आती हैं। schema आज छोटा है और आगे बढ़ सकता है, इसीलिए labels अपने code में लिखने के बजाय उसी से फ़ॉर्म बनाइए। उसे cache कीजिए, एक असली response test fixture की तरह रखिए, और जब वह बदले तो fixture का test आपको बता देगा।

कदम 3: राज्य, article, और जहाँ ज़रूरी हो वहाँ जिला और SRO

estamp.read के तहत तीन routes catalogue देते हैं और तीन और वहाँ काम आते हैं जहाँ राज्य को अतिरिक्त जानकारी चाहिए। GET /v1/estamp/states सक्रिय राज्यों की सूची है। GET /v1/estamp/states/:stateCode एक राज्य की पूरी तस्वीर देता है: नाम, eStampAvailable, traditionalAvailable, minAmount, maxAmount, sroRequired, cessRequired, propertyAreaRequired, fatherHusbandNameRequired, firstPartyAddressRequired, panCardImageRequired और instrumentCount। GET /v1/estamp/states/:stateCode/instruments उस राज्य के articles देता है, GET /v1/estamp/instruments/:instrumentCode/articles वही सूची देता है (path में state code जाता है), GET /v1/estamp/states/:stateCode/requirements राज्य की दस्तावेज़ी ज़रूरतें बताता है (जब तक sync न हुआ हो 404), और .../districts तथा .../districts/:districtCode/sros जिले और sub-registrar offices।

cascading select बनाने से पहले दो अजीब बातें जान लीजिए। एक, अलग से "instrument" नाम की कोई चीज़ नहीं है: instruments और articles वाले routes एक ही सूची लौटाते हैं, इसलिए आपके UI में दो स्तर हैं, राज्य और फिर article, तीन नहीं। दो, articles वाले route के instrumentCode की जगह state code जाता है। article की हर entry में code, description, popular, minimumAmount, वैकल्पिक allowedAmounts और isSecondPartyNA होता है, जो बताता है कि उस article में दूसरा पक्ष लागू नहीं होता।

राज्य के flags बताते हैं कि और क्या पूछना है। sroRequired true हो तो duty calculation और order, दोनों में districtCode और sroValue भेजना होगा, जो आप districts और SROs वाले routes से पढ़ते हैं। propertyAreaRequired true हो तो stamp line में propertyArea चाहिए। फ़ॉर्म इन्हीं flags से चलाइए, किसी राज्य के नाम पर अपने code में if मत लिखिए। master data बदलेगा तो flags भी साथ बदलेंगे। नीचे की response में रकमें केवल दिखाने के लिए हैं, किसी राज्य के नियम का बयान नहीं:

{
  "code": "MP",
  "name": "Madhya Pradesh",
  "isActive": true,
  "eStampAvailable": true,
  "traditionalAvailable": true,
  "minAmount": "100.00",
  "maxAmount": "500000.00",
  "sroRequired": false,
  "cessRequired": false,
  "propertyAreaRequired": true,
  "fatherHusbandNameRequired": true,
  "firstPartyAddressRequired": true,
  "panCardImageRequired": false,
  "instrumentCount": 30
}

कदम 4: duty calculate असल में क्या गिनता है?

यही वह कदम है जिसे सबसे ज़्यादा लोग ग़लत समझते हैं, इसलिए ठीक-ठीक बर्ताव बताता हूँ। POST /v1/estamp/duty/calculate एक राज्य, एक article और एक stampDutyAmount लेता है जो आप देते हैं। वह इस रकम को किराये, deposit या संपत्ति की क़ीमत से नहीं निकालता। वह यह जाँचता है कि यह रकम उस राज्य और article के लिए ख़रीदी जा सकती है या नहीं, और फिर उसके चारों तरफ़ का दाम जोड़ता है: service charges, उन पर GST, और कोई coupon। प्लेटफ़ॉर्म की शर्तें भी यही बँटवारा बताती हैं: जब तक कोई service अधिकृत डेटा के आधार पर गणना की सुविधा साफ़ न दे, StampMitra सरकारी duty तय नहीं करता।

जाँच क्या-क्या देखती है, यह जानना ज़्यादातर 400 की वजह समझा देता है। किसी राज्य या article में सिर्फ़ तय denominations चल सकते हैं, या न्यूनतम और अधिकतम के बीच की कोई रकम, या कुछ configurations में सीमित संख्या के papers से बना कुल योग। इन सबके बाहर की रकम पर ऐसा संदेश आता है जो बताता है कि क्या-क्या चलेगा। अगर राज्य के लिए कोई duty rule सेट है तो response में requiredDuty आता है: उस चयन के लिए नियम जितना कम से कम माँगता है। आप उससे बड़ा denomination ले सकते हैं, छोटा नहीं।

response में stateCode, articleCode, papers, paperCount, requiredDuty, stampDutyAmount, serviceCharges (हर entry में key, basis, amount, couponEligible, unitAmount, quantity), serviceChargeSubtotal, discountAmount, taxableServiceCharges, gstAmount, gstRatePercent, totalAmount, masterDataVersion, masterDataVersionStale और pricingVersion आते हैं। ढाँचा पढ़िए, रकमें नहीं। सरकारी duty (stampDutyAmount) पर न कर लगता है, न छूट। GST सिर्फ़ service charges पर लगता है। यूज़र को दिखाने की रकम totalAmount है। जो लौटे उसे वैसा ही दिखाइए, अपने यहाँ दोबारा जोड़िए-घटाइए मत, और अपने database में duty की कोई तालिका मत रखिए। masterDataVersion भेजेंगे तो masterDataVersionStale बता देगा कि आपका cache पुराना है या नहीं। यह call मीटर वाली है, इसलिए हर keystroke पर नहीं, inputs के hash के साथ quote cache कीजिए। duty की रकम तय कैसे होती है, इसके लिए राज्य-वार duty का explainer पढ़िए, और हर field व error के लिए duty calculation का reference पन्ना।

पक्षकार और गवाह: कौन-सी जानकारी कहाँ जाती है?

e-stamp उन लोगों के नाम पर जारी होता है जो दस्तावेज़ के पक्षकार हैं। order में हर stamp line पर firstParty (ज़रूरी) और secondParty (जहाँ article में दूसरा पक्ष होता है) जाता है, साथ में वैकल्पिक stampDutyPayer, payerPhone और payerGender। order बनने के बाद POST /v1/estamp/orders/:orderId/parties संपर्क-स्तर की जानकारी जोड़ता या सुधारता है, इन वैकल्पिक fields से: customerName, customerMobile, customerEmail, partyAddress और partyPan। यह route एक ही पक्ष को मॉडल करता है: partyName स्वीकार तो होता है, पर वह customerName वाला ही नाम लिखता है, इसलिए उससे दूसरा पक्ष तय नहीं होता। दूसरे पक्ष का नाम stamp line में secondParty के रूप में जाता है। यहाँ orderId का मतलब Core order id है। order बनाने के response में id और orderId दोनों आते हैं और यह route orderId वाला field लेता है। पहले sandbox response में इसे खुद देख लीजिए, अंदाज़े से मत चलिए। call मीटर वाली है और समीक्षा के दौर के लिए है, जब reviewer अब भी सुधार पर काम कर सकता है। जारी होने के बाद e-stamp आम तौर पर बदला नहीं जा सकता, और सेवा की शर्तें कहती हैं कि सुधार के लिए नया transaction लगाना पड़ सकता है। इसीलिए order बनाने से पहले एक review स्क्रीन रखिए।

गवाह। API में गवाह के fields नहीं हैं, और यह चूक नहीं, सही बात है। गवाह एग्रीमेंट पर दस्तख़त करते हैं, stamp की ख़रीद पर नहीं। एग्रीमेंट में गवाह चाहिए या नहीं, कितने चाहिए, और क्या उन्हें निष्पादन के समय मौजूद रहना है, ये दस्तावेज़ और राज्य के नियमों के सवाल हैं। गवाहों का ब्योरा अपने agreement workflow में रखिए। आपकी signing प्रक्रिया e-sign पर हो या हाथ के दस्तख़त पर, e-stamp certificate उस कदम का सिर्फ़ एक input है।

कदम 6: दो order बने बिना order कैसे बनाएँ?

पहले validate, फिर create। POST /v1/estamp/orders/validate वही जाँच चलाता है जो create करता है, पर कुछ सेव नहीं करता, और नतीजा READY_TO_PLACE हो, WARNINGS हो या NEEDS_INFORMATION, HTTP 200 ही लौटाता है। सिर्फ़ ऐसा input जो सुधर ही नहीं सकता, 400 और VALIDATION_FAILED देता है। इसका इस्तेमाल यूज़र को commit करवाने से पहले field-स्तर की दिक़्क़तें और दाम की चेतावनियाँ दिखाने में कीजिए। validate पर शुल्क नहीं लगता।

दोनों routes की body में आपका अपना reference और stamps की array होती है। हर line का राज्य एक ही होना चाहिए, क्योंकि एक order का मतलब एक राज्य। line में state, articleCode, denomination और firstParty ज़रूरी हैं; category का default e_stamp है; बाक़ी वैकल्पिक हैं: secondParty, purpose, district, sro, propertyArea, cessAmount, quantity, clientReference, costCentre, businessUnit। Python में एक पूरा call कुछ ऐसा दिखता है:

import os, requests

BASE = "https://api-b2b.stampmitra.in"
H = {"Authorization": f"Bearer {os.environ['STAMPMITRA_API_KEY']}"}

def create_stamp_order(agreement_id: str, version: int, line: dict):
    body = {"reference": agreement_id, "stamps": [line]}
    r = requests.post(
        f"{BASE}/v1/estamp/orders",
        json=body,
        headers={**H, "Idempotency-Key": f"{agreement_id}-v{version}"},
        timeout=30,
    )
    data = r.json()
    if r.status_code == 402:
        raise RuntimeError(f"balance कम है ({data['error']['message']}): संदेश में नामित wallet का top-up करें, फिर उसी key से दोबारा भेजें")
    if not r.ok:
        raise RuntimeError(f"{r.status_code} {data['error']['message']} req={data['error']['requestId']}")
    return data["id"], data["orderId"], data["stamps"][0]["id"]

एक सावधानी, यह body कॉपी करने से पहले। public order contract में firstParty और secondParty सादे नाम हैं और propertyArea एक string। जारी करने वाला पक्ष पक्षकार को ऐसे object की तरह मॉडल करता है जिसमें name, address, phone, fatherHusbandName और gender होते हैं, और संपत्ति के क्षेत्रफल को इकाई और मान की तरह, और पिता या पति के नाम व पहले पक्ष के पते वाले राज्य-flags इसी की तरफ़ इशारा करते हैं। अपना पहला नमूना sandbox में POST /v1/estamp/orders/validate पर चलाइए और स्वीकार हुआ आकार test fixture की तरह रखिए, क्योंकि contract का यही हिस्सा सबसे ज़्यादा परिष्कृत होने की संभावना रखता है।

Idempotency-Key header इसी route पर और सिर्फ़ इसी पर ज़रूरी है। उसी key और उसी body से दोबारा भेजने पर पुराना response लौटता है और दूसरा order नहीं बनता। उसी key के साथ अलग body भेजने पर 422 IDEMPOTENCY_KEY_REUSED; header ग़ायब हो तो 400 IDEMPOTENCY_KEY_REQUIRED; पहली request अभी प्रोसेस हो रही हो तब आई दूसरी request को 409 IDEMPOTENCY_IN_PROGRESS और Retry-After header मिलता है: रुकिए, फिर ठीक वही request दोबारा भेजिए। key आपकी organisation, route और environment तक सीमित है और 24 घंटे तक रखी जाती है। key अपने सिस्टम की किसी टिकाऊ चीज़ से बनाइए, जैसे agreement id के साथ version, ताकि timeout के बाद का retry वही key इस्तेमाल करे और सचमुच नया order नई key पाए।

order की status Core की समीक्षा-पूर्व status होती है: PENDING_REVIEW, READY_TO_PLACE, WARNINGS, NEEDS_INFORMATION, VALIDATION_FAILED या CANCELLED। ये जान-बूझकर vendor की अपनी शब्दावली नहीं हैं। order बनाने का काम validation पर रुक जाता है और order को जारी करने वाले vendor के पास नहीं भेजता; placement की पुष्टि operations का reviewer अलग से करता है, इसलिए नया order कुछ देर समीक्षा में रहेगा। reference में एक सामान्य POST /v1/orders भी है, जो किसी भी entitled service code के लिए चलता है। उसमें खुला-सा details object है और राज्य, article या denomination के कोई typed fields नहीं हैं, इसलिए stamp के लिए ऊपर वाले e-Stamp routes ही ठीक बैठते हैं।

पैसा कहाँ से कटता है? तीन खाते, तीन काम

StampMitra के खाते में तीन अलग balances होते हैं, और इन्हें दिमाग़ में अलग रखने से बहुत उलझन बचती है।

दोनों e-Stamp wallets Razorpay Checkout से भरे जाते हैं: top-up call रुपयों में baseAmount लेती है और razorpayOrderId तथा razorpayKeyId लौटाती है जिनसे आपका frontend checkout खोलता है। Service Fee Wallet के response में जुड़ा हुआ gstAmount और totalCharged भी दिखता है। balance और ledger GET /v1/stamp-duty-wallet, GET /v1/service-fee-wallet और उनके /transactions routes से पढ़े जाते हैं।

असली बात यह है कि पैसा कब हिलता है। order बनते समय, कोई भी order record लिखे जाने से पहले, प्लेटफ़ॉर्म duty Stamp Duty Wallet से और service fee Service Fee Wallet से काटता है। दूसरा debit फ़ेल हुआ तो पहला वापस लौटा दिया जाता है। कोई भी balance कम पड़े तो request ठुकरा दी जाती है और कुछ नहीं बनता। जवाब 402 PAYMENT_REQUIRED होता है और उसका संदेश बताता है कि कौन सा wallet कम है, Stamp Duty Wallet या Service Fee Wallet, ताकि आपको पता रहे कि किसका top-up करना है। top-up के बाद उसी Idempotency-Key से दोबारा भेजिए; call साफ़ चलेगी, पुराना फ़ेल हुआ जवाब नहीं दोहराएगी। अगर debit के बाद order बनाना ही फ़ेल हो जाए तो रकम वापस जमा कर दी जाती है। यूज़र को आख़िरी बटन देने से पहले wallet routes से balances जाँच लीजिए।

payment के reference पन्ने में एक सामान्य payment resource भी लिखा है: POST /v1/payments/intents एक Razorpay-आधारित intent बनाता है (fields externalOrderId, amountMinor, currency और paymentConnectionId) और GET /v1/payments/intents/:id उसे पढ़ता है। इसे सामान्य building block समझिए, और e-Stamp order के लिए wallets को वह रास्ता जिससे पैसा सचमुच कटता है। स्क्रीन जो भी कहे, सफल payment का मतलब जारी stamp नहीं है। अपने record को "paid, awaiting issuance" जैसी status पर रखिए और "stamped" तभी कीजिए जब certificate उपलब्ध हो।

order और stamp की states: दो शब्दकोश, दो पल

दो शब्दावलियाँ हैं और वे अलग-अलग पल बताती हैं। order की status समीक्षा का हाल बताती है, तब जब vendor के पास अभी कुछ है ही नहीं। stamp की status vendor के काम का हाल बताती है, placement के बाद। अपने database में दोनों रखिए और कभी एक enum में मत मिलाइए।

कोई ऐसी string आए जिसे आप नहीं पहचानते तो उसे "ध्यान चाहिए" वाली बाल्टी में डालिए, exception मत फेंकिए। यह शब्दावली एक अनुबंध है जिसे आप responses से पढ़ते हैं, और उसका बढ़ना आपके poller को गिराना नहीं चाहिए।

कदम 8: certificate कैसे उतारें?

ट्रैकिंग के दो स्तर हैं क्योंकि order असल में stamps का डिब्बा है। GET /v1/estamp/orders/:id order और उसकी समीक्षा-पूर्व status देता है, और GET /v1/estamp/orders आपकी organisation के orders की सूची, page और limit के साथ। reviewer के order place कर देने के बाद हर stamp की अपनी ज़िंदगी शुरू होती है: GET /v1/estamp/stamps/:stampId stamp लौटाता है, जिसकी status PLACED, ASSIGNED, GENERATING, VERIFYING, VERIFIED या CANCELLED होती है, साथ में verified boolean और बनने के बाद uin, यानी stamp की unique पहचान संख्या।

certificate वाला route जान-बूझकर सीधा passthrough है और एक साफ़ भेदक रखता है, इसलिए हमेशा HTTP 200 देता है। ऐसा आने पर:

{ "available": false, "status": "not_yet_available" }

का मतलब है कि अभी इंतज़ार कीजिए, और delivery के बाद:

{
  "available": true,
  "status": "available",
  "downloadUrl": "https://api-b2b.stampmitra.in/v1/estamp/certificates/eststamp_4f21ab/download?token=...",
  "expiresAt": "2026-10-29T10:05:00.000Z",
  "certificateNumber": "IN-MH-2026-0917-001234"
}

downloadUrl हमेशा StampMitra का अपना होता है, किसी तीसरे पक्ष का नहीं, और पाँच मिनट में ख़त्म हो जाता है। जिस पल ज़रूरत हो उसी पल उठाइए, PDF को सीधे अपने storage में उतारिए और वहीं रखिए, क्योंकि बाद में उस link पर भरोसा नहीं किया जा सकता। certificateNumber उपलब्ध certificate में भी null हो सकता है। जिस stamp की delivery नहीं हुई वह error नहीं है, इसलिए available: false को नाकामी मानने के बजाय backoff के साथ poll कीजिए।

// Node 18+, global fetch
const BASE = "https://api-b2b.stampmitra.in";
const headers = { Authorization: `Bearer ${process.env.STAMPMITRA_API_KEY}` };

async function certificateOnce(stampId) {
  const res = await fetch(`${BASE}/v1/estamp/stamps/${stampId}/certificate`, { headers });
  const body = await res.json();
  if (!res.ok) throw Object.assign(new Error(body.error?.message), { status: res.status, requestId: body.error?.requestId });
  if (!body.available) return null;          // अभी नहीं आया, अगली बार देखें
  const pdf = await fetch(body.downloadUrl); // link पाँच मिनट चलता है
  return { certificateNumber: body.certificateNumber, bytes: Buffer.from(await pdf.arrayBuffer()) };
}

order को place होने से पहले POST /v1/estamp/orders/:id/cancel से रद्द किया जा सकता है, और stamp को cancellable vendor state में POST /v1/estamp/stamps/:stampId/cancel से। generation की ख़राबी के बाद POST /v1/estamp/stamps/:stampId/replace से replacement माँगा जा सकता है। जो object उस मोड़ से आगे निकल चुका हो उस पर तीनों 409 INVALID_STATE देते हैं, और VERIFIED stamp रद्द नहीं होता।

webhook या polling: किस पर टिकें?

webhooks reference में order lifecycle के events गिनाए गए हैं: order.created, order.payment_confirmed, order.fulfilment_started, order.fulfilment_completed, order.failed, order.cancelled, order.refund_completed और order.document_ready। deliveries पर दस्तख़त होते हैं: timestamp, एक बिंदु और raw body का HMAC-SHA256 (hex), X-Webhook-Signature में, साथ में X-Webhook-Timestamp और X-Webhook-Event-Id headers। secret बदलते समय X-Webhook-Signatures header में सारे फ़िलहाल मान्य दस्तख़त आते हैं। नाकाम deliveries पर exponential backoff से retry होता है, क़रीब तेरह घंटे में छह कोशिशें, फिर dead-letter। raw bytes पर जाँचिए, अपनी घड़ी से बहुत दूर के timestamp ठुकराइए (SDKs का default 300 सेकंड है), event id पर duplicates छाँटिए और जल्दी से 2xx लौटाइए। सात भाषाओं में verification का code webhooks पेज पर है।

अपना endpoint dashboard के Webhooks पन्ने से दर्ज कीजिए। साफ़ रहिए कि events किस चीज़ को बयान करते हैं: वे प्लेटफ़ॉर्म के सामान्य order lifecycle से जुड़े हैं। dedicated routes से बने e-Stamp order के लिए यह मत मान लीजिए कि ऊपर की हर transition पर event आएगा; अपने खाते में event coverage की पुष्टि developer support से कर लीजिए। सुरक्षित design वही है जो दोनों हालात में चले: event को "जाकर देखो" का इशारा मानिए, फिर stamp और certificate routes से पूछिए और जो वे कहें उसी पर चलिए, और जो देर तक pending रहे उसके लिए धीमा poll पीछे रखिए।

क्या-क्या बिगड़ता है और किसे दोबारा भेजना सुरक्षित है?

इस flow की ज़्यादातर ग़लतियाँ अंदाज़े लायक हैं। नीचे की तालिका बताती है कि कहाँ retry मदद करता है और कहाँ नुक़सान।

बिलिंग के नियम यहाँ मदद करते हैं। शुरू में ही 400 से ठुकराई गई ग़लत बनावट वाली requests पर शुल्क नहीं लगता, और जो calls StampMitra की तरफ़ से या उसके provider की तरफ़ से फ़ेल हों, उनका पैसा अपने-आप वापस जमा हो जाता है। duplicate से बचाव के लिए idempotency key सस्ता बीमा है: network timeout के बाद जब आपको पता न हो कि order बना या नहीं, तो retry दोबारा काम करने के बजाय पुराना जवाब लौटाता है।

लागत का हिसाब: एक stamp की असली क़ीमत

लागत को उन हिस्सों में तोड़िए जो अलग-अलग चलते हैं। StampMitra की API fee pay-as-you-go पर हर चार्ज हुई call के लिए ₹5 है, Growth और Scale पर कम, और अपने plan की ठीक दर आपको pricing पेज पर मिलेगी। चार्ज होने वाली calls हैं duty calculation और parties, और जहाँ आपके खाते में per-order fee चालू है वहाँ order बनाना। lookups और validation मुफ़्त हैं। राज्य की procurement fee राज्य और मात्रा पर निर्भर करती है और production access मंज़ूर होने पर बताई जाती है। सरकारी duty actuals पर आगे पास होती है और उस पर कभी मार्कअप नहीं लगता। 18 प्रतिशत GST StampMitra के अपने शुल्कों पर लगता है, duty पर नहीं। साइट के दाम GST से पहले के हैं।

तो एक किराएदारी stamp का ख़र्च यह है: जो duty आपने तय की, उसके साथ उस राज्य की procurement और convenience fee और उन पर GST, और रास्ते में की गई हर चार्ज वाली call की API fee। order से पहले आप जितने quote माँगेंगे, API fee उतनी बढ़ेगी, इसीलिए quote को उसके inputs के हिसाब से cache करना और parties को एक ही बार बुलाना मेहनत के लायक है। wallets के न्यूनतम top-up GST से पहले गिने जाते हैं, और API credit wallet कम balance पर अलर्ट देता है। आपके request logs हर चार्ज हुई call दिखाते हैं; logs plan के हिसाब से 7 से 365 दिन तक रखे जाते हैं।

sandbox और production में फ़र्क़

sandbox एक नक़ली lifecycle चलाता है, इसलिए आप पूरा flow मुफ़्त में परख सकते हैं। sk_test_ key से कोई असली wallet नहीं कटता और कुछ जारी करने वाले पक्ष तक नहीं पहुँचता। उसका catalogue एक छोटा नमूना है और fee तालिका नमूने की, इसलिए sandbox quote का ढाँचा production जैसा और आँकड़े अलग होते हैं। orders CREATED, PAYMENT_PENDING, PROCESSING और ISSUED से क़रीब तीस सेकंड में अपने-आप गुज़रते हैं, stamps VERIFIED हो जाते हैं, और certificate route SANDBOX SAMPLE, NOT A VALID STAMP के watermark वाली एक साझा PDF तक छोटी उम्र का link देता है। दो sandbox wallets में नक़ली राशि रहती है जिसे आप भर सकते हैं, orders उन्हें काटते हैं और फ़ेल orders लौटा देते हैं। SBX-PAYMENT-FAILED और SBX-ISSUANCE-FAILED जैसे ख़ास reference मान failure के रास्ते तय करते हैं, और sandbox का webhook endpoint order.* events पाता है। इन calls की हर sandbox request sandbox सीमाओं में गिनी जाती है, route चाहे जो e-Stamp या wallet route हो, catalogue पढ़ना और wallet calls भी: प्रति organisation प्रति मिनट 10 और प्रति दिन 200 requests, और प्रति IP address प्रति दिन 50, आधी रात IST पर रीसेट।

जो अलग रहता है वह है जो कोई इंसान या असली दुनिया तय करती है। production का order किसी इंसान समीक्षक का इंतज़ार करता है और pre-placement statuses से शुरू होता है, इसलिए sandbox में दिखने वाला समय और statuses कोई वादा नहीं हैं। certificate नमूना है, stamp नहीं। live catalogue, states की उपलब्धता और दाम production की बातें हैं।

अपनी testing दो दौर में बनाइए। कदम 1 से 8 sandbox में पूरे चलाइए, हर failure marker, खुले orders की सीमा, कम wallet से मिलने वाला 402 और अपना webhook handler समेत। lifecycle statuses और test inputs की पूरी सूची order पन्ने में है और नमूना certificate document पन्ने में। फिर launch से पहले एक असली कम क़ीमत का production order चलाइए, ताकि असली समीक्षा का इंतज़ार और असली certificate आपने एक बार देखा हो। production के लिए मंज़ूर production access request और भरे हुए wallets चाहिए। key सँभालने और go-live की और गहराई sandbox बनाम production गाइड में है।

पूरा उदाहरण: इंदौर की एक leave and licence stamp, आदि से अंत तक

नीचे वही flow एक एग्रीमेंट के लिए, हर call के साथ। पात्र काल्पनिक हैं: मीना जोशी licensee हैं, राजेश वर्मा licensor, और संपत्ति इंदौर में है। मान लीजिए compliance टीम ने तय किया कि इस एग्रीमेंट की duty 500 रुपये है। यह उदाहरण की एक धारणा है, किसी राज्य के असली शुल्क का बयान नहीं। registration और execution API के बाहर होते हैं।

पहले backend GET /v1/services से estamp.instrument.rent_agreement ढूँढता है, entitled: true देखता है। फिर schema लेकर quote का फ़ॉर्म बनाता है। यूज़र मध्य प्रदेश चुनता है; GET /v1/estamp/states/MP के flags से फ़ॉर्म तय होता है कि district और SRO पूछना है या नहीं और propertyArea माँगनी है या नहीं। GET /v1/estamp/states/MP/instruments से article की सूची भरती है और यूज़र (या आपका compliance नियम) leave and licence वाला article चुनता है।

फिर quote। service पाँचों fields भेजती है, stampDutyAmount: 500 के साथ। मान्य denominations की सूची वाला 400 आए तो यूज़र को लौटाकर मान्य रकम चुनवाइए। 200 आए तो breakdown स्क्रीन पर totalAmount के साथ दिखाइए, यह बताते हुए कि इसमें duty कितनी है और fees कितनी। quote को inputs के hash से cache कीजिए। आख़िरी स्क्रीन से ठीक पहले stamp line POST /v1/estamp/orders/validate पर जाती है। WARNINGS आए तो यूज़र को पढ़ाइए; VALIDATION_FAILED आए तो फ़ॉर्म पर लौटाइए। उसके बाद service दोनों wallets के balance पढ़ती है, और अगर कोई quote से कम है तो order का बटन देने से पहले top-up करवाती है।

अब order: Idempotency-Key: kirayanama-2026-0412-v1 के साथ POST, और लौटे id, orderId और stamps[0].id को अपने agreement id के साथ सहेजना। आपके database में agreement की स्थिति stamp_requested हो जाती है। समीक्षा के दौर में सुधार चाहिए तो /v1/estamp/orders/<orderId>/parties पर संपर्क जानकारी भेजी जाती है। फिर एक निर्धारित job GET /v1/estamp/orders/<id> पढ़ती है और जब order समीक्षा से आगे बढ़कर stamp place हो जाता है तो GET /v1/estamp/stamps/<stampId>, और हर status बदलाव को समय के साथ दर्ज करती है। स्थिति stamp_in_progress हो जाती है। जब GET .../certificate में available: true दिखे, job पाँच मिनट के भीतर PDF उतारती है, सहेजती है, certificateNumber और uin दर्ज करती है और स्थिति stamped कर देती है। यूज़र को सूचना जाती है, और एग्रीमेंट signing की तरफ़ जा सकता है और जहाँ राज्य माँगे वहाँ registration की तरफ़।

रास्ते में यूज़र जो भी देखता है वह API के जवाबों से निकला है। कुछ भी स्थानीय रूप से गिना नहीं गया, सिर्फ़ payment देखकर कुछ पूरा नहीं माना गया, और हर write को सुरक्षित रूप से दोहराया जा सकता है।

live जाने से पहले की चेकलिस्ट

इसे एक बार चलाइए, ऐसे इंसान के साथ जो कानूनी पक्ष का मालिक हो।

• e-Stamp का production access मंज़ूर है और production key पर सिर्फ़ वही scopes हैं जो हर service इस्तेमाल करती है।
• दोनों e-Stamp wallets और API credit wallet भरे हैं, और कम balance पर आपके यहाँ अलर्ट बजता है।
• हर order बनाने पर agreement id से बनी टिकाऊ Idempotency-Key जाती है।
• आपका code order और stamp की हर status सँभालता है, अनजानी वाली भी।
• certificate उपलब्ध होते ही आपके storage में कॉपी हो जाते हैं, response के link पर टिके नहीं रहते।
• आपके database में duty की कोई तालिका नहीं है, और API से लौटी रकमों पर कोई स्थानीय गणित नहीं।
• आपका UI जमा करने से पहले article और duty का आधार किसी इंसान को दिखाता है, और create से पहले review स्क्रीन है।
• webhook के दस्तख़त raw bytes पर जाँचे जाते हैं, और बहुत देर pending रहने वाली चीज़ें धीमा poll पकड़ लेता है।
• आपने एक असली कम क़ीमत का order production में पूरा चलाकर देखा है।

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

StampMitra डेवलपर को e-Stamp और verification products पर एक API key और एक जैसे नियम देता है: वही error ढाँचा, वही scope मॉडल, वही request log और वही prepaid बिलिंग। यहाँ बताई गई e-Stamp सतह वही है जो आज मौजूद है, और इस पन्ने ने कोशिश की है कि वहाँ बिल्कुल सटीक रहे जहाँ बर्ताव सीधा नहीं है, जैसे placement से पहले समीक्षा, पाँच मिनट वाला certificate link और issuance की नक़ल का न होना।

अगर आप एग्रीमेंट के लोगों की पहचान भी जाँचते हैं तो PAN verification API और GSTIN verification API उसी key पर चलती हैं। order की mechanics की और गहरी developer walk-through के लिए e-Stamp order flow गाइड और किराएदारी प्रोडक्ट के design के लिए rental agreement वाला use case देखिए। lookups आज़माने के लिए sandbox key लीजिए और पहले तीन कदम आज ही चलाइए। sandbox मुफ़्त है और जब आप तैयार हों तो production की request dashboard से की जाती है।

API reference एक नज़र में

[
  {
    "serviceCode": "estamp.instrument.rent_agreement",
    "name": "Rent Agreement e-Stamp",
    "category": "estamp",
    "basePrice": "500.00",
    "currency": "INR",
    "isActive": true,
    "gstRatePercent": "18.00",
    "defaultGovernmentFee": null,
    "processingTimeHours": 24,
    "guestCheckoutEnabled": false,
    "requiresDocuments": true,
    "uiSchema": null,
    "entitled": true,
    "entitlementUpdatedAt": "2026-09-01T10:00:00.000Z"
  }
]

{
  "externalOrderId": "ord_ext_123",
  "createdAt": "2026-10-15T09:41:07.000Z",
  "serviceCode": "estamp.instrument.rent_agreement"
}

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