Avaldamine API kaudu mis tahes veebisaidil.

/ Ülevaade

Kuidas see toimib

Kui Orova lõpetab märksõna jaoks artikli kirjutamise, saadab see ühe HTTP POST päringu teie registreeritud lõpp-punkti URL-ile. Päringu keha on JSON ja sisaldab kogu artiklit. Teie lõpp-punkt loob postituse teie poolel ja vastab artikli lõpliku avaliku URL-iga. Orova salvestab selle URL-i avaldatud lingina, täpselt nagu WordPressi postituse puhul. Kasutage seda, kui soovite käsitsi sekkumiseta avaldamist saidil, mis ei ole WordPress, või kui eelistate postituste salvestamist täielikult ise kontrollida.

/ Seadistamine

Seadistamine — kuus sammu

• 1

  Lülitage oma projektis sisse „Ühenda API kaudu”. Avage oma projekt (Projektid → teie projekt → Ühendused). WordPressi kaardi kõrval on kaart Ühenda API kaudu. Sisestage sinna oma lõpp-punkti URL. Salajase võtme väli on valikuline: jätke see tühjaks ja Orova loob võtme, või kleepige võti, mida teie sait juba kasutab. Pärast salvestamist kuvatakse võti kaardil koos nupuga Kopeeri. Projekt avaldab ainult ühte sihtkohta — API kaudu ühendamine lukustab WordPressi nupu ja vastupidi.

• 2

  Ehitage POST-i vastuvõttev lõpp-punkt. Looge oma saidil või serveris marsruut, mis kuulab HTTP POST-i JSON-kehaga. See on URL, mille kleebite tagasi projekti ühenduste ekraanile. Orova kutsub seda üks kord iga valminud artikli kohta.

• 3

  Kontrollige Bearer-tokenit igal päringul. Iga Orova päring sisaldab Authorization päist kujul „Bearer <secret>”, kasutades täpselt teie projektis kuvatud salajast võtit. Võrrelge seda salvestatud koopiaga ja lükake tagasi kõik, mis ei klapi — see takistab teistel teie saidile postitamast.

• 4

  Looge artikkel andmetest. Lugege JSON-keha ja looge postitus oma CMS-is või andmebaasis: kasutage artikli enda jaoks title, slug ja content_html, metakirjeldusena excerpt, kaanepildina featured_image_url ning metaandmetena keyword / lang / published_at.

• 5

  Tagastage artikli avalik URL. Vastake HTTP 200 või 201 ja JSON-kehaga { "url": "https://yoursite.com/the-new-article" }. Orova salvestab selle URL-i artikli avaldatud lingina. Kui tagastate mitte-2xx oleku või jätate url-välja ära, loeb Orova avaldamise ebaõnnestunuks.

• 6

  Käsitlege Optimize-mootori uuenduspäringuid. Kui keha sisaldab action = "update", leidke olemasolev postitus target_url-i (või slug-i) järgi ja kirjutage selle title, content_html ja excerpt kohapeal üle — URL jääb muutmata. Vastake 200 ja { "url": ... }, mis viitab samale postitusele. Lõpp-punktid, mis seda veel ei käsitle, panevad Orova lihtsalt optimeerimise ebaõnnestunuks märkima; uute artiklite avaldamine töötab edasi nagu varem.

/ Leping

Päring, mille Orova saadab

Iga valminud artikkel saabub ühe sellise päringuna:

POST <your endpoint URL>

Headers:
  Content-Type: application/json
  Authorization: Bearer <secret>     # the secret key shown in Project -> Connections
  User-Agent: Orova-SEO

Body (JSON):
  {
    "title": "...",                  # article headline
    "slug": "...",                   # URL-friendly identifier
    "content_html": "...",           # full article HTML
    "excerpt": "...",                # meta description
    "featured_image_url": "..." | null,
    "keyword": "...",                # target keyword
    "lang": "en",                    # ISO language code
    "published_at": "2026-05-17T09:00:00.482913",  # ISO 8601, UTC, no offset suffix
    "status": "draft"                # optional: "draft" keeps it unpublished
  }
  # Optional fields are left out of the body when empty — never sent as null.

/ Viide

Andmeväljad

Avaldamise (uue artikli) päringu väljad. Kustutamis- ja uuenduspäringud kasutavad sama lõpp-punkti väiksemate kehadega, mis on näidatud allpool nende endi jaotistes.

