# کسٹم لائسنسنگ سسٹم انضمام کی رہنمائی

موجودہ سورس کوڈ دو لائسنس فراہم کنندگان کی حمایت کرتا ہے: Licentivo اور `custom_http`۔ مرچنٹ **سسٹم کی ترتیبات → لائسنسنگ سسٹم** میں ایک فراہم کنندہ منتخب اور فعال کرتا ہے؛ تمام مصنوعات اور sandbox/live ماحول ایک ہی فراہم کنندہ استعمال کرتے ہیں۔ کسٹم کنکشن اور پلان میپنگ ہر پروڈکٹ اور ماحول کے لیے الگ ترتیب دی جاتی ہیں۔ اس خصوصیت میں خود بنایا گیا لائسنسنگ سسٹم شامل نہیں؛ مرچنٹ اپنی لائسنسنگ سروس اور SDK استعمال کرتا رہتا ہے۔

موجودہ Licentivo اکاؤنٹ ایکسچینج، نو زبانوں کا SDK اور ڈیوائس مینجمنٹ موجودہ طریقے سے جاری رہتے ہیں۔ کسٹم مصنوعات اس دستاویز کے پروٹوکول کے ذریعے خریداری کی حیثیت ہم آہنگ کرتی ہیں؛ صارف اکاؤنٹ سینٹر میں لائسنس کی فراہمی دیکھتا ہے اور Licentivo SDK کے عمل میں داخل نہیں ہوتا۔

## فوری آغاز

1. اپنی سروس میں ذیل کے چار HTTP انٹرفیس نافذ کریں اور ہر کنکشن کے لیے الگ HMAC دستخطی کلید اور شناخت کنندہ ترتیب دیں۔
2. “لائسنسنگ سسٹم” میں “کسٹم لائسنسنگ سروس” منتخب کریں، نیا کنکشن شامل کریں، پتہ، ماحول، کنکشن شناخت کنندہ، key ID اور معیاری Base64 کلید درج کریں۔ تصدیق کے بعد محفوظ کریں اور “کسٹم لائسنسنگ سروس فعال کریں” پر کلک کریں۔
3. پروڈکٹ اور سیلز پلان کے مسودے بنائیں۔ خریداری کی قسم اور قیمت Launch میں منظم ہوتی ہیں؛ لائسنس کے قواعد آپ کے اپنے سسٹم میں منظم ہوتے ہیں۔
4. پروڈکٹ اور ماحول منتخب کریں، کنکشن منتخب کریں، بیرونی پروڈکٹ اور پلان کے حوالے درج کر کے محفوظ کریں۔ فراہم کنندہ پوری سائٹ کی انتخابی ترتیب سے طے ہوتا ہے؛ دوسری مصنوعات کے لیے بیک وقت Licentivo فعال نہیں کیا جا سکتا۔
5. سیلز پلان صفحے پر آزمائشی ورژن شائع کریں، ادائیگی، فراہمی، تجدید، اپ گریڈ، رقم کی واپسی اور خرابی سے بحالی کے قبولیتی ٹیسٹ مکمل کریں، پھر پروڈکشن ماحول الگ ترتیب دیں۔

بنانے کے بعد پتہ، ماحول، کنکشن شناخت کنندہ اور نیٹ ورک رسائی کی پالیسی تبدیل نہیں ہو سکتی؛ ضرورت پر نیا کنکشن بنائیں۔ دستخطی کلید تبدیل کی جا سکتی ہے؛ خالی چھوڑنے سے پرانی کلید برقرار رہتی ہے۔ دوسرے لائسنسنگ سسٹم کے آرڈرز موجود ہوں تو پوری سائٹ کا فراہم کنندہ براہ راست تبدیل نہیں ہو سکتا؛ پہلے منتقلی مکمل کریں۔ تبدیلی کے بعد پرانے پلان صرف پیش نظارہ بن جاتے ہیں اور دوبارہ شائع کرنا ضروری ہے؛ محفوظ کنکشن اسناد اور میپنگ برقرار رہتی ہیں۔ موجودہ آرڈرز والے پروڈکٹ کا کنکشن براہ راست تبدیل نہیں ہو سکتا اور زیر فروخت میپنگ بھی براہ راست نہیں بدلی جا سکتی؛ نئی قیمت یا میپنگ کے لیے پلان کا نیا ورژن استعمال کریں۔

