Propojte své nápady. Udržujte proces přehledný.

Zahájit integraci

1. Požádejte administrátora, aby vytvořil vaši aplikaci v části Administrace → API a integrace. Každá aplikace má samostatné prostředí, rozsahy obsahu, kanály, jazyky, autory, dobu platnosti a kvótu požadavků.
2. Uložte přihlašovací údaj na svém serveru. Produkce používá přihlašovací údaje ft_live_, sandbox používá ft_test_. S každým požadavkem odešlete Authorization: Bearer <credential>.
3. Načtěte /capabilities a /content/taxonomies, abyste získali ID povolených autorů a témat. Dokument připravte podle schématu v OpenAPI.
4. Vytvořte koncept, odešlete jej ke kontrole a sledujte události publikování. Vaše automatizace může připravit užitečný obsah, zatímco za vydání zůstává odpovědný editor.

Základní URL: https://www.formtruth.com/integrations/v1

Obsah a publikování

Každý externí koncept vyžaduje před zveřejněním schválení aktuálního obsahu pracovníkem. Uvedení metody tvorby člověkem nebo nastavení automatického publikování nepředstavuje redakční schválení.

Příspěvky, nákupní průvodci a často kladené dotazy používají jednotný formát dokumentu a historii verzí. Použijte /content/posts, /content/guides nebo /content/faqs s odpovídajícím oprávněním. Aplikace mají přístup pouze k obsahu, který vlastní; čtení soukromého konceptu se liší od čtení publikovaného webu.

Dokumenty obsahují zdrojový jazyk, skutečného autora, témata, zdroje a lokalizované názvy, adresy URL, souhrny a strukturované bloky těla. Články vytvořené s pomocí AI nebo automatizovaně musí uvádět cíl čtenáře a původní přínos. Úpravy překladu nesmějí měnit fakta o produktech, čísla, ID obrázků, odkazy ani strukturální rozměry.

Každý zápis vyžaduje klíč Idempotency-Key. Aktualizace, kontrola, publikování a stažení vyžadují také hlavičku If-Match s ETagem v uvozovkách. Úprava zkontrolovaného obsahu zneplatní příslušné schválení. Změna zdroje způsobí, že příslušné překlady budou zastaralé, dokud nebudou znovu sjednoceny a zkontrolovány.

Nahrané obrázky zůstávají neschválené, dokud editor nezkontroluje práva a kvalitu. Publikovaná vydání jsou neměnné snímky. Stažení odstraní vydání z veřejného obsahu, kanálů a vyhledávání.

Referenční dokumentace API

Níže uvedené cesty jsou relativní vůči základní URL. Stejné trasy článků platí pro průvodce a často kladené dotazy po změně skupiny obsahu. Stáhněte si OpenAPI pro úplná schémata požadavků, požadované rozsahy a odpovědi.

Katalog, objednávky a skladové zásoby jsou vyhrazeny pro pozdější moduly API. Prostřednictvím této brány v1 zatím nejsou dostupné.

Chyby a opakování požadavků

Odešlete nekomprimovaný JSON UTF-8. Limit těla požadavku je 2 MiB pro běžné zápisy, 8 MiB pro importy a 18 MiB pro kódované obrazové soubory; tělo musí dorazit do deseti sekund. Kód 413 znamená, že tělo je příliš velké, 415 označuje nepodporovaný formát a 408 znamená, že vypršel časový limit nahrávání.

Chyby vracejí error.code, error.message, podrobnosti o poli, pokud jsou relevantní, retryable a request_id. Pro účely podpory si ponechte X-Request-Id. A 401 označuje problém s přihlašovacím údajem; 403 označuje oprávnění; 412 označuje změněnou verzi; 422 označuje neplatný nebo nepřipravený obsah; 428 označuje chybějící předběžnou podmínku.

U 429 respektujte Retry-After. Při dočasném 503 nebo přerušení sítě opakujte požadavek s omezeným exponenciálním odstupem a STEJNÝM klíčem a vstupem. Jiný obsah vyžaduje nový klíč. Při 409 slaďte stav s předchozí operací namísto jejího bezhlavého opakování. Importy vracejí výsledky jednotlivých položek prostřednictvím /jobs/{id}.

Podepsané webhooky

Použijte veřejný přijímač HTTPS na portu 443. Události zahrnují content.review_required, content.published, content.withdrawn, content.publication_failed a import.completed. Před analýzou ověřte nezpracované tělo požadavku.

HMAC-SHA256(secret, timestamp + "." + event_id + "." + raw_body)

Načtěte X-Formtruth-Timestamp, X-Formtruth-Event-Id a X-Formtruth-Signature. Odmítněte časová razítka starší než pět minut. Hlavička podpisu může během 24hodinového období změny klíče obsahovat více hodnot v1= oddělených čárkami; přijměte jakýkoli platný podpis pro klíč, který stále uchováváte.

