तृतीय-पक्ष नोटिफिकेशन इंटीग्रेशन

त्वरित शुरुआत

Web Admin में लक्षित कंपनी से जुड़ा तृतीय-पक्ष ऐप बनाएँ। App ID और App Secret कॉपी करें; अंतिम परिणाम चाहिए तो वैकल्पिक Callback URL सेट करें। Engine जुड़ी कंपनी के प्रत्येक सक्रिय और योग्य उपयोगकर्ता के लिए सूचना केंद्र रिकॉर्ड बनाता है तथा सिस्टम Push केवल योग्य पंजीकृत डिवाइसों पर भेजने का प्रयास करता है।

Endpoint और प्रमाणीकरण

API वातावरण:

• परीक्षण: https://aim-api-test.proton-system.com
• उत्पादन: https://aim-api.proton-system.com

हर server-to-server JSON request में HTTP Basic Authentication के जरिए Authorization: Basic Base64(KEY:SECRET) भेजें, जहाँ KEY App ID और SECRET App Secret है:

Endpoint: POST /openapi/v1/notifications।

curl --request POST 'https://<your-engine-host>/openapi/v1/notifications' \
  --header 'Authorization: Basic <Base64(AppID:AppSecret)>' \
  --header 'Content-Type: application/json' \
  --data '{"requestId":"order-20260819-001","title":"ऑर्डर पूरा हुआ","body":"आपका ऑर्डर पूरा हो गया है।","imageUrls":["https://cdn.example.com/order/001-1.webp","https://cdn.example.com/order/001-2.webp"]}'

अनुरोध अनुबंध

सख्त JSON में आवश्यक requestId, title और body के साथ वैकल्पिक imageUrls स्वीकार होता है। imageUrls न भेजना, या null अथवा [] भेजना, कोई चित्र न होने का संकेत है; अन्यथा प्रदर्शन क्रम में 1-9 URL भेजें। हर मान से किनारे के खाली स्थान हटते हैं, वह अद्वितीय होना चाहिए, username या password के बिना पूर्ण HTTPS URL होना चाहिए और अधिकतम 2048 Unicode अक्षर का हो सकता है। कोई भी URL अमान्य होने पर पूरा अनुरोध अस्वीकार होता है। Engine URL संग्रहीत करता है, लेकिन चित्र fetch, probe, proxy या cache नहीं करता। पूरा body अधिकतम 256 KiB है; requestId 128 Unicode अक्षर, title 100 और body 1000 अक्षर तक हो सकते हैं। हर App ID के लिए प्रति मिनट 10 और प्रति घंटा 100 अनुरोध की सीमा है।

समान requestId, title, body और उसी क्रम के imageUrls दोहराने पर पहले से संग्रहीत परिणाम मिलता है; इसलिए प्रक्रिया पूरी होने के बाद उसका status, ACCEPTED के बजाय SUCCESS, PARTIAL_SUCCESS या FAILED हो सकता है। उसी requestId को बदली सामग्री या चित्र क्रम के साथ भेजने पर IDEMPOTENCY_CONFLICT मिलता है।

स्वीकृति प्रतिक्रिया

मान्य अनुरोध HTTP 202 लौटाता है:

{
  "requestId": "order-20260819-001",
  "notificationId": "00000000-0000-0000-0000-000000000001",
  "status": "ACCEPTED"
}

ACCEPTED का अर्थ केवल यह है कि Engine ने अनुरोध वितरण के लिए सहेजा है; यह APNs/FCM या डिवाइस पर प्रदर्शन की पुष्टि नहीं है।

Callback परिणाम

Callback URL सेट होने पर Engine अंतिम परिणाम भेजता है:

{
  "requestId": "order-20260819-001",
  "status": "PARTIAL_SUCCESS",
  "recipientCount": 8,
  "pushAcceptedCount": 1,
  "pushFailedCount": 1
}

recipientCount सूचना केंद्र के प्राप्तकर्ता उपयोगकर्ताओं की संख्या है। pushAcceptedCount और pushFailedCount Push Outbox बैच की संख्याएँ हैं; ये उपयोगकर्ता या डिवाइस की संख्या अथवा सिस्टम बैनर पहुँचने का प्रमाण नहीं हैं।

Callback परीक्षण

एडमिन पैनल से हर Callback परीक्षण एक अलग प्रोब इवेंट भेजता है:

{
  "requestId": "callback-test-<unique-id>",
  "status": "SUCCESS",
  "recipientCount": 1,
  "pushAcceptedCount": 1,
  "pushFailedCount": 0,
  "test": true
}

जब test का मान true हो, संरचना जाँचकर 2xx लौटाएँ, लेकिन प्रोब को भेजे गए किसी नोटिफिकेशन अनुरोध से न जोड़ें और व्यावसायिक डिलीवरी स्थिति न बदलें। गिनतियाँ स्थिर परीक्षण मान हैं; वे वास्तविक प्राप्तकर्ता या Push Outbox बैच नहीं हैं।

अंतिम status SUCCESS, PARTIAL_SUCCESS या FAILED होता है। किसी भी 2xx से पुष्टि करें, अन्यथा 1 मिनट, 5 मिनट, 30 मिनट, 2 घंटे, 6 घंटे और 24 घंटे बाद पुनः प्रयास होता है। अभी HMAC हस्ताक्षर नहीं है: HTTPS अनिवार्य करें, गैर-परीक्षण परिणामों के requestId मिलाएँ, पहुँच सीमित रखें और Callback को idempotent रूप से संभालें।

त्रुटि संदर्भ

सुरक्षा और वितरण सीमा

Mobile client प्रति चित्र अधिकतम 5 MiB स्वीकार करता है और पूरी चित्र डाउनलोड प्रक्रिया की समय-सीमा 10 सेकंड है। Client 3xx redirect का अनुसरण नहीं करता, इसलिए हर URL को चित्र सीधे लौटाना होगा।

App ID और App Secret केवल server-to-server क्रेडेंशियल हैं। इन्हें browser, mobile app, सार्वजनिक repository, URL या client storage में न रखें। रिसाव पर App Secret रीसेट करें। जुड़ी कंपनी के प्रत्येक सक्रिय और योग्य उपयोगकर्ता को सूचना केंद्र रिकॉर्ड मिलता है और वह recipientCount में गिना जाता है। सिस्टम Push केवल उस सक्रिय PushInstallation पर आज़माया जाता है जो BUSINESS श्रेणी की अनुमति देता है; फिर भी हर डिवाइस पर सिस्टम बैनर की गारंटी नहीं है। imageUrls केवल notification detail में दिखते हैं और Push या Callback payload में नहीं जाते। title और body चित्रों के बिना भी पूर्ण और समझने योग्य होने चाहिए। चित्र डाउनलोड या रेंडर विफल होने पर accepted, Callback या Push status नहीं बदलता। Mobile client हर चित्र सीधे public CDN से डाउनलोड करता है; authentication या Cookie रहित URL दें, उन्हें कम से कम 90 दिन उपलब्ध रखें और ध्यान रखें कि CDN को उपयोगकर्ता का IP, request time और User-Agent मिलेगा। स्थिर ऐतिहासिक प्रदर्शन के लिए immutable object URL इस्तेमाल करें।