API سے ترتیب دیتے وقت پہلے `PUT /api/v1/admin/licensing/provider` کال کریں، درخواست کا باڈی `{"provider":"custom_http"}` یا `{"provider":"licentivo"}` ہو، پھر پروڈکٹ میپنگ محفوظ کریں۔ غیر فعال فراہم کنندہ کے لیے پروڈکٹ لائسنس بائنڈنگ یا Licentivo پلان پالیسی میپنگ محفوظ نہیں ہو سکتی۔

کنکشن کی جانچ پروٹوکول، توثیق، ماحول اور معاون خریداری کی اقسام کی تصدیق کرتی ہے؛ مرچنٹ کے لیے بیرونی پلان نہیں بناتی یا تصدیق نہیں کرتی۔ حقیقی ادائیگی لینے سے پہلے حقیقی بیرونی پلان کے ساتھ sandbox انضمام کا قبولیتی امتحان مکمل کرنا ضروری ہے۔

## 3. مرچنٹ انضمام کا عمل

1. موجودہ لائسنسنگ سسٹم کے سامنے اس دستاویز کے چار انٹرفیس نافذ کریں؛ سسٹم کی موجودہ لائسنس منطق برقرار رکھیں۔
2. Launch میں نیا “کسٹم لائسنسنگ سروس” کنکشن بنائیں اور HTTPS پتہ، کنکشن شناخت کنندہ، ماحول اور دستخطی کلید ترتیب دیں۔
3. Launch صلاحیت کی جانچ کا انٹرفیس کال کر کے پروٹوکول ورژن، مستقل/محدود مدت خریداری کی حمایت اور فراہمی کا طریقہ تصدیق کرتا ہے۔
4. پروڈکٹ کے لیے یہ کنکشن منتخب کریں؛ سیلز پلان ورژن کو بیرونی `product_ref` اور `plan_ref` سے میپ کریں۔ بیرونی شناخت کے لیے مرچنٹ کے اپنے سٹرنگ استعمال ہو سکتے ہیں؛ Licentivo UUID لازم نہیں۔
5. sandbox میں ادائیگی، تجدید، اپ گریڈ، رقم کی واپسی اور خرابی سے بحالی کا قبولیتی امتحان مکمل کریں، پھر live ترتیب الگ شائع کریں۔
6. ادائیگی کی توثیق کے بعد Launch اسی ڈیٹا بیس ٹرانزیکشن میں آرڈر، خریداری کوریج اور بھیجے جانے والے کام محفوظ کرتا ہے۔
7. پس منظر میں مکمل خریداری سنیپ شاٹ کسٹم لائسنسنگ سروس کو بھیجا جاتا ہے؛ وہ سروس وصولی کا ریکارڈ مستقل محفوظ کرنے کے بعد وصولی کی تصدیق کرتی ہے۔
8. لائسنسنگ سروس ہدف کی حالت پر کارروائی کرتی ہے۔ Launch اصل ایونٹ کی رسید پوچھتا ہے اور صرف `applied` پر ہم آہنگی مکمل مانتا ہے۔
9. Launch لاگ ان اور اس خریداری کے مالک گاہک کی فراہمی کی معلومات پڑھ کر کسٹمر سینٹر میں لائسنس کوڈ، ایکٹیویشن کا راستہ یا سادہ متن کی ہدایات دکھاتا ہے۔ ایپ مرچنٹ کے اپنے لائسنسنگ سسٹم سے جڑتی ہے۔
10. تجدید، اپ گریڈ، رقم کی واپسی، ادائیگی کی واپسی، معطلی اور اختتام ہر ایک مکمل سنیپ شاٹ کا نیا ورژن بناتے ہیں۔ لائسنسنگ سروس تازہ ترین ہدف کی حالت کے مطابق کارروائی کرتی ہے۔

