Pagpapatotoo
Magpadala ng API key bilang isang bearer token. Kailangang taglayin ng key ang pahintulot na sites.view; ang key na wala nito ay tatanggihan gamit ang 403, hindi 404.
Ang endpoint na ito ay hindi nangangailangan ng id ng organisasyon. Natutukoy na ng iyong key ang organisasyong kinabibilangan nito, at nakatuon ang tugon dito.
Subukan ito
Palitan ang anuman sa loob ng mga panaklong na may anggulo ng iyong sariling mga halaga, at ang placeholder ng key na may key mula sa iyong dashboard.
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> }'Nakalagda? Ang API console sa iyong dashboard ay awtomatikong naglalagay ng iyong tunay na ID ng organisasyon at sariling susi, at pinapatakbo ang kahilingan laban sa live na API upang makita mo ang aktwal na tugon. Buksan ang endpoint na ito sa console ng API
Mga Detalye
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).
Mga Parameter
| Pangalan | Uri | Kailangan | Ano ito |
|---|---|---|---|
Idempotency-Key (header) | string | Hindi | Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats. |
Katawan ng kahilingan
| Pangalan | Uri | Kailangan | Ano ito |
|---|---|---|---|
operation | BulkOperation | Oo | 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 | Oo | 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 | Hindi | 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[] | Hindi | 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 | Hindi | 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 | Hindi | 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 | Hindi | Free text kept with the job, for whoever reads the report later. |
Tugon
| Pangalan | Uri | Kailangan | Ano ito |
|---|---|---|---|
id | Uuid | Oo | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
org_id | Uuid | Oo | UUIDv7 identifier — sortable by creation time (docs/02 §8). |
operation | BulkOperation | Oo | 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 | Oo | 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 | Oo | 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 | Oo | — |
status | BulkJobStatus | Oo | ⛔ `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 | Oo | Who asked for it. |
note | string | Oo | — |
created_at | string | Oo | — |
updated_at | string | Oo | — |
settled_at | object | Oo | When the job finished; `null` while it is still running. |
counts | BulkJobCounts | Oo | — |
progress | BulkJobProgress | Oo | 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`… |
Mga error na maibabalik ng endpoint na ito
401 · 403 · 409 · 422 · 429