Valikulised väljad jäetakse kehast täielikult välja, kui pole midagi saata — Orova ei saada kunagi null-i, seega lugege neid ettevaatlikult. Ka status on valikuline: "draft" loob artikli mustandina, "publish" või status-e puudumine avaldab selle kohe.

/ Leping

Vastus, mille peate tagastama

Kui olete postituse loonud, vastake HTTP 200 või 201 olekuga ja selle JSON-kehaga:

HTTP 200 (or 201)
Content-Type: application/json

{
  "url": "https://yoursite.com/published-article"
}

Orova salvestab selle url-i artikli avaldatud lingina. Kui teie lõpp-punkt tagastab mis tahes mitte-2xx oleku või keha, mis ei ole url-väljaga JSON-objekt, loeb Orova avaldamise ebaõnnestunuks ja märgib artikli vastavalt, et saaksite uuesti proovida. Vastake 60 sekundi jooksul — pärast seda katkestab Orova päringu (see kehtib nii avaldamise, uuendamise kui kustutamise kohta).

/ Näide

Koodinäide

Minimaalne vastuvõttev lõpp-punkt Node.js-is ja Expressis. Samad sammud — kontrollige tokenit, hargnege action järgi (update / delete), looge või muutke postitust, tagastage URL — kehtivad igas keeles või raamistikus.

// Node.js / Express — a minimal receiving endpoint
import express from "express";

const app = express();
app.use(express.json({ limit: "5mb" }));

// The secret Orova generated for this project.
const OROVA_SECRET = process.env.OROVA_SECRET;

app.post("/orova/publish", async (req, res) => {
  // 1. Verify the Bearer token.
  const auth = req.get("authorization") || "";
  if (auth !== "Bearer " + OROVA_SECRET) {
    return res.status(401).json({ error: "unauthorized" });
  }

  // 2. Required: list your articles (duplicate check, internal links). action = "list".
  if (req.body.action === "list") {
    const posts = await listPosts(req.body.limit || 500); // newest first, 500 max
    // each post: { id, title, slug, link, date, modified, status, author, excerpt? }
    return res.status(200).json({ ok: true, posts });
  }

  // 3. Required: read one article in full (used when optimizing it). action = "get".
  if (req.body.action === "get") {
    const post = await findPost(req.body.id, req.body.target_url, req.body.slug);
    if (!post) return res.status(404).json({ ok: false, err: "not_found" });
    return res.status(200).json({ ok: true, post });
  }

  // 4. Visual Editor: store an image, answer with its absolute URL.
  if (req.body.action === "upload_image") {
    const { filename, mime, data_base64 } = req.body;
    if (!String(mime || "").startsWith("image/")) {
      return res.status(422).json({ error: "image files only" });
    }
    const bytes = Buffer.from(data_base64, "base64");
    if (bytes.length > 15 * 1024 * 1024) {
      return res.status(413).json({ error: "image too large" });
    }
    return res.status(200).json({ ok: true, url: await saveImage(filename, bytes) });
  }

  // 5. Delete requests: body carries action = "delete".
  if (req.body.action === "delete") {
    const removed = await deletePostByUrl(req.body.url, req.body.slug);
    if (!removed) return res.status(404).json({ deleted: true }); // already gone
    return res.status(200).json({ deleted: true });
  }

  // 6. Update requests: action = "update". Optional fields may be absent.
  if (req.body.action === "update") {
    const updated = await updatePost(req.body.id, req.body.target_url, {
      title: req.body.title,
      html: req.body.content_html,
      metaDescription: req.body.excerpt,
      coverImage: req.body.featured_image_url,  // optional
      status: req.body.status,                  // optional: "publish" | "draft"
    });
    if (!updated) return res.status(404).json({ error: "post not found" });
    return res.status(200).json({ url: updated.url });
  }

  // 7. New article: read the payload Orova sent.
  const {
    title, slug, content_html, excerpt,
    featured_image_url, keyword, lang, published_at, status,
  } = req.body;

  // 8. Create the article in your own CMS or database.
  const post = await createPost({
    title,
    slug,
    html: content_html,
    metaDescription: excerpt,
    coverImage: featured_image_url,
    keyword,
    lang,
    publishedAt: published_at,
    draft: status === "draft",   // status is optional; absent means publish now
  });

  // 9. Return 200/201 with the live URL.
  return res.status(201).json({
    url: "https://yoursite.com/" + post.slug,
  });
});