ایک ہی پروڈکٹ کے sandbox/live الگ کنکشن سے منسلک ہیں۔ خریداری کے بعد فراہم کنندہ بدلنے کے لیے الگ منتقلی ضروری ہے؛ پرانے آرڈرز اور کام پس منظر کے انتخاب کے ساتھ خاموشی سے نئی سروس کو نہیں بھیجے جا سکتے۔

## 4. کسٹم لائسنسنگ سروس کے لیے ضروری API

درج ذیل تمام انٹرفیس **مرچنٹ کی لائسنسنگ سروس وصول کرتی ہے اور Launch سرور کال کرتا ہے**۔ `base_url` میں مقررہ پاتھ سابقہ ہو سکتا ہے؛ جدول کے پاتھ اس کے بعد شامل ہوتے ہیں۔

| طریقہ اور پاتھ | مقصد |
| --- | --- |
| `GET /launch/v1/capabilities` | کنکشن کی جانچ، پروٹوکول اور صلاحیتوں کا اعلان |
| `POST /launch/v1/events` | مکمل خریداری کی ہدف حالت وصول کریں؛ دوبارہ کوشش میں اصل ایونٹ استعمال کریں |
| `GET /launch/v1/events/{event_id}` | دریافت کریں کہ ایونٹ واقعی لاگو ہوا یا نہیں، اور گم شدہ جواب بحال کریں |
| `GET /launch/v1/entitlements/{entitlement_ref}/delivery` | دوسرا لائسنس بنائے بغیر موجودہ لائسنس کی فراہمی کی معلومات پڑھیں |

پہلے ورژن میں رسید فعال طور پر پوچھی جاتی ہے؛ آرڈر بدلنے کے لیے نیا بیرونی کال بیک راستہ نہیں بنایا جاتا۔ کسٹم سروس کو ادائیگی کی تصدیق، قیمت تبدیل کرنے یا خریداری کی مدت بدلنے کا اختیار نہیں۔

### 4.1 عمومی اصول اور توثیق

- JSON میں UTF-8؛ وقت کے لیے UTC RFC 3339؛ `version` کے لیے مثبت صحیح عدد استعمال کریں۔
- کامیاب جواب `{"data": {...}, "request_id": "..."}` ہے؛ غلطی کا جواب `{"error": {"code": "...", "message": "..."}, "request_id": "..."}` ہے۔
- ہر ماحول اور کنکشن کے لیے الگ کلید استعمال کریں۔ کلید کم از کم 32 بے ترتیب بائٹس کی ہو؛ Launch میں موجود خفیہ کردہ کلید اسٹوریج کا حوالہ دیں، اسے فرنٹ اینڈ ترتیب، مثال یا ایپ انسٹالیشن پیکیج میں نہ رکھیں۔
- ہر درخواست میں `X-Launch-Key-Id`, `X-Launch-Timestamp`, `X-Launch-Nonce`, `X-Launch-Signature` شامل ہیں۔
- ٹائم اسٹیمپ اعشاری Unix سیکنڈ ہے۔ nonce کم از کم 128 بٹ بے ترتیب قدر کی بغیر پیڈنگ base64url انکوڈنگ ہے؛ ہر نیٹ ورک کوشش پر نئی قدر بنائیں۔

دستخط کا ان پٹ درج ذیل سات اشیا کو ایک ایک نئی سطر سے جوڑنے والے UTF-8 بائٹس ہیں؛ آخر میں نئی سطر شامل نہ کریں:

```text
v1
<key_id>
<timestamp>
<nonce>
<UPPERCASE HTTP method>
<encoded request path and raw query, including the base_url path prefix>
<lowercase hexadecimal SHA-256 digest of the exact request body>
```

`X-Launch-Signature`، `v1=` کے بعد `HMAC-SHA256` نتیجے کی بغیر پیڈنگ base64url انکوڈنگ ہے۔ GET درخواست کا باڈی خالی ہے۔ وصول کنندہ پہلے دستخط اور وقت کی حد جانچے، پھر ڈی سیریلائز کرے؛ مستقل وقت کا موازنہ استعمال کرے، طے شدہ طور پر مثبت و منفی 300 سیکنڈ فرق قبول کرے اور ری پلے روکنے کے لیے nonce کم از کم 600 سیکنڈ رکھے۔ دوبارہ کوششوں میں nonce دوبارہ استعمال نہ کریں، لیکن ایونٹ ID اور کاروباری درخواست کا باڈی یکساں رہیں۔

