تخطَّ إلى المحتوى

التطبيقات والمفاتيح

GET /v1/apps

النطاق read:creatives.

Terminal window
curl -s https://api.ad80.dev/v1/apps -H "Authorization: Bearer $AD80_API_KEY"
{
"apps": [
{
"appId": "com.example.news",
"name": "Example News",
"createdAt": "2026-10-20T08:00:00Z",
"lastUploadAt": "2026-10-28T09:12:44Z",
"sdkVersion": "0.2.0",
"policyVersion": 3,
"creativeCount": 412,
"playground": false
}
]
}

القيمة playground: true تميّز تطبيق «جرّب سياستك» الخاص بمؤسستك، فاستبعده من قوائم تطبيقات SDK. يمثّل lastUploadAt آخر رفع مقبول من SDK (ويكون null قبل أول رفع). وقد يكون sdkVersion وpolicyVersion بقيمة null.

GET /v1/apps/{appId}

النطاق read:creatives. يرجع تطبيقًا واحدًا بالشكل نفسه. استعلم عنه بشكل متكرر لتنتظر أول رفع (lastUploadAt). يرد بالرمز 404 إن لم يكن التطبيق موجودًا في مؤسستك.

POST /v1/apps

النطاق manage:keys.

Terminal window
curl -s -X POST https://api.ad80.dev/v1/apps \
-H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \
-d '{"appId": "com.example.news", "name": "Example News"}'
الحقلالشروط
appIdمطلوب. معرّف التطبيق: معرّف تطبيق Android، أو معرّف الحزمة (bundle identifier) في iOS الذي يرسله SDK. مقطعان على الأقل تفصل بينهما نقاط، يبدأ كل مقطع بحرف، ثم حروف أو أرقام أو _. حتى 150 حرفًا. لا تُقبل الشرطة (-)، فمعرّف الحزمة الذي يحتوي شرطة (وتسمح بها Apple) يُرفض حالياً بالرمز 400.
nameاسم للعرض، اختياري، حتى 100 حرف.

يرد بالرمز 201 ومعه التطبيق. ويرد بالرمز 409 إن كان معرّف التطبيق موجودًا من قبل في مؤسستك.

GET /v1/keys

النطاق manage:keys. يعرض مفاتيح الرفع (ingest) ومفاتيح API (client). لا يرجع المفاتيح السرية أبدًا، بل prefix فقط، وهو جزء غير سري (أول 12 حرفًا).

{
"keys": [
{
"id": "ik_7",
"type": "ingest",
"prefix": "ad80_ik_Ab3x",
"label": "Release build",
"appId": "com.example.news",
"createdBy": "user:31",
"createdAt": "2026-10-20T08:01:00Z",
"lastUsedAt": "2026-10-28T09:12:44Z",
"expiresAt": null,
"revokedAt": null
},
{
"id": "ck_3",
"type": "client",
"prefix": "ad80_ck_Q9zL",
"label": "Nightly export",
"scopes": ["read:creatives", "read:verdicts"],
"createdBy": "user:31",
"createdAt": "2026-10-21T10:00:00Z",
"lastUsedAt": null,
"expiresAt": "2027-10-21T10:00:00Z",
"revokedAt": null,
"rotatedFrom": "ck_1"
}
]
}

يُحدَّث lastUsedAt مرة واحدة في الدقيقة على الأكثر.

POST /v1/keys

النطاق manage:keys.

الحقلمعناه
typeclient (الافتراضي) أو ingest.
labelاختياري، حتى 100 حرف.
scopesلمفاتيح API: نطاق واحد على الأقل. لا يمنح المفتاح إلا نطاقات يملكها هو نفسه (وإلا فالرد 403).
appIdلمفاتيح الرفع: التطبيق الذي يرفع المفتاح باسمه (مطلوب إلا عند التجديد).
expiresInDaysاختياري، من 0 إلى 3650. القيمة 0 أو غياب الحقل: بلا انتهاء.
rotatesاختياري: معرّف مفتاح نشط تريد استبداله، مثل ik_7 أو ck_3. يأخذ المفتاح الجديد نطاقات المفتاح القديم أو تطبيقه.
graceHoursمع rotates: تنتهي صلاحية المفتاح القديم بعد هذا العدد من الساعات (من 0 إلى 8760). القيمة 0 أو غياب الحقل: يبقى المفتاح القديم صالحًا حتى تبطله بنفسك.

إنشاء مفتاح رفع لتطبيق:

Terminal window
curl -s -X POST https://api.ad80.dev/v1/keys \
-H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \
-d '{"type": "ingest", "appId": "com.example.news", "label": "Release build"}'

إنشاء مفتاح API للقراءة فقط تنتهي صلاحيته بعد سنة:

Terminal window
curl -s -X POST https://api.ad80.dev/v1/keys \
-H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \
-d '{"type": "client", "label": "BI export", "scopes": ["read:creatives", "read:verdicts"], "expiresInDays": 365}'

تجديد مفتاح رفع، مع إبقاء القديم صالحًا 30 يومًا ريثما يصل تحديث التطبيق إلى المستخدمين:

Terminal window
curl -s -X POST https://api.ad80.dev/v1/keys \
-H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \
-d '{"rotates": "ik_7", "graceHours": 720}'

الرد 201. الحقل key هو المفتاح السري، ولن تراه إلا هنا:

{
"id": "ik_8",
"key": "ad80_ik_THE_NEW_SECRET",
"prefix": "ad80_ik_Zx81",
"expiresAt": null,
"note": "the key is shown once; store it now"
}

مفاتيح API ترجع معها scopes أيضًا. وإن حاولت إنشاء مفتاح رفع على باقة لا تشمل الربط مع SDK، يكون الرد 403 مع entitlement: sdk_ingest.

POST /v1/keys/{id}/revoke

النطاق manage:keys. قيمة id هي ck_<n> أو ik_<n>. يتوقف المفتاح عن العمل فورًا.

Terminal window
curl -s -X POST https://api.ad80.dev/v1/keys/ik_7/revoke -H "Authorization: Bearer $AD80_API_KEY"
{ "id": "ik_7", "revoked": true }

في حالات نادرة يضيف الرد الحقل warning، وعندها يسري الإبطال خلال 30 ثانية.