app.listen(3000);

/ Leping — uuendamine

Artiklite uuendamine (Optimize)

Orova Optimize-mootor kirjutab ümber juba avaldatud artikleid — värskendatud faktid, paremad pealkirjad, ühendatud sisu — ja kirjutab seejärel olemasoleva postituse üle kohapeal, URL-i muutmata. Päring läheb samale lõpp-punkti URL-ile POST-ina sama Bearer-tokeniga:

POST <your endpoint URL>

Headers:
  Content-Type: application/json
  Authorization: Bearer <secret>
  User-Agent: Orova-SEO

Body (JSON):
  {
    "action": "update",          # always the literal string "update"
    "id": 123,                   # optional: post id, match on this first
    "target_url": "...",         # public URL of the post to overwrite (match next)
    "title": "...",              # new headline
    "slug": "...",               # slug fallback for matching, may be empty
    "content_html": "...",       # full new article body as HTML
    "excerpt": "...",            # new meta description
    "featured_image_url": "...", # optional: new cover image
    "status": "publish"          # optional: "publish" or "draft"
  }
  # Optional fields are left out of the body when empty — never sent as null.

Leidke postitus target_url-i järgi (varuvariandina slug), asendage selle pealkiri, sisu ja metakirjeldus, jätke URL samaks ning vastake 200 ja { "url": "<same post URL>" }. Mis tahes mitte-2xx olek või ilma url-ita keha paneb Orova selle optimeerimise ebaõnnestunuks märkima (dubleeritud postitust ei looda kunagi). Lõpp-punktid, mis seda veel ei rakenda, jätkavad uute artiklite avaldamist muutmata — uuendamise rakendamine on vajalik alles siis, kui kasutate Optimize-ekraani.

Alates 29. augustist võib uuenduskeha sisaldada ka id (sobitage selle järgi enne target_url-i), featured_image_url uue kaanepildi jaoks ja status, mille väärtus on "publish" või "draft". Kõik kolm on valikulised; tühjana jäetakse need kehast välja, mitte ei saadeta null-ina.

/ Leping — Visual Editor

Artiklite lugemine (kohustuslik)

Orova peab lugema teie saidil juba olevaid artikleid — et vältida korduvaid teemasid, lisada sisemisi linke ja optimeerida vanemaid postitusi. Lisage samale lõpp-punkti URL-ile veel kaks toimingut sama Bearer-tokeniga: list tagastab teie artiklid, get tagastab ühe neist täielikult.

POST <your endpoint URL>     # same endpoint, same Bearer secret

Body (JSON):
  {
    "action": "list",            # always the literal string "list"
    "limit": 500                 # newest article first, 500 maximum
  }

Response — HTTP 200:
  {
    "ok": true,
    "posts": [
      {
        "id": 123,               # your own post id, reused by "get" and "update"
        "title": "...",
        "slug": "...",
        "link": "https://yoursite.com/the-article",
        "date": "2026-08-29",    # published date, YYYY-MM-DD
        "modified": "2026-08-29",
        "status": "publish",     # "publish" or "draft"
        "author": "...",
        "excerpt": "..."         # optional: short summary, 300 characters max
      }
    ]
  }
  # Required: Orova reads this list to avoid duplicate topics,
  # add internal links and analyze the whole site.

POST <your endpoint URL>

Body (JSON):
  {
    "action": "get",             # always the literal string "get"
    "id": 123,                   # match on this first
    "target_url": "...",         # then the public URL
    "slug": "..."                # then the slug
  }

Response — HTTP 200:
  {
    "ok": true,
    "post": {
      "id": 123,
      "title": "...",
      "slug": "...",
      "link": "https://yoursite.com/the-article",
      "content_html": "...",     # full article body as HTML
      "excerpt": "...",
      "featured_image_url": "...",
      "status": "publish"        # "publish" or "draft"
    }
  }

No such post — HTTP 404:
  { "ok": false, "err": "not_found" }