دستخط HTTPS کا متبادل نہیں۔ درخواست میں گاہک کا پاس ورڈ، ادائیگی کی کلید یا Licentivo انتظامی کلید نہیں ہوتی؛ طے شدہ طور پر صرف گمنام اکاؤنٹ حوالہ بھیجا جاتا ہے، ای میل نہیں۔ سرور HTTP کلائنٹ میں ٹائم آؤٹ، جواب کی لمبائی کی حد اور اسناد کے ساتھ ری ڈائریکٹ کی پیروی روکنا ضروری ہے۔ کسٹم پتہ ترتیب دیتے وقت ہدف کا پتہ جانچیں؛ اندرونی نیٹ ورک تک رسائی منتظم کی واضح ترتیب کردہ تعیناتی صلاحیت ہونی چاہیے۔

### 4.2 صلاحیت کی جانچ

`GET /launch/v1/capabilities` HTTP 200 واپس کرتا ہے، مثلاً:

```json
{
  "data": {
    "protocol": "launch-external-licensing-v1",
    "connection_ref": "merchant-01-sandbox",
    "environment": "sandbox",
    "purchase_types": ["perpetual", "fixed_term"],
    "delivery_types": ["license_key", "activation_url", "instructions"],
    "devices": false,
    "identity_exchange": false
  },
  "request_id": "check-001"
}
```

`protocol`, `connection_ref`, `environment`, `purchase_types`, `delivery_types` لازم ہیں۔ آخری دو غیر خالی arrays ہوں؛ غیر معاون خریداری کی قسم فروخت کے لیے شائع نہیں ہو سکتی۔ پہلے ورژن میں `devices` اور `identity_exchange` لازماً `false` ہوں؛ توسیعی معاہدہ اور نفاذ مکمل ہونے کے بعد ہی حمایت کا اعلان جائز ہے۔

### 4.3 خریداری سنیپ شاٹ

`POST /launch/v1/events` درخواست کی مثال:

```json
{
  "schema": "launch-external-licensing-v1",
  "event_id": "7bf84b91-2749-4b01-a6a7-bd527c488ee8",
  "connection_ref": "merchant-01-sandbox",
  "environment": "sandbox",
  "type": "entitlement.snapshot",
  "change_reason": "purchase",
  "account_ref": "customer_opaque_001",
  "entitlement_ref": "purchase_opaque_001",
  "launch_product_id": "c6dd463e-50f7-4b76-8239-0a8ec6fc304b",
  "launch_plan_version_id": "5459a073-9362-4b46-949d-9b0c5d84421a",
  "product_ref": "desktop-editor",
  "plan_ref": "professional-yearly-v1",
  "version": 1,
  "desired_state": "active",
  "valid_from": "2026-10-25T00:00:00Z",
  "valid_until": "2027-10-25T00:00:00Z"
}
```

اوپر کی مثال کے تمام فیلڈ لازم ہیں۔ `valid_until` کا `null` مستقل خریداری ظاہر کرتا ہے؛ دوسری اقدار `valid_from` کے بعد ہونی چاہئیں۔

