API ऑर्डर के पूरा होने की सूचनाएं कैसे सेट करें

किन इवेंट्स को ऑर्डर का पूरा होना माना जाए

सबसे पहले तय करें कि API में कौन सा स्टेटस ऑर्डर के वास्तविक पूरा होने को दर्शाता है। अलग-अलग प्रदाताओं में यह पूर्ण, डिलीवर्ड, रद्द, अस्वीकृत, वापस किया गया या आंशिक रूप से पूर्ण ऑर्डर हो सकता है। ऑटोमेशन को केवल "सफलता" शब्द से न जोड़ें: ऑर्डर कई मध्यवर्ती अवस्थाओं से गुजर सकता है और फिर सीमा, जांच या रद्दीकरण के कारण रुक सकता है।

केवल सकारात्मक परिणाम को ही नहीं, बल्कि त्रुटि, रद्दीकरण, वापसी या आंशिक पूर्णता की सूचना भी आंतरिक सिस्टम में दर्ज करनी चाहिए। अन्यथा पैनल, CRM या बॉट में ऑर्डर प्रतीक्षा में रहेगा, जबकि आगे निष्पादन नहीं होगा।

स्टेटस मैपिंग तालिका बनाएं

API स्टेटस को बिना प्रोसेसिंग के इंटरफ़ेस में न भेजें। प्रदाता के नाम और लॉजिक बदल सकते हैं, और एक ही आंतरिक स्टेटस कई बाहरी स्टेटस को जोड़ सकता है। मूल मान अलग से संग्रहीत करें: यह त्रुटि विश्लेषण और दस्तावेज़ीकरण से मिलान के लिए उपयोगी होगा।

• pending, created, queued — नया या प्रोसेसिंग की प्रतीक्षा में ऑर्डर।
• processing, in_progress, running — ऑर्डर निष्पादित हो रहा है।
• completed, delivered, success — पूर्ण ऑर्डर।
• partial, partially_completed — आंशिक रूप से पूर्ण ऑर्डर।
• cancelled, rejected, failed — रद्द या त्रुटि के साथ समाप्त ऑर्डर।
• refunded, returned — ऑर्डर में वापसी या समायोजन की आवश्यकता है।
• अज्ञात स्टेटस — कार्ड को स्वचालित रूप से नहीं बदलता और जांच के लिए भेजा जाता है।

ऊपर दिए गए नाम उदाहरण के रूप में हैं। अंतिम तालिका विशिष्ट API के स्टेटस के आधार पर बनाई जानी चाहिए। मैन्युअल मैपिंग की कमी यह है कि API अपडेट के बाद इसे बनाए रखना पड़ता है: नया स्टेटस हैंडलर में उसके लिए नियम बनने से पहले आ सकता है।

वेबहुक, API पोलिंग या दोनों चुनें

वेबहुक — यह ऑर्डर स्टेटस बदलने पर सेवा द्वारा आपके URL पर भेजा गया अनुरोध है। API पोलिंग उलटा काम करती है: आपका सिस्टम अंतराल पर ऑर्डर की जानकारी का अनुरोध करता है। पूर्णता सूचनाओं के लिए आमतौर पर वेबहुक अधिक सुविधाजनक हैं, क्योंकि अपडेट स्टेटस जांच विधि पर लगातार अनुरोधों के बिना आता है।

• वेबहुक त्वरित प्रतिक्रिया के लिए उपयुक्त हैं: कार्ड अपडेट, अगले चरण का प्रारंभ या जिम्मेदार व्यक्ति को संदेश भेजना।
• पोलिंग तब उपयुक्त है जब प्रदाता callback सूचनाओं का समर्थन नहीं करता या सर्वर बाहरी अनुरोध स्वीकार नहीं करता।
• संयुक्त योजना वेबहुक को मुख्य चैनल के रूप में और पोलिंग को छूटे या अटके ऑर्डर खोजने के लिए उपयोग करती है।

