Documentație API

Introducere

API-ul de traducere traduce text, HTML și JSON structurat în până la 24 de limbi oficiale ale UE. Solicitările și răspunsurile sunt în format JSON (UTF-8). Fiecare cerere selectează un nivel de calitate: basic (AI), pro (AI cu aplicare terminologică) sau review (verificare suplimentară prin eșantionare de către vorbitori nativi, asincron).

Pentru testare, utilizați cheia publică de sandbox din zona de administrare – se comportă ca producția, dar este limitată la un contingent de test. Cheile de producție sunt disponibile după o scurtă activare prin contul dumneavoastră.

Cheie publică Sandboxbd_test_sandbox_2026

Autentificare

Fiecare cerere include cheia API în antetul Authorization ca token Bearer. Cheile încep cu bd_test_ (sandbox) sau bd_live_ (producție). Tratați cheile ca pe parole: niciodată în codul frontend, niciodată în depozit – în caz de suspiciune de compromitere, revocați și generați una nouă din zona de administrare.

Cererile fără cheie validă primesc răspuns cu status 401. O cheie poate fi asociată cu o limită lunară de cuvinte; la atingerea limitei, API-ul răspunde cu status 402 până când măriți limita.

Authorization: Bearer bd_live_ihr_schluessel

Traducere text

POST/api/v1/translate

Endpoint-ul principal traduce unul sau mai multe texte într-o limbă țintă. Câmpul format controlează tratarea: text (implicit), html (marcajul rămâne intact) sau json (doar valorile șir sunt traduse, cheile și structura rămân neschimbate).

Răspunsul conține traducerile în ordinea intrării, cuvintele sursă numărate și costul calculat în cenți. Cu antetul opțional Idempotency-Key, preveniți procesarea dublă la reluări de rețea: chei identice returnează primul răspuns stocat.

curl https://www.baduno.com/api/v1/translate \
  -H "Authorization: Bearer bd_test_sandbox_2026" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "fr",
    "texts": ["Kostenloser Versand ab 50 Euro."],
    "format": "text",
    "tier": "basic"
  }'

{
  "ok": true,
  "target": "fr",
  "tier": "basic",
  "translations": ["Livraison gratuite à partir de 50 euros."],
  "words": 6,
  "cost_cents": 12,
  "detected_source": "de"
}

Parametru

const res = await fetch("https://www.baduno.com/api/v1/translate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.BADUNO_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ target: "it", texts: [title, description], format: "html" })
});
const { translations } = await res.json();

import os, requests

r = requests.post(
    "https://www.baduno.com/api/v1/translate",
    headers={"Authorization": f"Bearer {os.environ['BADUNO_API_KEY']}"},
    json={"target": "pl", "texts": ["Zurück zur Startseite"], "tier": "pro"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["translations"][0])

$ch = curl_init("https://www.baduno.com/api/v1/translate");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("BADUNO_API_KEY"),
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode(["target" => "es", "texts" => [$text]])
]);
$out = json_decode(curl_exec($ch), true);

Batch și Webhook-uri

POST/api/v1/batches

Pentru volume mari sau etapa de revizuire, lucrați asincron: Endpoint-ul Batch acceptă până la 1.000 de texte și răspunde imediat cu un Job-ID. Odată ce jobul este finalizat – în cazul revizuirii după eșantionul nativ – API-ul apelează URL-ul Webhook-ului configurat cu rezultatul.

Apelurile Webhook sunt semnate cu un antet HMAC-SHA-256, pe care îl verificați cu secretul Webhook-ului dumneavoastră. Dacă serverul dumneavoastră nu răspunde cu un status 2xx, livrarea este repetată de până la cinci ori cu intervale crescânde; joburile rămân accesibile suplimentar timp de 30 de zile prin GET.

POST /api/v1/batches            → { "ok": true, "job": "job_8f2…", "status": "processing" }
GET  /api/v1/batches/job_8f2…   → { "ok": true, "status": "done", "results": [ … ] }

Glosare

POST/api/v1/glossaries

Glosarele vă asigură terminologia: fiecare intrare conține un termen sursă și traducerea sa obligatorie pentru fiecare limbă țintă. Se încarcă în format CSV în zona client sau prin API; nivelul pro și review aplică obligatoriu rezultatele, iar basic le folosește ca recomandare.

Pe cont sunt posibile până la 20 de glosare cu câte 5.000 de intrări fiecare. Modificările au efect imediat asupra tuturor cererilor ulterioare – de aceea, versionați glosarele ca pe cod și testați modificările mai întâi cu cheia sandbox.

Limbi

GET/api/v1/languages

Endpointul pentru limbi furnizează limbile țintă și sursă disponibile în prezent, cu cod ISO și denumirea lor nativă. Folosiți-l în locul unei liste fixe – limbile noi apar automat acolo.

Consum

GET/api/v1/usage

Endpointul de consum afișează, pe cheie, cuvintele traduse și costurile acumulate ale lunii curente, precum și limita lunară stabilită. Aceleași cifre le vedeți grafic în zona clientului, la „API & Consum”.

Coduri de eroare

Erorile vin ca JSON cu câmpurile error (cod citibil de mașină) și message (descriere). Tratați cel puțin următoarele cazuri:

Limite și echitate

În mod implicit, se aplică 60 de cereri pe minut și cheie și 30.000 de caractere per cerere; cheia sandbox este suplimentar limitată la cota de test. Deblocăm limite mai mari după o scurtă verificare – contactați-ne cu cazul dvs. de utilizare.

Numărarea cuvintelor: se numără cuvintele textului sursă (delimitare Unicode), o dată pe limbă țintă. Pentru formatele html și json, se numără doar nodurile de text traductibile, respectiv valorile șir – markup, chei și variabile nu costă nimic.

Protecția datelor

Prelucrarea exclusiv pentru prestarea serviciilor pe servere din UE; conținutul nu este utilizat pentru antrenarea modelelor și este șters din jurnalele de procesare după 30 de zile. Pentru utilizarea în producție, încheiem un contract de prelucrare a datelor conform Art. 28 GDPR – detalii în Trust Center.

Nu trimiteți date reale cu caracter personal prin Sandbox. Pseudonimizați conținutul de test sau folosiți exemple sintetice.

Jurnal de modificări

Iulie 2026

Lansarea sandbox-ului public: punct final pentru traducere, lot, glosar, limbi și consum.

Planificat

Autogestionare chei de producție, profiluri de stil per marcă, memorie de traducere (Translation Memory) per cont.

API este versionată sub /v1; extensiile compatibile cu versiunile anterioare (câmpuri opționale noi, limbi noi) au loc fără schimbarea versiunii. Modificările majore apar ca o versiune nouă, cu cel puțin douăsprezece luni de funcționare paralelă.