| فیلڈ | پابندیاں اور معنی |
| --- | --- |
| `event_id` | Launch کا بنایا UUID؛ ایک ہی ایونٹ کی دوبارہ کوشش میں غیر تبدیل |
| `connection_ref` / `environment` | دستخطی کلید کے کنکشن اور ماحول سے مطابقت ضروری ہے |
| `account_ref` | مستحکم گمنام اکاؤنٹ حوالہ؛ وصول کنندہ کنکشن، ماحول اور اس حوالے سے گاہک کی شناخت کرتا ہے |
| `entitlement_ref` | ایک خریداری تعلق کا مستحکم حوالہ؛ سب منسوخ ہونے کے بعد دوبارہ خریداری میں نیا حوالہ استعمال کریں |
| `launch_product_id` / `launch_plan_version_id` | Launch پروڈکٹ اور غیر متغیر پلان ورژن کا UUID |
| `product_ref` / `plan_ref` | انضمام کرنے والے کا ترتیب کردہ بیرونی حوالہ؛ 1–128 ASCII حروف، حروف، اعداد، `_`, `-`, `.` جائز؛ بیرونی پلان خودکار نہیں بنتا |
| `version` | ایک ہی کنکشن، ماحول اور خریداری حوالے کے تحت مسلسل بڑھتا ہدف ورژن |
| `desired_state` | `active`、`suspended`、`expired`、`revoked` |
| `change_reason` | `purchase`、`renewal`、`upgrade`、`refund`、`reversal`、`suspension`、`resumption`、`expiry`、`reconciliation` |

`account_ref`, `entitlement_ref` میں 1–128 حروف، اعداد، انڈر اسکور یا ہائفن استعمال ہوتے ہیں۔ `schema`, `type` مثال کی اقدار پر مقرر ہیں۔ وصول کنندہ `desired_state` اور مکمل مطلق مدت کے مطابق نتیجہ لاگو کرتا ہے، وجہ کی بنیاد پر خود دن نہیں بڑھاتا یا پورا لائسنس منسوخ نہیں کرتا۔

خصوصاً رقم کی واپسی: تجدید یا اپ گریڈ آرڈر واپس کرنے کے بعد بھی درست بنیادی خریداری رہ سکتی ہے؛ تب سنیپ شاٹ `active` رہ سکتا ہے لیکن مدت کم یا پلان تبدیل ہو سکتا ہے۔ صرف لیجر کی دوبارہ گنتی کے بعد درست خریداری کوریج باقی نہ رہے تو متعلقہ اختتامی حالت بھیجی جاتی ہے۔

### 4.4 وصولی، رسید اور بحالی

وصول کنندہ ایونٹ ID، اصل درخواست باڈی کا ڈائجسٹ اور زیر عمل کام مستقل محفوظ کرنے کے بعد ہی HTTP 202 واپس کرے؛ پہلے مکمل ہم آہنگ ڈپلیکیٹ درخواست HTTP 200 واپس کر سکتی ہے۔ دونوں درج ذیل رسید کا ڈھانچہ واپس کرتے ہیں۔

```json
{
  "data": {
    "event_id": "7bf84b91-2749-4b01-a6a7-bd527c488ee8",
    "connection_ref": "merchant-01-sandbox",
    "environment": "sandbox",
    "entitlement_ref": "purchase_opaque_001",
    "version": 1,
    "payload_sha256": "<64-character lowercase hexadecimal SHA-256 digest of the exact event body>",
    "status": "pending",
    "error_code": null
  },
  "request_id": "receipt-001"
}
```

ڈائجسٹ پلیس ہولڈر کو حقیقی ڈائجسٹ سے بدلنا ضروری ہے۔ رسید میں اوپر کے تمام فیلڈ لازم ہیں؛ غلطی نہ ہو تو `error_code`، `null` ہے۔ `GET /launch/v1/events/{event_id}` اسی ڈھانچے کو HTTP 200 کے ساتھ واپس کرتا ہے؛ حالت ہو سکتی ہے:

| `status` | مطلب | Launch کی کارروائی |
| --- | --- | --- |
| `pending` | مستقل محفوظ، اصل لائسنس تبدیلی ابھی مکمل نہیں | بعد میں پوچھیں، ہم آہنگی مکمل نشان زد نہ کریں |
| `applied` | لائسنسنگ سروس تصدیق کرتی ہے کہ ہدف حالت واقعی لاگو ہو گئی | تمام متعلقہ فیلڈ اور ڈائجسٹ جانچنے کے بعد ہم آہنگی مکمل تصدیق کریں |
| `rejected` | یقینی طور پر لاگو نہیں ہو سکتا، مثلاً بیرونی پلان موجود نہیں | خودکار دوبارہ کوشش روک کر واضح غلطی دکھائیں |
| `manual_review` | نتیجہ غیر یقینی یا حالت میں تصادم ہے؛ دستی جانچ ضروری ہے | اصل کام اور ایونٹ محفوظ رکھیں، قابل آڈٹ کارروائی کا انتظار کریں |