पोलिंग की कमी — देरी और API पर अतिरिक्त भार। वेबहुक की कमी — endpoint को सुरक्षित करना, डुप्लिकेट को ध्यान में रखना और इवेंट डिलीवरी के क्रम पर निर्भर न रहना।

इवेंट प्राप्त करने के लिए endpoint सेट करें

सूचनाओं के लिए एक सार्वजनिक HTTPS पता आवश्यक है जो API सेवा की ओर से सुलभ हो। इंटीग्रेशन सेटिंग्स में आमतौर पर हैंडलर URL, सिग्नेचर सीक्रेट और इवेंट की सूची निर्दिष्ट की जाती है: स्टेटस परिवर्तन, पूर्णता, रद्दीकरण, त्रुटि या आंशिक पूर्णता।

केवल API इवेंट के लिए एक अलग मार्ग आवंटित करें। इससे लॉगिंग सेट करना, पहुंच सीमित करना, अनुरोध सीमा निर्धारित करना और सेवा ट्रैफ़िक को साइट फ़ॉर्म से अलग रखना आसान होता है। कार्य ऑर्डर के लिए परीक्षण वातावरण का पता न उपयोग करें: वातावरण अपडेट के बाद प्रदाता सहेजे गए URL पर इवेंट भेजता रहेगा।

लॉन्च से पहले दस्तावेज़ीकरण के अनुसार अनुरोध विधि और बॉडी प्रारूप जांचें। अधिकतर यह JSON के साथ POST होता है, लेकिन form-data, query पैरामीटर या कस्टम सीरियलाइज़ेशन स्कीमा भी मिलते हैं। पार्स त्रुटि को लॉग में दर्ज करें, अन्यथा गलत payload और एप्लिकेशन विफलता में अंतर करना कठिन होगा।

ऑर्डर और इवेंट के बीच संबंध सहेजें

API के माध्यम से ऑर्डर बनाते समय प्रदाता द्वारा लौटाया गया पहचानकर्ता सहेजें। साथ में आंतरिक ऑर्डर संख्या, सेवा प्रकार, मूल स्टेटस, अंतिम परिवर्तन का समय और मूल API प्रतिक्रिया सुरक्षित रूप में संग्रहीत करें। आने वाले वेबहुक का मिलान प्रदाता ID से करें, न कि चैनल लिंक, सेवा नाम या ग्राहक नाम से।

यदि API निर्माण के समय बाहरी पहचानकर्ता भेजने की अनुमति देता है, तो अपनी ऑर्डर संख्या external_id या client_reference जैसे फ़ील्ड में जोड़ें। इससे लॉग में खोज और विवादित स्थितियों का विश्लेषण आसान होता है। लेकिन बाहरी संख्या को एकमात्र कुंजी न बनाएं: कुछ प्रदाता इसे प्रत्येक सूचना में नहीं लौटाते।

वेबहुक से अज्ञात ID पर नया ऑर्डर न बनाएं। अज्ञात इवेंट को लॉग में सहेजें और अलग से जांचें। स्वचालित रिकॉर्ड निर्माण गलत डेटा या नकली अनुरोध की प्रोसेसिंग का कारण बन सकता है।

payload की स्पष्ट संरचना का उपयोग करें

फ़ील्ड के सटीक नाम API पर निर्भर करते हैं। नीचे किसी विशिष्ट सेवा का अनुबंध नहीं, बल्कि JSON इवेंट का उदाहरण है जिसे आंतरिक हैंडलर डिज़ाइन करते समय मार्गदर्शन के रूप में उपयोग किया जा सकता है। इवेंट पहचानकर्ता, प्रदाता के ऑर्डर ID, स्टेटस, परिवर्तन का समय और निदान डेटा महत्वपूर्ण हैं।

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

स्टेटस के बिना पूर्ण इकाइयों की संख्या को पूर्णता का संकेत न मानें। ऑर्डर आंशिक रूप से पूर्ण हो सकता है, और payload में संख्या गोल, देरी से अपडेट या बिल्कुल न भेजी गई हो सकती है। पूरी इवेंट बॉडी संग्रहीत करने की कमी — इसमें व्यक्तिगत डेटा या सेवा फ़ील्ड हो सकते हैं, इसलिए ऐसी प्रविष्टियों को मास्क करना और भंडारण अवधि सीमित करना आवश्यक है।