limit on maksimaalselt 500 ja uusim artikkel tuleb esimesena. get puhul saadab Orova koos id, target_url ja slug — sobitage selle järgi, mille ära tunnete, selles järjekorras. Kui midagi ei sobi, vastake 404 ja { "ok": false, "err": "not_found" }. excerpt on list-is valikuline (kuni 300 tähemärki). Kohustuslik: Orova kutsub list, et teada saada, millised artiklid juba olemas on (et vältida dubleerimist, lisada sisemisi linke ja analüüsida kogu saiti), ning kutsub get, et lugeda artiklit selle optimeerimisel. Kui teie sait neile kahele toimingule ei vasta, ei saa uued artiklid sisemisi linke ja vanemaid artikleid ei saa optimeerida.

/ Leping — Visual Editor

Piltide üleslaadimine (Visual Editor)

Kui lohistate pildi Visual Editorisse, saadab Orova selle samale lõpp-punkti URL-ile base64-na JSON-keha sees — ilma multipartita ja ilma teise kaitstava URL-ita.

POST <your endpoint URL>

Body (JSON):
  {
    "action": "upload_image",    # always the literal string "upload_image"
    "filename": "cover.png",     # original file name, extension included
    "mime": "image/png",         # image/* only
    "data_base64": "iVBORw0KGgo..."   # file bytes, base64, 15 MB maximum
  }

Response — HTTP 200 (or 201):
  {
    "ok": true,
    "url": "https://yoursite.com/uploads/cover.png"   # absolute URL
  }

Võtke vastu ainult image/* ja lükake tagasi kõik, mis ületab 15 MB. Salvestage fail ja vastake pildi absoluutse URL-iga: suhteline tee rikub artikli kohe, kui seda mujal kuvatakse. Seda toimingut on vaja ainult Visual Editori jaoks.

/ Leping — kustutamine

Artiklite kustutamine

Kui kasutaja eemaldab Orova's avaldatud artikli (ekraanilt Kirjuta või Aruanded), palub Orova teie saidil see samuti kustutada. Päring läheb samale lõpp-punkti URL-ile POST-ina sama Bearer-tokeniga — erinev on ainult keha:

POST <your endpoint URL>

Headers:
  Content-Type: application/json
  Authorization: Bearer <secret>
  User-Agent: Orova-SEO

Body (JSON):
  {
    "action": "delete",          # always the literal string "delete"
    "url": "...",                # public URL of the article to remove (match on this first)
    "slug": "...",               # slug fallback, may be empty
    "keyword": "..."             # the article's target keyword, for your logs
  }

Otsige postitus url-i järgi (varuvariandina slug), eemaldage see või tühistage avaldamine ning vastake 200 ja { "deleted": true } — sobib ka lihtne 204. Kui postitust enam pole, vastake 404 ja Orova loeb selle juba kustutatuks. { "deleted": false } tagastamine ütleb Orova'le, et postitust ei eemaldatud. Tavalised avaldamispäringud ei sisalda kunagi action-välja, nii et olemasolevad lõpp-punktid töötavad muutmata — kustutamise rakendamine on valikuline, kuid soovitatav.

/ Turvalisus

Turvamärkused

• Kontrollige alati Bearer-tokenit. Teie lõpp-punkt on avalik URL — igaüks võib seda kutsuda. Authorization päis on ainus, mis tõendab, et päring tuli tõesti Orova'st, seega lükake tagasi iga päring, mille token ei vasta täpselt teie salvestatud saladusele.
• Teenindage lõpp-punkti HTTPS-i kaudu. Saladus liigub päises. HTTPS takistab selle lugemist edastamise ajal.
• Hoidke saladus koodist väljas. Hoidke seda keskkonnamuutujas või saladuste halduris, mitte kunagi kõvakodeerituna failis, mille commit'ite. Kui see kunagi lekib, looge uus jaotises Projekt → Ühendused.
• Käsitlege content_html-i sisuna, mitte usaldusväärse märgistusena. Salvestage ja kuvage seda sama hoolikalt nagu mis tahes artikli sisu oma CMS-is.

/ Kokkuvõte

See ongi kogu leping

Kui lõpp-punkt on töös ja projektis registreeritud, avaldab Orova teie saidile automaatselt — täpselt nagu WordPressi kasutajatele. Iga valminud artikkel jõuab teie serverisse, muutub postituseks ja selle avalik URL liigub tagasi aruannetesse ja analüüsi, et saaksite jälgida selle tulemusi.