فراہمی کی حالت ہم آہنگی کی رسید سے الگ ہے؛ `applied` کو گاہک کی ایپ کا رن ٹائم اجازت نامہ براہ راست نہیں سمجھا جا سکتا۔

قابل اعتماد ہونے کے تقاضے:

- کم از کم ایک بار ترسیل؛ وصول کنندہ کاروباری idempotency یقینی بنائے؛ نیٹ ورک سطح پر “صرف ایک بار کال” کا وعدہ نہیں کیا جا سکتا۔
- ایک ہی ایونٹ ID اور اصل درخواست باڈی پر موجودہ نتیجہ واپس کریں؛ ایک ہی ID اور مختلف باڈی پر HTTP 409 `IDEMPOTENCY_CONFLICT` واپس کریں۔
- پرانا ورژن نئے کو اوور رائٹ نہیں کر سکتا۔ ایک خریداری ورژن کے مختلف ایونٹس یا اہداف خاموشی سے قبول نہ ہوں؛ جانچ کے لیے HTTP 409 `STATE_VERSION_CONFLICT` واپس کریں۔
- POST جواب کھو جائے یا عمل دوبارہ شروع ہو تو Launch پہلے اصل ایونٹ کا GET کرتا ہے؛ واضح `EVENT_NOT_FOUND` کے بعد ہی اصل ID اور باڈی دوبارہ بھیجتا ہے۔
- دور دراز اجراء کا حقیقی نتیجہ غیر واضح ہو تو انضمام کرنے والا اپنے مستقل idempotency حوالے سے بھی جانچے؛ دوبارہ بھیجنے سے دوسرا لائسنس نہ بنے۔
- HTTP 429 میں `Retry-After` کی پابندی کریں؛ ٹائم آؤٹ اور 5xx پر بیک آف سے بحالی کریں؛ حد سے تجاوز پر دستی جانچ۔ توثیق، ترتیب اور کاروباری انکار کو کامیاب ہم آہنگی نہ سمجھیں۔

تجویز کردہ غلطی کوڈ: `SIGNATURE_INVALID`（401）、`SIGNATURE_EXPIRED`（401）、`NONCE_REPLAYED`（409）、`SCOPE_MISMATCH`（403）、`EVENT_NOT_FOUND`（404）、`IDEMPOTENCY_CONFLICT`（409）、`STATE_VERSION_CONFLICT`（409）、`PLAN_UNKNOWN`（422）、`PURCHASE_TYPE_UNSUPPORTED`（422）、`RATE_LIMITED`（429）、`SERVICE_UNAVAILABLE`（503）。 غلطی کے پیغام میں اسناد نہ ہوں۔

### 4.5 لائسنس کی فراہمی

`GET /launch/v1/entitlements/{entitlement_ref}/delivery` صرف اس کنکشن اور ماحول کا موجودہ فراہمی نتیجہ پڑھ سکتا ہے؛ سوال کو نیا اجراء حکم نہ سمجھیں۔ HTTP 200 مثال:

```json
{
  "data": {
    "connection_ref": "merchant-01-sandbox",
    "environment": "sandbox",
    "entitlement_ref": "purchase_opaque_001",
    "version": 1,
    "status": "ready",
    "delivery": {
      "type": "license_key",
      "value": "EXAMPLE-ONLY-NOT-A-REAL-LICENSE",
      "expires_at": null
    }
  },
  "request_id": "delivery-001"
}
```

`status`، `pending`, `ready` یا `unavailable` ہے؛ ready نہ ہو تو `delivery`، `null` ہے۔ ready پر `type` اعلان کردہ `license_key`, `activation_url` یا `instructions` ہو، `value` زیادہ سے زیادہ 4096 UTF-8 بائٹس اور `expires_at` UTC وقت یا `null` ہو۔ تمام متعلقہ جوابی فیلڈ Launch کے موجودہ خریداری ورژن سے ملیں؛ پرانے ورژن کی فراہمی موجودہ نتیجہ نہیں۔

