உங்கள் கருத்துகளை இணைக்கவும். செயல்முறையை தெளிவாக வைத்திருக்கவும்.

ஒருங்கிணைப்பைத் தொடங்கவும்

1. நிர்வாகி → API & ஒருங்கிணைப்புகளில் உங்கள் பயன்பாட்டை உருவாக்க நிர்வாகியைக் கேட்கவும். ஒவ்வொரு பயன்பாட்டிற்கும் தனி சூழல், உள்ளடக்க நோக்கங்கள், சேனல்கள், மொழிகள், ஆசிரியர்கள், காலாவதி மற்றும் கோரிக்கை ஒதுக்கீடு உள்ளது.
2. உங்கள் சேவையகத்தில் அடையாளச் சான்றைச் சேமிக்கவும். உற்பத்தி ft_live_ அடையாளச் சான்றுகளைப் பயன்படுத்துகிறது; சாண்ட்பாக்ஸ் ft_test_ ஐப் பயன்படுத்துகிறது. ஒவ்வொரு கோரிக்கையுடனும் Authorization: Bearer <credential> ஐ அனுப்பவும்.
3. அனுமதிக்கப்பட்ட ஆசிரியர் மற்றும் தலைப்பு IDகளைப் பெற /capabilities மற்றும் /content/taxonomies ஐ வாசிக்கவும். உங்கள் ஆவணத்தைத் தயாரிக்க OpenAPI இல் உள்ள திட்டத்தைப் பயன்படுத்தவும்.
4. வரைவை உருவாக்கி, மதிப்பாய்வுக்குச் சமர்ப்பித்து வெளியீட்டு நிகழ்வுகளைக் கேட்கவும். உங்கள் தானியங்கு பயனுள்ள உள்ளடக்கத்தைத் தயாரிக்க முடியும், அதே நேரத்தில் ஒரு ஆசிரியர் வெளியீட்டுக்குப் பொறுப்பாக இருக்கிறார்.

அடிப்படை URL: https://www.formtruth.com/integrations/v1

உள்ளடக்கம் & வெளியீடு

ஒவ்வொரு வெளிப்புற வரைவையும் வெளியிடுவதற்கு முன், அதன் தற்போதைய உள்ளடக்கத்திற்கு பணியாளர் ஒப்புதல் தேவை. மனிதர் உருவாக்கிய முறை அல்லது தானியங்கி வெளியீட்டு அமைப்பு குறிப்பிடப்பட்டிருப்பது ஆசிரியர் ஒப்புதலை வழங்காது.

இடுகைகள், வாங்குபவர் வழிகாட்டிகள் மற்றும் கேள்வி பதில்கள் ஒரே ஆவண வடிவம் மற்றும் பதிப்பு வரலாற்றைப் பகிர்ந்துகொள்கின்றன. தொடர்புடைய அனுமதியுடன் /content/posts, /content/guides அல்லது /content/faqs ஐப் பயன்படுத்தவும். பயன்பாடுகள் அவை சொந்தமான உள்ளடக்கத்தை மட்டுமே அணுக முடியும்; தனிப்பட்ட வரைவை வாசிப்பது வெளியிடப்பட்ட இணையதளத்தை வாசிப்பதிலிருந்து வேறுபட்டது.

ஆவணங்கள் மூல மொழி, உண்மையான ஆசிரியர், தலைப்புகள், ஆதாரங்கள் மற்றும் உள்ளூர்மயமாக்கப்பட்ட தலைப்புகள், ஸ்லக்குகள், சுருக்கங்கள் மற்றும் கட்டமைக்கப்பட்ட உள்ளடக்கத் தொகுதிகளைக் கொண்டுள்ளன. AI-உதவி அல்லது தானியங்கு கட்டுரைகள் அவற்றின் வாசகர் இலக்கு மற்றும் அசல் பங்களிப்பை அடையாளம் காண வேண்டும். மொழிபெயர்ப்புத் திருத்தங்கள் தயாரிப்பு உண்மைகள், எண்கள், பட IDகள், இணைப்புகள் அல்லது கட்டமைப்பு பரிமாணங்களை மாற்ற முடியாது.

ஒவ்வொரு எழுதும் செயலுக்கும் Idempotency-Key தேவை. புதுப்பித்தல், மதிப்பாய்வு, வெளியீடு மற்றும் திரும்பப் பெறுதல் ஆகியவற்றுக்கும் மேற்கோள் குறிகளுடன் கூடிய ETag-உடன் If-Match தேவை. மதிப்பாய்வு செய்யப்பட்ட உள்ளடக்கத்தைத் திருத்துவது, அதனுடன் தொடர்புடைய ஒப்புதலை செல்லாததாக்கும். மூலத்தை மாற்றினால், தொடர்புடைய மொழிபெயர்ப்புகள் மீண்டும் ஒத்திசைக்கப்பட்டு மதிப்பாய்வு செய்யப்படும் வரை காலாவதியானதாகக் குறிக்கப்படும்.

பதிவேற்றப்பட்ட படங்கள் ஒரு ஆசிரியர் உரிமைகள் மற்றும் தரத்தைச் சரிபார்க்கும் வரை அங்கீகரிக்கப்படாமல் இருக்கும். வெளியிடப்பட்ட வெளியீடுகள் மாறாத தருணப்பதிவுகள். வாபஸ் பெறுதல் பொது உள்ளடக்கம், ஊட்டங்கள் மற்றும் தேடல் கண்டுபிடிப்பிலிருந்து வெளியீட்டை நீக்குகிறது.

