المصادقة
أرسل مفتاح واجهة برمجة التطبيقات (API key) كرمز حامل (bearer token). يجب أن يحمل المفتاح إذن sites.view؛ والمفتاح الذي لا يملكه يُرفض بالرمز 403 وليس 404.
لا يقبل هذا الطرف أي معرف للمؤسسة. يحدد مفتاحك بالفعل المؤسسة التي ينتمي إليها، وتكون الاستجابة محصورة في نطاقها.
جربه الآن
استبدل أي شيء بين أقواس زاوية بقيمك الخاصة، والعنصر النائب للمفتاح بمفتاح من لوحة تحكمك.
curl -X POST https://api.zinndigital.com/v1/bulk-jobs \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "operation": <BulkOperation>, "selector": <BulkSelector> }'هل سجلت الدخول؟ تقوم وحدة تحكم واجهة برمجة التطبيقات في لوحة التحكم الخاصة بك بربط معرف مؤسستك الحقيقي ومفتاحك الخاص، وتنفذ الطلب مقابل واجهة برمجة التطبيقات المباشرة لتتمكن من رؤية الاستجابة الفعلية. افتح هذه النهاية الطرفية في وحدة تحكم API
التفاصيل
Freezes the selection into a per-site work-list and starts a durable, idempotent workflow. **The submit is instant and the work is not** — this returns `202` as soon as the rows are written, and nothing a person is watching waits on the job itself. Only **eligible** sites are enrolled; ineligible ones are not written as pre-failed rows, because a report padded with rows that never had a chance makes the failures that matter harder to find. `previewBulkJob` is where you see them. A selection that enrolls **nothing** is a `422`, not a job that completes instantly: "completed, 0 of 0" is indistinguishable from success on every screen that renders it. ⛔ A typed `confirm` phrase is required when the selector is wider than an explicit list (`product_line`, `org`) **or** the operation is weighty (`plugin_remove`, `plugin_deactivate`, `blueprint_apply`) at any size. `previewBulkJob` returns the exact phrase in `confirmation_phrase`. ⛔ All the selected sites must belong to **one** organization. A mixed selection is a `422` naming the problem rather than a job whose owner is a guess. Requires `sites.view` plus the operation's own key (see the tag description).
المعلمات
| الاسم | النوع | مطلوب | ما هو هذا |
|---|---|---|---|
Idempotency-Key (header) | string | لا | Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats. |
جسم الطلب
| الاسم | النوع | مطلوب | ما هو هذا |
|---|---|---|---|
operation | BulkOperation | نعم | What a bulk job does to each of its sites. ⛔ One job model with an operation discriminator, not eight job models. A selection, a frozen work-list, a durable pass and a per-site… |
selector | BulkSelector | نعم | Which sites a job targets. ⛔ There is no `all`. A job belongs to exactly one organization and `all` would span every tenant on the platform; the fleet-wide act is a staff operat… |
selector_value | string | لا | The selector's argument — a product-line code for `product_line`, an organization id for `org`, a site-group id for `group`. Ignored for `sites`, whose members are `site_ids`. |
site_ids | Uuid[] | لا | The explicit selection, for `selector: sites`. Every id is fenced to the organizations you can reach, so one belonging to somebody else resolves to nothing rather than to a cros… |
params | BulkJobParams | لا | The operation's arguments. Which keys are read depends on `operation`: `plugin_install` takes `slugs` + `activate`; `plugin_activate`, `plugin_deactivate` and `plugin_remove` ta… |
confirm | string | لا | The typed confirmation phrase, required when `previewBulkJob` answers `confirmation_required: true`. Send exactly the value it returned in `confirmation_phrase`. ⛔ Whether it is… |
note | string | لا | Free text kept with the job, for whoever reads the report later. |
الاستجابة
| الاسم | النوع | مطلوب | ما هو هذا |
|---|---|---|---|
id | Uuid | نعم | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
org_id | Uuid | نعم | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
operation | BulkOperation | نعم | What a bulk job does to each of its sites. ⛔ One job model with an operation discriminator, not eight job models. A selection, a frozen work-list, a durable pass and a per-site… |
params | BulkJobParams | نعم | The operation's arguments. Which keys are read depends on `operation`: `plugin_install` takes `slugs` + `activate`; `plugin_activate`, `plugin_deactivate` and `plugin_remove` ta… |
selector | BulkSelector | نعم | Which sites a job targets. ⛔ There is no `all`. A job belongs to exactly one organization and `all` would span every tenant on the platform; the fleet-wide act is a staff operat… |
selector_value | string | نعم | — |
status | BulkJobStatus | نعم | ⛔ `partial` is a real outcome, not a rounding of the other two. A job where 4 of 900 sites failed is neither a success nor a failure, and reporting it as either is how a bulk ac… |
requested_by | string | نعم | Who asked for it. |
note | string | نعم | — |
created_at | string | نعم | — |
updated_at | string | نعم | — |
settled_at | object | نعم | When the job finished; `null` while it is still running. |
counts | BulkJobCounts | نعم | — |
progress | BulkJobProgress | نعم | How far along a job is, how fast it is going and how much longer it has. ⛔⛔ **Every estimate here is nullable, and a `null` must never be rendered as `0`.** `rate_per_minute: 0`… |
الأخطاء التي يمكن أن تُرجعها نقطة النهاية هذه
401 · 403 · 409 · 422 · 429