ავთენტიფიკაცია#
ყველა /v1 მოთხოვნას (გარდა საჯარო მეთოდებისა, რომლებსაც „ავტორიზაციის გარეშე“ აწერია) Bearer ტოკენი სჭირდება. ტოკენი ორი სახისაა:
| ტოკენი |
როგორ მიიღება |
შესაძლებლობები |
sess_… პანელის სესია |
POST /v1/sessions სამუშაო სივრცის API გასაღებით (მოქმედებს 30 დღე) |
ყველაფერი; მუშაობს ყველა ტარიფზე |
sk_live_… API გასაღები |
ჩანს მხოლოდ ერთხელ, სამუშაო სივრცის შექმნისას |
ყველაფერი, მაგრამ მხოლოდ API წვდომის მქონე ტარიფებზე (optimize, agency, agency_client, enterprise); სხვა ტარიფებზე პასუხია 403 api_access_required |
Authorization: Bearer sk_live_…
მოთხოვნების ლიმიტები ტარიფზეა დამოკიდებული; 429 პასუხს Retry-After სათაური ახლავს. POST მოთხოვნებს შეგიძლიათ
Idempotency-Key სათაური დაურთოთ: იმავე გასაღებით გამეორებულ მოთხოვნაზე სერვერი პირველ პასუხს ხელახლა დააბრუნებს
(Idempotent-Replayed: true).
გაზომვა და ანალიტიკა#
გაზომვის (/v1/runs, /v1/answers, /v1/visibility, /v1/share-of-voice, /v1/citations)
და ანალიტიკის (/v1/overview, /v1/trends, /v1/competitors, /v1/sources,
/v1/prompt-metrics, /v1/report, /v1/report.pdf) მეთოდები ერთსა და იმავე ფილტრებს იღებს: brand_id, engine,
language, from, to (YYYY-MM-DD, ორივე თარიღის ჩათვლით). ანალიტიკა არჩეულ პერიოდს იმავე ხანგრძლივობის
წინა პერიოდს ადარებს (ნაგულისხმევი პერიოდი — ბოლო 28 დღე). კვირა ორშაბათს იწყება.
ცვლილებები: ხელით განთავსება პანელიდან#
ყოველ მომზადებულ ცვლილებას (GET /v1/content/items) ახლავს placement (რომელ URL‑ზე, გვერდის რომელ ადგილას,
დანომრილი ნაბიჯები, გვერდზე არსებული ტექსტი, რომელსაც ცვლილება ჩაანაცვლებს, და თითოეული ნაწილი კოპირებისთვის
მზა სახით) და facts (დადასტურებული ფაქტები, რომლებსაც ცვლილება ეყრდნობა). პროცესი API მიწოდების დამატებითი
სერვისის გარეშე:
proposed → POST /v1/content/{id}/approve → approved (მზადაა განსათავსებლად).
- კლიენტი ცვლილებას საიტზე ჩასვამს და გამოიძახებს
POST /v1/content/{id}/applied → live; იწყება
ექსპერიმენტი (ხელახალი გაზომვა იმ დროის გასვლის შემდეგ, რაც AI სისტემებს ცვლილების შესამჩნევად სჭირდებათ, ბოლოს კი —
დატოვება ან დაბრუნება). ახალი გვერდებისთვის ამის ნაცვლად გამოიყენება POST /v1/pages/{id}/published რეალური URL‑ით.
- თუ ექსპერიმენტი ზრდას არ აჩვენებს (ან კლიენტი ცვლილებას დააბრუნებს), ცვლილება გადადის
remove_requested სტატუსში მოსახსნელი ტექსტით; POST /v1/content/{id}/removed → rolled_back.
Google Business Profile‑ის ცვლილებები ყველა ტარიფზე ავტომატური რჩება: gbp_profile /
gbp_post ცვლილების დამტკიცებისთანავე PromART მას Google‑ში ჩაწერს (ფუნქციის გადამრთველი google_bp).
API მიწოდება (ფასიანი დამატებითი სერვისი)#
API მიწოდების დამატებითი სერვისით (სამუშაო სივრცის ველი api_delivery_enabled; იხ. GET /v1/usage‑ის ველი
add_ons) საიტის ცვლილება დამტკიცებისთანავე live ხდება, თქვენი საიტის სერვერი კი მას გვერდის რენდერინგისას
ითხოვს. დამატებითი სერვისის გარეშე ეს მეთოდები 403 addon_required‑ს აბრუნებს:
ბრუნდება მხოლოდ API‑ით მიწოდებული ცვლილებები (delivery: api); ცვლილებები, რომლებიც კლიენტმა ხელით
განათავსა, გვერდზე უკვე არის. პასუხების ქეშირება შეგიძლიათ 60 წამამდე (Cache-Control: private, max-age=60).
ბლოკების გამოყენება#
თითოეული ბლოკი ასეთი ობიექტია: {block_id, selector, action, html, fact_ids, status}. დარენდერებულ HTML‑ში
იპოვეთ CSS selector‑ის შესაბამისი პირველი ელემენტი და შეასრულეთ action:
| action |
რას აკეთებს |
replace |
ელემენტს (outer HTML) ცვლის html‑ით |
append |
html‑ს სვამს ელემენტის ბოლო შვილობილ ელემენტად |
prepend |
html‑ს სვამს ელემენტის პირველ შვილობილ ელემენტად |
before |
html‑ს სვამს უშუალოდ ელემენტის წინ |
after |
html‑ს სვამს უშუალოდ ელემენტის შემდეგ |
თუ სელექტორს არც ერთი ელემენტი არ შეესაბამება, ბლოკი გამოტოვეთ. html უკვე გასუფთავებულია PromART‑ის
უსაფრთხოების ფილტრით: დაშვებულია მხოლოდ p br h2 h3 h4 ul ol li strong em b i table thead tbody tr th td a
(ბმულები მხოლოდ თქვენს ჰოსტებზე); სკრიპტებს, სტილებსა და ატრიბუტებს (a[href]‑ის გარდა) ის არ შეიცავს.
ხელმოწერის შემოწმება#
GET /v1/content, GET /v1/pages/{url}/blocks, GET /v1/pages/blocks და GET /v1/pages/new
პასუხებს ახლავს სათაური:
X-Sachino-Signature: sha256=<hex HMAC-SHA256(signing_secret, exact response body bytes)>
signing_secret‑ს აბრუნებს GET /v1/me. ხელმოწერა შეამოწმეთ პასუხის ნედლი ბაიტების მიხედვით, JSON‑ის
პარსინგამდე; შედარება მუდმივ დროში (constant-time) უნდა სრულდებოდეს.
Node:
JavaScript
const crypto = require('crypto');
const ok = (raw, header, secret) => {
const want = 'sha256=' + crypto.createHmac('sha256', secret).update(raw).digest('hex');
return header && header.length === want.length &&
crypto.timingSafeEqual(Buffer.from(header), Buffer.from(want));
};
PHP:
PHP
$want = 'sha256=' . hash_hmac('sha256', $rawBody, $secret);
$ok = hash_equals($want, $_SERVER['HTTP_X_SACHINO_SIGNATURE'] ?? $header);
Go:
Go
m := hmac.New(sha256.New, []byte(secret))
m.Write(raw)
ok := hmac.Equal([]byte(header), []byte("sha256="+hex.EncodeToString(m.Sum(nil))))
შეფერხებისას ქცევის წესი (სავალდებულო)#
PromART‑მა თქვენი საიტის მუშაობა არასოდეს უნდა დაარღვიოს. თუ API მოთხოვნა ვერ შესრულდება, ტაიმაუტით შეწყდება
(გირჩევთ 800 მწმ ტაიმაუტს), 2xx‑ისგან განსხვავებულ სტატუსს დააბრუნებს (მათ შორის 403 addon_required) ან
ხელმოწერა არ დაემთხვევა, დაარენდერეთ თავდაპირველი გვერდი უცვლელად. გვერდის რენდერინგი PromART‑ის გამო
არასოდეს უნდა შეფერხდეს.
IndexNow#
GET /v1/indexnow-key აბრუნებს თქვენი სამუშაო სივრცის IndexNow გასაღებს და ფაილს, რომელიც თქვენმა დეველოპერმა
ყველა დომენზე უნდა განათავსოს: https://<domain>/<key>.txt — ტექსტური ფაილი, რომელიც მხოლოდ გასაღებს შეიცავს,
HTTP 200 სტატუსით და გადამისამართების გარეშე. ყოველი content.published მოვლენის შემდეგ (როცა ცვლილება API‑ით
გამოქვეყნდება, ხელით განთავსებულად მოინიშნება ან ახალი გვერდის გამოქვეყნება დადასტურდება) PromART შეცვლილ
URL‑ებს IndexNow‑ს უგზავნის; თითოეული გაგზავნა და მისი შედეგი ჩანს GET /v1/actions‑ში (არხი bing). როგორც კი
ფაილი ხელმისაწვდომი გახდება, indexnow_key შემოწმება ok სტატუსს მიიღებს.
ვებჰუკები#
მოვლენების გამოსაწერად გამოიძახეთ POST /v1/webhooks. მოვლენები: run.completed, visibility.changed,
content.proposed, content.approved, content.published, content.removal_requested,
content.rolled_back, facts.stale, alert.triggered, page.approved, integration.invited,
review.request (ან * ყველა მოვლენისთვის).
თითოეული გაგზავნა POST მოთხოვნაა JSON შიგთავსით {id, type, created_at, data}; მას ახლავს სათაურები
X-Sachino-Event: <type> და X-Sachino-Signature: sha256=<hex HMAC-SHA256(webhook secret, body)>
(საიდუმლო გასაღები ვებჰუკის შექმნისას ბრუნდება). თუ თქვენი სერვერი 2xx‑ისგან განსხვავებულ სტატუსს დააბრუნებს,
PromART გაგზავნას 3‑ჯერ გაიმეორებს.
ინტეგრაციები და ფუნქციების გადამრთველები#
Google Business Profile (google_bp, წვდომის არე business.manage), Search Console (gsc) და GA4
(ga4, analytics.readonly) Google OAuth‑ით უკავშირდება; ტოკენები დაშიფრული სახით ინახება. Cloudflare
(cloudflare) ჩასმული API ტოკენით უკავშირდება (ტოკენის უფლებები მხოლოდ ზონის ბოტების პარამეტრებზე ვრცელდება)
და გამოიყენება მხოლოდ AI ბოტების დასაშვებად. cloudflare და google_bp სერვერის ფუნქციების გადამრთველებით
ირთვება: როცა გადამრთველი გამორთულია, შესაბამისი მეთოდები 403 სტატუსს აბრუნებს feature_disabled კოდით, ხოლო
GET /v1/integrations ამ ტიპს enabled: false მნიშვნელობით აჩვენებს.
შეცდომები#
შეცდომები ერთიანი სტრუქტურით ბრუნდება: {"error": {"code": "...", "message": "..."}}. კოდები: unauthorized
(401), plan_limit (402), api_access_required (403: API გასაღები ისეთ ტარიფზე, რომელიც API წვდომას არ მოიცავს;
პანელი სესიებს იყენებს და ყველა ტარიფზე მუშაობს), addon_required (403: API მიწოდების დამატებითი სერვისი ჩართული
არ არის), feature_disabled (403), not_found (404), invalid_request / invalid_json (400),
rate_limited (429), internal (500). პროგრამულ ლოგიკაში დაეყრდენით code‑ს: ის ზოგადი და სტაბილურია. არარსებულ
/v1 მისამართზე პასუხი ამავე სტრუქტურით მოდის, 404 სტატუსითა და not_found კოდით, ხოლო HTTP მეთოდზე, რომელსაც
/v1 მისამართი არ უჭერს მხარს, — 405 სტატუსით, invalid_request კოდით და Allow სათაურით.
თუ შეცდომას უფრო კონკრეტული მიზეზი აქვს, მას ასევე ახლავს reason — შეტყობინების სტაბილური გასაღები, მაგ.,
http.err.brand_id_required ან core.err.not_found.brand — და params, ამ შეტყობინებაში ჩასმული მნიშვნელობები
(თუ მნიშვნელობები არ არის, ველი გამოტოვებულია). თუ პარამეტრი რაიმეს ასახელებს (ტარიფს, სტატუსს, AI სისტემას),
მისი მნიშვნელობა კოდია, როგორც ინგლისურ შეტყობინებებში. ასეთი შეცდომის message პასუხის ენაზეა
(იხ. „ენა“); ინგლისურად კი ის ზუსტად ის ტექსტია, რაც reason‑ის დამატებამდე იყო.
JSON
{"error": {"code": "api_access_required",
"message": "plan monitor does not include API access; use the panel, or upgrade to Optimize or higher",
"reason": "http.err.api_access_required", "params": {"plan": "monitor"}}}
ენა#
PromART‑ის მიერ დაწერილი ტექსტები (შეცდომების შეტყობინებები, შენიშვნები, რეკომენდაციები, განთავსების ნაბიჯები,
გაფრთხილებები, მოსაწვევი გვერდი) შეიძლება დაბრუნდეს ქართულად, რუსულად ან ინგლისურად. ენა აირჩიეთ lang URL
პარამეტრით (ka, ru ან en, ნებისმიერ მეთოდზე) ან Accept-Language სათაურით (გამოიყენება მხარდაჭერილი ენა
ყველაზე მაღალი q‑მნიშვნელობით; lang მასზე უპირატესია). თუ არც ერთი არ არის მითითებული ან მითითებულია მხოლოდ
მხარდაუჭერელი ენები, პასუხები ინგლისურად ბრუნდება, ზუსტად ისე, როგორც ადრე. ყოველი პასუხის ენა მითითებულია
Content-Language სათაურში (ბრაუზერებს მისი წაკითხვა შეუძლიათ: Access-Control-Expose-Headers) და ყოველ პასუხს
ახლავს Vary: Accept-Language. გამონაკლისია პასუხები, რომლებიც ყველა ენაზე ერთნაირია — GET /v1/content‑ისა და
GET /v1/pages/{url}/blocks‑ის საიტის შიგთავსი, /healthz, შრიფტები და დოკუმენტაციის გვერდის ფაილები:
მათ არც ერთი ეს სათაური არ ახლავს. /docs‑იც
მოთხოვნილ ენაზე იხსნება (ქართულად, რუსულად ან ინგლისურად, Vary: Accept-Language‑ით); /openapi.yaml მხოლოდ
ინგლისურადაა: მას ახლავს Content-Language: en, Vary‑ის გარეშე. Idempotency-Key‑ით გამეორებული POST მოთხოვნის
პასუხი პირველი მოთხოვნის ენაზე ბრუნდება, იმავე Content-Language‑ით. კოდები, ID‑ები და თქვენი მონაცემები
(ბრენდების სახელები, ფაქტები, პრომპტები, AI სისტემების პასუხები, საიტისთვის მომზადებული შიგთავსი) არასოდეს
ითარგმნება.