मूल अनुरोध बॉडी पर सिग्नेचर सत्यापित करें

खुला हैंडलर URL न केवल API सेवा से अनुरोध प्राप्त कर सकता है। यदि प्रदाता सिग्नेचर, सीक्रेट या टोकन भेजता है, तो ऑर्डर बदलने से पहले उन्हें सत्यापित करें। सामान्य योजना HMAC-SHA256 है: प्रदाता अनुरोध बॉडी के बाइट्स और साझा सीक्रेट से सिग्नेचर की गणना करता है, फिर परिणाम HTTP हेडर में भेजता है।

गणना का सिद्धांत इस प्रकार है: मूल अनुरोध बॉडी, उदाहरण के लिए बिना बदलाव के JSON बाइट्स, और इंटीग्रेशन सीक्रेट लिया जाता है। फिर HMAC-SHA256 की गणना की जाती है। यदि हेक्साडेसिमल रूप में परिणाम हेडर मान से मेल खाता है, तो सिग्नेचर के बाद बॉडी नहीं बदली और अनुरोध संभवतः सीक्रेट जानने वाले पक्ष द्वारा भेजा गया है।

सशर्त उदाहरण: HMAC_SHA256(सीक्रेट, raw_body) = X-Signature हेडर से सिग्नेचर। हेडर का नाम, एल्गोरिद्म और परिणाम प्रारूप केवल API दस्तावेज़ीकरण से लें। कुछ सेवाएं सिग्नेचर स्ट्रिंग में टाइमस्टैम्प या इवेंट ID जोड़ती हैं। इस मामले में केवल JSON बॉडी सत्यापित नहीं की जा सकती।

सिग्नेचर सत्यापन से पहले JSON न बदलें

सिग्नेचर मूल अनुरोध बाइट्स पर सत्यापित किया जाता है, न कि JSON ऑब्जेक्ट पर जिसे एप्लिकेशन ने पहले ही पार्स और फिर से बनाया है। पुनः सीरियलाइज़ेशन में फ़ील्ड का क्रम, स्पेस, कैरेक्टर एस्केपिंग, लाइन ब्रेक या एन्कोडिंग बदल सकती है। मनुष्य के लिए JSON वही रहेगा, लेकिन बाइट्स का सेट बदल जाएगा और HMAC मेल नहीं खाएगा।

इससे बचने के लिए पहले raw body को bytes या buffer के रूप में प्राप्त करें, इसे मेमोरी में सहेजें, सिग्नेचर की गणना करें और केवल सफल सत्यापन के बाद JSON पार्स करें। बॉडी पर trim, एन्कोडिंग रूपांतरण, कुंजी सॉर्टिंग और फ़ॉर्मेटिंग लागू न करें। फ्रेमवर्क के middleware में जांचें कि मूल बॉडी तक पहुंचने से पहले JSON स्वचालित रूप से पार्स तो नहीं हो रही।

इस योजना की कमी — हैंडलर middleware के क्रम पर निर्भर हो जाता है। गलत सेटिंग के साथ एप्लिकेशन केवल रूपांतरित ऑब्जेक्ट देखेगा और वैध सूचनाएं अस्वीकार होने लगेंगी।

HMAC सत्यापन के साथ हैंडलर का उदाहरण

नीचे Python में एक सशर्त उदाहरण है। यह क्रियाओं का क्रम दिखाता है, तैयार इंटीग्रेशन नहीं: हेडर, एल्गोरिद्म, सिग्नेचर प्रारूप और payload फ़ील्ड को प्रदाता के दस्तावेज़ीकरण के मानों से बदलें।

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