Atomicky uložte ID události pro deduplikaci, zařaďte práci do fronty a neprodleně vraťte 2xx. Doručení lze opakovat, proto duplicitní událost nesmí publikovat ani účtovat dvakrát. Podpisový tajný klíč uchovávejte odděleně od přihlašovacího údaje API.

Příklady kódu

Připravte document.json pomocí schématu KnowledgeDocument a skutečných povolených ID taxonomie. Na serveru bezpečně nastavte FORMTRUTH_API_TOKEN. Tyto příklady vytvoří koncept; publikování stále vyžaduje proces kontroly.

import { readFile } from "node:fs/promises"
import { randomUUID } from "node:crypto"

const base = process.env.FORMTRUTH_URL || "https://www.formtruth.com"
const token = process.env.FORMTRUTH_API_TOKEN
if (!token) throw new Error("Set FORMTRUTH_API_TOKEN in a secure environment")
const document = JSON.parse(await readFile("document.json", "utf8"))
// Persist the key before calling. Reuse it only for an identical retry.
const key = process.env.FORMTRUTH_REQUEST_KEY || randomUUID()
console.log("Request key:", key)
const response = await fetch(base + "/integrations/v1/content/posts", {
  method: "POST",
  headers: { Authorization: "Bearer " + token, "Content-Type": "application/json", "Idempotency-Key": key },
  body: JSON.stringify({ channel: "b2b", external_id: document.locales[document.source_locale].slug, document }),
})
const result = await response.json()
if (!response.ok) throw new Error(JSON.stringify(result.error))
console.log("Draft:", result.entry.id, "ETag:", response.headers.get("etag"))
// Creating a draft does not publish it. Submit for editorial review separately.

import json, os, uuid, urllib.request, urllib.error

base = os.environ.get("FORMTRUTH_URL", "https://www.formtruth.com")
token = os.environ["FORMTRUTH_API_TOKEN"]
with open("document.json", encoding="utf-8") as source:
    document = json.load(source)
# Persist this key before sending; reuse for an identical retry.
key = os.environ.get("FORMTRUTH_REQUEST_KEY", str(uuid.uuid4()))
print("Request key:", key)
payload = {"channel": "b2b", "external_id": document["locales"][document["source_locale"]]["slug"], "document": document}
request = urllib.request.Request(base + "/integrations/v1/content/posts",
    data=json.dumps(payload, ensure_ascii=False).encode("utf-8"), method="POST",
    headers={"Authorization": "Bearer " + token, "Content-Type": "application/json", "Idempotency-Key": key})
try:
    with urllib.request.urlopen(request, timeout=45) as response:
        result = json.load(response)
        print("Draft:", result["entry"]["id"], "ETag:", response.headers.get("ETag"))
except urllib.error.HTTPError as error:
    raise RuntimeError(error.read().decode("utf-8")) from error
# Creating a draft does not publish it. Submit for editorial review separately.

import { createHmac, timingSafeEqual } from "node:crypto"

export function verifyWebhook(rawBody, headers, secret, now = Date.now()) {
  const timestamp = headers.get("x-formtruth-timestamp") || ""
  const eventId = headers.get("x-formtruth-event-id") || ""
  const signatures = (headers.get("x-formtruth-signature") || "").split(",")
  if (!/^[0-9]{10}$/.test(timestamp) || !eventId || Math.abs(now - Number(timestamp) * 1000) > 300000) return false
  const expected = createHmac("sha256", secret).update(timestamp + "." + eventId + ".").update(rawBody).digest()
  return signatures.some(value => {
    const part = value.trim()
    if (!/^v1=[a-f0-9]{64}$/.test(part)) return false
    const actual = Buffer.from(part.slice(3), "hex")
    return actual.length === expected.length && timingSafeEqual(actual, expected)
  })
}
// Verify the raw body BEFORE JSON parsing. Atomically record eventId in durable
// storage to deduplicate retries; enqueue accepted work, then return HTTP 2xx.
// During rotation both v1 signatures are sent for 24 hours.

import hashlib, hmac, re, time

def verify_webhook(raw_body, headers, secret, now=None):
    timestamp = headers.get("x-formtruth-timestamp", "")
    event_id = headers.get("x-formtruth-event-id", "")
    signatures = headers.get("x-formtruth-signature", "").split(",")
    current = time.time() if now is None else now
    if not re.fullmatch(r"[0-9]{10}", timestamp) or not event_id or abs(current - int(timestamp)) > 300:
        return False
    signed = (timestamp + "." + event_id + ".").encode("utf-8") + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()
    return any(re.fullmatch(r"v1=[a-f0-9]{64}", part.strip()) and hmac.compare_digest(part.strip()[3:], expected) for part in signatures)

# Normalize header names to lowercase. Verify raw bytes before parsing JSON.
# Atomically persist event_id for deduplication, enqueue work, then return 2xx.