Sayt API sənədi (seoasist-site-api/1)

Bu səhifə saytınızın tətbiq etdiyi SEOAsist Sayt API müqaviləsini (spesifikasiya seoasist-site-api/1) təsvir edir. Paneldəki Tərtibatçı təlimatı → Spesifikasiya sekiyası və Quraşdırma təlimatı eyni müqaviləni daşıyır. Qoşulma addımları üçün SEOAsist Sayt API ilə xüsusi hazırlanmış saytı qoşun səhifəsinə baxın.

#Ümumi qaydalar

• Bütün sonluqlar bir əsas yol altında yerləşir, məsələn, https://example.com/api/seoasist.
• Həmişə JSON formatında cavab verin. JSON olmayan cavab xəta sayılır.
• Heç vaxt yönləndirməyin (30x yoxdur). SEOAsist yönləndirmələri izləmir, buna görə paneldə son API URL-ini saxlayın.
• Uğursuzluq zamanı {"error":"<qısa mesaj>"} ilə 4xx/5xx cavabı verin. Bu mesaj paneldə göstərilir.
• Daxil edilən məlumatları doğrulayın, gövdə ölçüsünü məhdudlaşdırın (~2 MB) və zəngləri jurnala daxil edin (log).
• SEOAsist hər sorğu üçün 25 saniyəlik gözləmə müddəti (timeout) təyin edir. Sorğular SEOAsist-SiteAPI/1.0 (+https://seoasist.com) user agent-indən istifadə edir.
• URL ictimaiyyətə açıq olmalıdır; SEOAsist heç vaxt localhost və ya şəxsi şəbəkə ünvanlarına zəng etmir.

#Autentifikasiya

Hər bir sorğu üç başlığı (header) daşıyır:

• Tokeni SEOASIST_SITE_TOKEN ətraf mühit dəyişənində (environment variable) saxlayın; heç vaxt kodun içində sabit yazmayın. O, paneldə Qoşul düyməsini sıxdıqda yaradılır və sa_ ilə başlayır.
• Tokeni və imzanı sabit vaxtda (constant time) müqayisə edin.
• GET sorğuları üçün xam gövdə boş sətirdir, buna görə imzalanmış mesaj <timestamp>. olur.
• İmza səhvdirsə və ya vaxt damğası 300 saniyədən köhnədirsə, 401 {"error":"unauthorized"} cavabını verin.

const expected = "sha256=" + createHmac("sha256", token).update(`${ts}.${body}`).digest("hex");

#GET /manifest

Qoşulma sınağı bu sonluğu çağırır. Yalnız tətbiq etdiyiniz imkanları sadalayın.

{"spec":"seoasist-site-api/1","platform":"nextjs","name":"My site","capabilities":["rules","content","files"]}

spec seoasist-site-api/ ilə başlamalıdır. Tanınan imkanlar rules, content və files-dir; başqa hər şey nəzərə alınmır. Panel onları SEO qaydaları, Məzmun dərc edilməsi və llms.txt / robots kimi göstərir.

Daha iki əlavə opsional sahə var:

• locales: dərc edə biləcəyiniz dillər (ISO 639-1), məsələn, ["az","ru","en","tr"]. SEOAsist yalnız bu siyahıda olduqda saytın əsas dilindən fərqli dildə məqalə göndərir. Məqalə dil uyğunsuzluğuna görə rədd edilməzdən əvvəl manifest bir dəfə də oxunur.
• ruleKinds: opsional qayda növləri üçün dəstəyi elan edir. Bu gün yeganə opsional növ link-dir; "ruleKinds":["link"] ilə SEOAsist Pixel əvəzinə daxili keçidləri Sayt API-nizə göndərir.

{"spec":"seoasist-site-api/1","platform":"nextjs","name":"My site","capabilities":["rules","content","files"],"locales":["tr","en"],"ruleKinds":["link"]}

#PUT /rules (imkan: rules)

Gövdə: {"rules": Rule[]}. Bu, tam cari qaydalar dəstidir; əvvəllər saxlanılan hər şeyi əvəz edin. Boş massiv bütün qaydaları təmizləyir. Qaydaları saxlayın (verilənlər bazası cədvəli və ya JSON faylı) və render edərkən onları server tərəfində tətbiq edin ki, axtarış botları nəticəni müştəri tərəfindəki JavaScript-də deyil, HTML-də görsünlər.

type Rule = { id: string; kind: string; matchType: "exact" | "prefix" | "regex" | "all"; matchPath: string; payload: object };

Uyğunlaşdırma sondakı sləş olmadan sorğu yolundan istifadə edir (əsas səhifə üçün /):

• exact: yol dəqiq bərabərdir
• prefix: yol matchPath ilə başlayır
• regex: JavaScript RegExp sınağı
• all: hər bir səhifə

Eyni növlü bir neçə qayda uyğun gəldikdə, ən spesifik olanı qalib gəlir: exact > prefix > regex > all.

Bilinməyən növləri saxlayın və onlara məhəl qoymayın. Cavab: {"ok":true,"count":<saxlanılan say>}.

SEOAsist saytın bütün aktivləşdirilmiş qaydalarını göndərir: Pixel sekmasında əlavə edilmiş, tətbiq olunmuş meta təklifləri, Autopilot (Otopilot) planı tapşırıqları tərəfindən yaradılmış qaydalar, təsdiqlənmiş daxili keçidlər və Avto-düzəliş / Qaydalarla düzəlt tərəfindən yaradılanlar. rules imkanı olan qoşulmuş Sayt API saytın qayda kanalı kimi istifadə olunur.

#POST /content (imkan: content)

Gövdə:

{"externalId":null,"type":"post","title":"…","slug":"…","html":"<h2>…</h2>","excerpt":"…","metaTitle":"…","metaDescription":"…","status":"draft","featuredImageUrl":"https://…","tags":["…"],"updateUrl":null,"locale":"tr","translationOf":null}

• externalId verildikdə: həmin elementi yeniləyin.
• updateUrl verildikdə (type: "page"): həmin URL-də olan mövcud səhifəni yeniləyin (əsas məzmunu, başlığı və meta məlumatları).
• Əks halda: saytın mövcud məzmun sistemindən (DB/CMS/MDX) və onun normal URL şablonundan istifadə edərək yeni bloq yazısı yaradın.
• status: "draft" ictimaiyyətə görünməməlidir.
• html etibarlı, artıq formatlanmış məqalə HTML-dir (başlıqlar, siyahılar, cədvəllər, FAQ). Saytın dizaynını və tərtibatını saxlayın.
• tags ən çox 5 teq saxlayır.
• locale: mətnin dili (ISO 639-1, məsələn, az, tr). Çoxdilli saytda yazını həmin dilin öz URL-i (dil prefiksi / marşrutu) altında dərc edin, heç vaxt fərqli dildə dərc etməyin.
• translationOf: yazı tərcümə olduqda, orijinal yazı üçün əvvəllər qaytardığınız id. Onu həmin yazının dil versiyası kimi saxlayın (dil dəyişdiricisi 404 deyil, onu açmalıdır) və versiyaları hər birində <link rel="alternate" hreflang> ilə əlaqələndirin. Orijinal həmişə birinci göndərilir; sahibi yenidən dərc etdikdə, hər versiya öz externalId-si ilə yenidən göndərilir.
• featuredImageUrl: yazının şəkilinin mütləq URL-i, hər dil versiyası üçün eynidir. Yaradıldıqda və hər yenilənmədə, saxlanılandan fərqlənirsə, onu endirin və yazının şəkilini əvəz edin (URL-in fayl genişlənməsi olmaya bilər; cavabın məzmun növündən istifadə edin).
• Bloq yazıları üçün html sonunda <script type="application/ld+json"> kimi yazının strukturlaşdırılmış məlumatlarını (məsələn, BlogPosting və FAQPage) daşıya bilər. Onu silməyin; səhifədə olduğu kimi dərc edin.

Cavab: {"id":"<sabit id>","url":"<mütləq ictimai URL>","status":"draft"|"publish"}. SEOAsist id-ni saxlayır və eyni elementi yenidən göndərdikdə onu externalId kimi geri göndərir. Əgər externalId-si olmayan bloq yazısı eyni saytda daha əvvəl eyni slug və dillə dərc edilmiş yazı ilə uyğun gəlirsə, SEOAsist həmin yazının id-sindən istifadə edir, beləliklə saytda ikinci nüsxə açılmır.

#PUT /files (imkan: files)

Gövdə: {"path":"llms.txt"|"robots-ai.txt","content":string}

• llms.txt: onu /llms.txt ünvanında text/plain kimi təqdim edin (əvvəlkində əvəzləyərək).
• robots-ai.txt: Süni İntellekt axtarış botlarının qaydaları bloku. /robots.txt-i saytın öz qaydaları və əlavə edilmiş bu blokla birlikdə təqdim edin (əvvəlki bloku əvəz edərək).

Cavab: {"ok":true,"url":"<ictimai url>"}.

#Hazır nümunələr

Tərtibatçı təlimatı dialoqunda kopyalayıb yapışdırmaq üçün kod var:

Nümunələrdəki /content sonluğu bir qaralamadır (TODO); yazını öz bloqunuzda/CMS-də saxlamalı və onun real URL-ini qaytarmalısınız.

Sınaq əmri:

TOKEN="<SEOASIST_SITE_TOKEN>"
TS=$(date +%s)
SIG=$(printf "%s." "$TS" | openssl dgst -sha256 -hmac "$TOKEN" | sed 's/^.* //')
curl -s "https://example.com/api/seoasist/manifest" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-SEOAsist-Timestamp: $TS" \
  -H "X-SEOAsist-Signature: sha256=$SIG"

#Paneldə gösterilən xəta mesajları

Saytınız gövdədə {"error":"…"} qaytarırsa, panel həmin mesajı olduğu kimi göstərir. Düzəlişlər üçün Sayt API bağlantısı problemləri səhifəsinə baxın.