तुलना के लिए ऐसा फ़ंक्शन उपयोग करें जो पहले अमेल कैरेक्टर पर रुकता न हो। इससे प्रतिक्रिया समय के माध्यम से सिग्नेचर डेटा लीक होने का जोखिम कम होता है। सीक्रेट को क्लाइंट कोड में न भेजें, URL में न जोड़ें और लॉग में पूरी तरह न लिखें।

इवेंट प्रोसेसिंग को आइडेम्पोटेंट बनाएं

प्रदाता एक ही इवेंट कई बार डिलीवर कर सकता है। कारण सामान्य हैं: आपके सर्वर ने देर से उत्तर दिया, डेटा सहेजने के बाद कनेक्शन टूट गया, endpoint ने अस्थायी रूप से त्रुटि लौटाई या सेवा ने अपने नियमों के अनुसार पुनः डिलीवरी शुरू की। पुनरावृत्ति का अर्थ यह नहीं कि API ने नया ऑर्डर बनाया।

आइडेम्पोटेंसी का अर्थ है कि समान इवेंट परिणाम को केवल एक बार बदलता है। यदि इस नियम को ध्यान में न रखा जाए, तो डुप्लिकेट ग्राहक को फिर से संदेश भेजेगा, प्रबंधक के लिए कई कार्य बनाएगा, मुआवजा देगा या दोबारा ऑपरेशन शुरू करेगा।

सबसे अच्छा है payload से event_id का उपयोग करना। इसे अलग तालिका या प्रोसेस्ड इवेंट लॉग में विशिष्ट प्रतिबंध के साथ सहेजें। यदि अलग ID नहीं है, तो स्थिर फ़ील्ड से कुंजी बनाएं: प्रदाता का ऑर्डर ID, इवेंट प्रकार, स्टेटस और परिवर्तन का समय। यह विकल्प खराब है: गलत टाइमस्टैम्प के साथ अलग इवेंट समान दिख सकते हैं।

इवेंट और स्टेटस को एक ही ऑपरेशन में सहेजें

"क्या इवेंट प्रोसेस हो गया" की जांच और परिणाम की प्रविष्टि परमाणु रूप से होनी चाहिए। अन्यथा एक साथ आए दो समान अनुरोध दोनों रिकॉर्ड की अनुपस्थिति देखेंगे और क्रिया दो बार शुरू करेंगे। व्यावहारिक विकल्प — event_id पर विशिष्ट इंडेक्स और डेटाबेस ट्रांजैक्शन।

हैंडलर की सशर्त निरंतरता इस प्रकार है:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

अज्ञात ऑर्डर के लिए सफल कोड के साथ उत्तर देने की कमी — प्रदाता डिलीवरी दोबारा नहीं कर सकता। इसलिए अज्ञात इवेंट की अलग से निगरानी करें और जल्दी विश्लेषण करें। यदि API दस्तावेज़ीकरण ऐसे मामलों के लिए भिन्न उत्तर कोड की सिफारिश करता है, तो उसका पालन करें।

इवेंट के क्रम के उल्लंघन को ध्यान में रखें

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

अनुमत संक्रमण निर्धारित करें। उदाहरण के लिए, मध्यवर्ती स्टेटस अंतिम को अधिलेखित नहीं कर सकता, और रद्द ऑर्डर अलग जांच के बिना पूर्ण में नहीं बदलता। यदि API अंतिम स्टेटस के समायोजन की अनुमति देता है, तो कारण, मूल मान और परिवर्तन का स्रोत सहेजें।

यदि payload में ऑर्डर परिवर्तन का समय है, तो वेबहुक प्राप्ति के समय की नहीं, उसकी तुलना करें। जब API ऐसा मार्कर नहीं भेजता, तो स्थिति प्राथमिकताओं और ऑर्डर प्राप्ति विधि के माध्यम से मिलान का उपयोग करें। प्राथमिकताओं की कमी — वे वास्तविक अनुक्रम की जगह नहीं लेतीं, विशेषकर यदि प्रदाता अंतिम स्टेटस से वापसी की अनुमति देता है।

डिलीवरी की तुरंत पुष्टि करें और क्रियाओं को कतार में डालें