لائسنس کوڈ حساس معلومات ہے؛ فراہمی کا جواب `Cache-Control: no-store` استعمال کرتا ہے، باڈی لاگ نہیں ہوتی اور مستقل رکھنے کی ضرورت پر خفیہ کردہ اسٹوریج استعمال کریں۔ ایکٹیویشن URL صرف کنکشن ترتیب کے اجازت یافتہ HTTPS ذرائع سے قبول کریں؛ instructions سادہ متن میں دکھائیں، HTML یا اسکرپٹ نہ چلائیں۔ منسوخ، مکمل رقم واپس شدہ یا درست خریداری کے بغیر اکاؤنٹ Launch سے فراہمی کی معلومات حاصل نہیں کر سکتا؛ پہلے فراہم شدہ اسناد کی حقیقی تنسیخ بیرونی نظام کرتا ہے۔

## Launch انتظامی اور کسٹمر API

یہ انٹرفیس مرچنٹ کے تعینات کردہ Launch origin کے تحت ہیں، بیرونی سروس کی HMAC کلید سے توثیق نہیں کرتے۔ منتظم موجودہ ویب سائٹ سیشن استعمال کرتا ہے، لکھنے کی درخواست میں `X-CSRF-Token` لازم ہے۔ گاہک صرف اپنی خریداری پڑھ سکتا ہے۔

| طریقہ اور پاتھ | مقصد |
| --- | --- |
| `GET /api/v1/admin/licensing/connections` | `connections`, `bindings`, `mappings` اور `default_provider` واپس کرتا ہے؛ کنکشن فہرست میں صرف کسٹم کنکشن ہیں، Licentivo موجودہ انتظامی انٹرفیس استعمال کرتا ہے |
| `POST /api/v1/admin/licensing/connections` | کسٹم کنکشن جانچ کر شامل کریں |
| `PUT /api/v1/admin/licensing/connections/{id}` | نام، اجازت یافتہ ایکٹیویشن ذرائع اور دستخطی ترتیب میں ترمیم کریں؛ پرانا وصولی پتہ غیر تبدیل |
| `POST /api/v1/admin/licensing/connections/{id}/check` | دوبارہ جانچیں؛ HTTP 200 میں `last_check_error` غیر null ہو تو جانچ ناکام ہے |
| `PUT /api/v1/admin/products/{id}/licensing` | پروڈکٹ کے منتخب ماحول کے لیے فراہم کنندہ، کنکشن اور بیرونی پلان میپنگ ترتیب دیں |
| `GET /api/v1/me/products/{id}/delivery?environment=sandbox` | موجودہ گاہک اپنی موجودہ درست کسٹم خریداری کی لائسنس فراہمی پڑھتا ہے؛ Cookie یا desktop Bearer توثیق |
| `GET /api/v1/licensing/documentation` | یہ دستاویز، لاگ ان ضروری نہیں |
| `GET /api/v1/licensing/protocol` | کسٹم سروس کے نفاذ کے لیے OpenAPI، لاگ ان ضروری نہیں |

نیا کسٹم کنکشن شامل کرنے کا درخواست باڈی:

```json
{
  "provider": "custom_http",
  "name": "My licensing service",
  "base_url": "https://licenses.example.com",
  "environment": "sandbox",
  "connection_ref": "merchant-01-sandbox",
  "key_id": "key-1",
  "signing_key": "<standard Base64 encoding of 32 to 128 random bytes>",
  "allow_private_network": false,
  "allow_local_http": false,
  "activation_origins": ["https://activate.example.com"]
}
```

جواب کا `data` حساس معلومات ہٹایا گیا کنکشن آبجیکٹ ہے؛ دستخطی کلید یا secret ID واپس نہیں ہوتی۔ allow_local_http صرف sandbox کے localhost/لوپ بیک پتوں کے لیے ہے؛ نجی نیٹ ورک HTTPS کے لیے منتظم کی واضح اجازت ضروری ہے۔ خالی کلید صرف موجودہ کنکشن میں ترمیم پر جائز ہے۔ Licentivo اب بھی `POST /api/v1/admin/connections/licentivo` سے ترتیب پاتا ہے۔