API குறிப்பு

கீழே உள்ள பாதைகள் அடிப்படை URL ஐ ஒப்பிடுகின்றன. உள்ளடக்கக் குடும்பத்தை மாற்றுவதன் மூலம் அதே கட்டுரை வழிகள் வழிகாட்டிகள் மற்றும் கேள்வி பதில்களுக்குப் பொருந்தும். முழு கோரிக்கைத் திட்டங்கள், தேவையான நோக்கங்கள் மற்றும் பதில்களுக்கு OpenAPI ஐப் பதிவிறக்கவும்.

பட்டியல், ஆர்டர்கள் மற்றும் சரக்கு பிற்கால API தொகுதிகளுக்காக ஒதுக்கப்பட்டுள்ளன. அவை இந்த v1 நுழைவாயில் வழியாக இன்னும் கிடைக்கவில்லை.

பிழைகள் & மறுமுயற்சிகள்

சுருக்கப்படாத UTF-8 JSON-ஐ அனுப்பவும். சாதாரண எழுதும் செயல்களுக்கு கோரிக்கை உடல் வரம்பு 2 MiB, இறக்குமதிகளுக்கு 8 MiB, குறியாக்கப்பட்ட படப் பதிவேற்றங்களுக்கு 18 MiB ஆகும்; உடல் பத்து வினாடிகளுக்குள் வந்து சேர வேண்டும். 413 என்பது உடல் அளவு மிகப் பெரியது, 415 என்பது ஆதரிக்கப்படாத வடிவம், 408 என்பது பதிவேற்றம் காலக்கெடுவை மீறியது என்பதைக் குறிக்கும்.

பிழைகள் error.code, error.message, பொருந்தினால் புலத் தகவல்கள், retryable மற்றும் request_id ஐத் திருப்பித் தருகின்றன. ஆதரவுக்காக X-Request-Id ஐ வைத்திருக்கவும். 401 என்பது அடையாளச் சான்று பிரச்சினையைக் குறிக்கிறது; 403 என்பது அனுமதியைக் குறிக்கிறது; 412 என்பது மாற்றப்பட்ட பதிப்பைக் குறிக்கிறது; 422 என்பது தவறான அல்லது தயாராக இல்லாத உள்ளடக்கத்தைக் குறிக்கிறது; 428 என்பது காணாமல் போன முன்நிபந்தனையைக் குறிக்கிறது.

429 க்கு, Retry-After ஐ மதிக்கவும். தற்காலிக 503 அல்லது பிணைய இடைநிறுத்தத்திற்கு, வரம்புள்ள பேக்ஆஃப் மற்றும் அதே விசை மற்றும் உள்ளீட்டுடன் மறுமுயற்சி செய்யவும். வேறுபட்ட பேலோடுக்கு புதிய விசை தேவை. 409 இல், கண்மூடித்தனமாக மீண்டும் செய்வதற்குப் பதிலாக முந்தைய செயல்பாட்டை சமரசம் செய்யவும். இறக்குமதிகள் /jobs/{id} வழியாக உருப்படி முடிவுகளைத் திருப்பித் தருகின்றன.

கையொப்பமிடப்பட்ட வெப்ஹூக்குகள்

போர்ட் 443 இல் பொது HTTPS பெறுநரைப் பயன்படுத்தவும். நிகழ்வுகள் content.review_required, content.published, content.withdrawn, content.publication_failed மற்றும் import.completed ஐ உள்ளடக்கியுள்ளன. பாகுபடுத்துவதற்கு முன் மூல கோரிக்கை உள்ளடக்கத்தைச் சரிபார்க்கவும்.

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

X-Formtruth-Timestamp, X-Formtruth-Event-Id மற்றும் X-Formtruth-Signature ஐ வாசிக்கவும். ஐந்து நிமிடங்களுக்கு வெளியே உள்ள நேர முத்திரைகளை நிராகரிக்கவும். கையொப்ப தலைப்பு 24-மணிநேர விசைச் சுழற்சி சாளரத்தின் போது காற்புள்ளியால் பிரிக்கப்பட்ட பல v1= மதிப்புகளைக் கொண்டிருக்கலாம்; உங்கள் தக்கவைக்கப்பட்ட விசைக்கான எந்தவொரு செல்லுபடியாகும் கையொப்பத்தையும் ஏற்கவும்.

நகல் நீக்கத்திற்காக நிகழ்வு IDஐ அணு முறையில் சேமிக்கவும், வேலையை வரிசைப்படுத்தவும் மற்றும் 2xx ஐ உடனடியாகத் திருப்பித் தரவும். வழங்கல் மறுமுயற்சி செய்யப்படலாம், எனவே நகல் நிகழ்வு இருமுறை வெளியிடவோ அல்லது கட்டணம் வசூலிக்கவோ கூடாது. கையொப்ப இரகசியத்தை API அடையாளச் சான்றிலிருந்து தனியாக வைக்கவும்.

குறியீடு எடுத்துக்காட்டுகள்

KnowledgeDocument திட்டத்தையும் உண்மையான அனுமதிக்கப்பட்ட வகைபாடு IDகளையும் பயன்படுத்தி document.json ஐத் தயாரிக்கவும். உங்கள் சேவையகத்தில் FORMTRUTH_API_TOKEN ஐ பாதுகாப்பாக அமைக்கவும். இந்த எடுத்துக்காட்டுகள் வரைவை உருவாக்குகின்றன; வெளியீட்டுக்கு இன்னும் மதிப்பாய்வு பணிப்பாய்வு தேவை.

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.