प्रदाता को उत्तर देने से पहले लंबे ऑपरेशन न करें। सिग्नेचर सत्यापन, ऑर्डर खोज, इवेंट प्रविष्टि और स्टेटस अपडेट आमतौर पर जल्दी पूरे किए जा सकते हैं। संदेश भेजना, CRM के साथ सिंक, रिपोर्ट बनाना या तृतीय-पक्ष सिस्टम से अनुरोध कार्य कतार में स्थानांतरित करना बेहतर है।

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

कतार की कमी — एक अलग घटक जोड़ा जाता है जिसे नियंत्रित करना आवश्यक है: कार्य त्रुटियां, देरी और पुनः प्रारंभ। लेकिन प्रबंधक की सूचना में विफलता ऑर्डर स्टेटस की प्राप्ति को अवरुद्ध नहीं करती।

टीम और ग्राहक के लिए सूचनाएं सेट करें

स्टेटस बदलने के बाद सभी को समान रूप से सूचित करने की आवश्यकता नहीं। प्रबंधक के लिए आमतौर पर रद्दीकरण, त्रुटियां, आंशिक पूर्णता और लंबे समय तक न बदलने वाले ऑर्डर महत्वपूर्ण हैं। ग्राहक के लिए अक्सर स्पष्ट परिणाम पर्याप्त है: ऑर्डर पूर्ण, रद्द या स्पष्टीकरण की आवश्यकता है।

• पूर्ण ऑर्डर — व्यक्तिगत खाते में अपडेट या ग्राहक को संक्षिप्त संदेश।
• निष्पादन त्रुटि — जिम्मेदार व्यक्ति को API द्वारा भेजे गए कारण के साथ सूचना।
• आंशिक पूर्णता — समायोजन, वापसी या अगली क्रिया की जांच का कार्य।
• अज्ञात स्टेटस — लॉग में प्रविष्टि और तकनीकी विशेषज्ञ को संदेश।
• अज्ञात ऑर्डर ID — आपके सिस्टम और प्रदाता के बीच संबंध की अलग जांच।

प्रत्येक तकनीकी संक्रमण पर संदेश न भेजें। फ़ीड जल्दी शोर में बदल जाएगी और महत्वपूर्ण समस्या अनदेखी रह जाएगी। आंतरिक सूचना में ऑर्डर संख्या, सेवा, वर्तमान स्टेटस, बाहरी ID और कार्ड का लिंक होना चाहिए।

लॉग रखें और अपूर्ण ऑर्डर का मिलान करें

लॉग यह समझने के लिए आवश्यक हैं कि सेवा ने इवेंट भेजा या नहीं, कौन सी बॉडी आई, सिग्नेचर क्यों विफल हुआ और प्रोसेसिंग किस चरण पर रुकी। प्राप्ति का समय, इवेंट ID, ऑर्डर ID, इवेंट प्रकार, सिग्नेचर सत्यापन परिणाम, आंतरिक स्टेटस और उत्तर कोड सहेजें। सीक्रेट, टोकन और व्यक्तिगत डेटा मास्क करें।

डिलीवरी त्रुटियों, अमान्य सिग्नेचर, अज्ञात ऑर्डर, असमर्थित स्टेटस, डुप्लिकेट और स्थिति क्रम के कारण लागू न हो सकने वाले इवेंट की अलग से निगरानी करें। ऐसी प्रविष्टियों की वृद्धि API स्कीमा परिवर्तन, समाप्त सीक्रेट, मार्ग विफलता या हैंडलर लॉजिक में त्रुटि का संकेत दे सकती है।

समय-समय पर API डेटा प्राप्ति विधि के माध्यम से मध्यवर्ती स्टेटस वाले ऑर्डर का मिलान करें। यह जांच वेबहुक की जगह नहीं लेती, लेकिन छूटे इवेंट, कतार विफलता या ऐसे मामले का पता लगाने में मदद करती है जब बाहरी स्टेटस सही सूचना के बिना बदल गया।