links
POST /v1/site-links/ingest
Receive one batch of a site's outbound-link scan (signed webhook).
احراز هویت
این نقطه پایانی عمومی است. هیچ مدرک احراز هویت و هیچ سازمانی نمیپذیرد — این همان چیزی است که سایت بازاریابی خودمان و موتورهای پاسخدهنده هوش مصنوعی میخوانند.
این نقطه پایانی هیچ شناسه سازمانی را دریافت نمیکند. کلید شما در حال حاضر سازمان مربوطه را مشخص میکند و پاسخ در همان محدوده ارائه میشود.
امتحان کنید
هر چیزی را که داخل براکتهای زاویهدار قرار دارد با مقادیر خودتان جایگزین کنید، و نگهدارنده کلید را با کلیدی از داشبورد خود جایگزین نمایید.
curl -X POST https://api.zinndigital.com/v1/site-links/ingest \
-H "Content-Type: application/json" \
-d '{ "site": <string>, "scan_id": <string> }'وارد شدهاید؟ کنسول API در داشبورد شما شناسه سازمان واقعی و کلید خودتان را پر میکند و درخواست را روی API زنده اجرا میکند تا بتوانید پاسخ واقعی را ببینید. این نقطه پایانی را در کنسول API باز کنید
جزئیات
What a site's Zinn® plugin POSTs when its scheduled link scan runs: the posts it looked at, and for each one every outbound <a> tag it found, with how many times that tag appears in that post. Machine-to-machine; there is no principal. Authentication is the same HMAC scheme ingestSiteEvents uses — SHA-256 over "<timestamp>\n<body>" in X-Zinn-Cache-Signature, with X-Zinn-Cache-Timestamp carrying the unix seconds, against a secret derived per site from the platform master key. ⛔ Deliberately not a second scheme: one secret, one derivation, one place for the two ends to agree. The organisation comes from the resolved site and never from the body. A scan is a SNAPSHOT, delivered in batches. One pass over a site carries one scan_id across as many requests as it takes; the request carrying complete: true triggers reconciliation, which deletes every post and placement for that site not stamped with that pass. ⛔ That is what makes a link the customer removed disappear from the report — an append-only index rots into a permanent overcount and looks authoritative while it does. ⛔ An abandoned pass deletes nothing. No completing batch, no sweep: the report goes stale rather than wrong-by-deletion. ⛔ A batch from a superseded pass is ignored whole and answers ignored: true. The plugin's POST is fire-and-forget with a two-second timeout, so a batch landing after the next cron tick has begun is expected; mixing it in would let a finished pass sweep away the live one's rows. Every refusal is uninformative on purpose — an unknown hostname is a bare 404 and a bad signature a bare 401, because a chattier answer would tell anyone who can guess a hostname which domains this platform hosts.
پارامترها
| نام | نوع | الزامی | چیست |
|---|---|---|---|
X-Zinn-Cache-Timestamp (header) | string | بله | Unix seconds. Signed as part of the material, which is what bounds a replay. |
X-Zinn-Cache-Signature (header) | string | بله | sha256=<hex>. |
بدنه درخواست
| نام | نوع | الزامی | چیست |
|---|---|---|---|
site | string | بله | The site's own home_url(). An untrusted claim — it selects which site's derived secret the signature is checked against, and nothing more. |
scan_id | string | بله | Identifies the pass, not the request. Minted by the plugin, because one pass spans many requests and the engine cannot mint it. Opaque: nothing is inferred from its value, and… |
complete | boolean | خیر | ⛔ Only a literal true ends the pass. A missing key, a null or the string "false" all mean "not complete", because reading one as complete would sweep away every post the… |
posts_sent | integer | خیر | Posts this pass has sent so far, cumulative across batches, as counted by the site. ⛔⛔ Load-bearing on the completing batch: the POST is non-blocking, so a site never learns… |
posts | object[] | خیر | — |
پاسخ
| نام | نوع | الزامی | چیست |
|---|---|---|---|
accepted | boolean | بله | — |
ignored | boolean | بله | The batch belonged to a superseded pass and was dropped whole. Expected occasionally: the plugin's POST is fire-and-forget with a two-second timeout. |
posts | integer | بله | — |
links | integer | بله | — |
truncated | boolean | بله | A post reported more links than the per-post ceiling and the tail was dropped. Surfaced rather than swallowed — a report that silently under-counts is worse than one that says it… |
reconciled | boolean | بله | This batch completed the pass, so the snapshot sweep ran. |
removed | integer | بله | Rows the sweep deleted. ⭐ The only externally visible proof the snapshot reconciliation works: a site whose links change while this stays 0 on every pass is the append-only rot… |
refused | string | خیر | Why a completing batch was not swept, when it was not — a lost batch, or one whose post list was truncated. ⛔ Reported rather than swallowed: a pass that keeps completing… |
خطاهایی که این نقطه پایانی میتواند برگرداند
401 · 404 · 422 · 503