پروڈکٹ ترتیب دینے کا درخواست باڈی:

```json
{
  "provider": "custom_http",
  "environment": "sandbox",
  "connection_id": "<id returned when creating the connection>",
  "mappings": [
    {
      "version_id": "<Launch plan version UUID>",
      "product_ref": "desktop-editor",
      "plan_ref": "professional-yearly-v1"
    }
  ]
}
```

Licentivo منتخب کرنے پر `{"provider":"licentivo","environment":"sandbox","mappings":[]}` بھیجیں، اس کی پروڈکٹ/پالیسی میپنگ اب بھی اصل انٹرفیس استعمال کرتی ہے۔ پہلی تبدیلی موجودہ اشاعت کو پیش نظارہ بناتی ہے؛ نئے فراہم کنندہ کے مطابق دوبارہ جانچ اور اشاعت ضروری ہے۔ mappings میں صرف شامل یا برقرار رکھنے والے ورژن ہو سکتے ہیں؛ حذف کرنے سے پرانی میپنگ نہیں مٹتی۔

گاہک کی فراہمی HTTP 200 کا معیاری data envelope ہے؛ خریداری نہ ہو تو 404، Licentivo پروڈکٹ پر 409 `LICENSING_DELIVERY_UNSUPPORTED`، غیر ہم آہنگ، معطل، میعاد ختم یا مکمل رقم واپس ہونے پر 409 `ENTITLEMENT_NOT_READY`، بیرونی سروس عارضی غیر دستیاب یا رسید نہ ملنے پر 503۔ کسٹمر سینٹر کا “لائسنس فراہمی دیکھیں” ملکیت اور حالت دوبارہ جانچتا ہے اور اسناد URL یا لاگ میں نہیں لکھتا۔

کسٹم پروڈکٹ کے Licentivo identity, device, integration-check انٹرفیس 409 `CUSTOM_LICENSING_SDK_REQUIRED` واپس کرتے ہیں۔ پرانا `/credential` اب بھی 410 واپس کرتا ہے۔ ایپ مرچنٹ کا اپنا SDK استعمال کرے، Launch کی `ready` حالت کو رن ٹائم اجازت نہ سمجھے۔

## مثال اور قبولیتی جانچ

[Python پتلے اڈاپٹر کی مثال](/ur/launch-documents/custom-licensing-example/) دستخط، nonce، ایونٹ ڈپلیکیٹ روکنے اور رسید مستقل محفوظ کرنے کا وصول کنندہ فریم ورک فراہم کرتی ہے؛ حقیقی لائسنس کارروائی کے لیے مرچنٹ سسٹم سے انضمام ضروری ہے۔

کسٹم پروٹوکول کا [OpenAPI](/ur/assets/launch/external-licensing-openapi.json) اور Launch کا اپنا [OpenAPI](/ur/assets/launch/openapi.json) الگ الگ دونوں سمتیں بیان کرتے ہیں۔ وصول کنندہ کو Licentivo پروڈکٹ کیٹلاگ، پالیسی کیٹلاگ یا شناختی اعتماد کے انٹرفیس نافذ کرنے کی ضرورت نہیں۔

مقامی توثیق الگ MySQL، حقیقی HTTP اڈاپٹر اور مصنوعی لائسنس/ادائیگی سروس استعمال کرتی ہے، جواب کا ضیاع، دوبارہ آغاز، تجدید، اپ گریڈ، رقم کی واپسی، اکاؤنٹ معطلی، رسید کا عدم مطابقت اور فراہمی کی علیحدگی شامل ہیں۔ پروڈکشن قبولیتی جانچ میں مرچنٹ کی اپنی لائسنس سروس اور ایپ بھی ضروری ہیں۔ غیر اعلان شدہ ڈیوائس، مشترکہ اکاؤنٹ لاگ ان اور آف لائن صلاحیتیں Launch فراہم نہیں کرتا۔