Dokumentacja API

Wprowadzenie

API tłumaczeniowe tłumaczy tekst, HTML i strukturalny JSON na maksymalnie 24 urzędowe języki UE. Zapytania i odpowiedzi są w formacie JSON (UTF-8). Każde zapytanie wybiera poziom jakości: basic (AI), pro (AI z wymuszaniem terminologii) lub review (dodatkowo natywna kontrola próbek, asynchronicznie).

Do testowania użyj publicznego klucza sandbox z panelu klienta – zachowuje się jak produkcyjny, ale jest ograniczony do limitów testowych. Klucze produkcyjne otrzymujesz po krótkiej aktywacji na swoim koncie klienta.

Publiczny klucz sandboxabd_test_sandbox_2026

Uwierzytelnianie

Każde zapytanie zawiera Twój klucz API w nagłówku Authorization jako token Bearer. Klucze zaczynają się od bd_test_ (sandbox) lub bd_live_ (produkcja). Traktuj klucze jak hasła: nigdy w kodzie frontendowym, nigdy w repozytorium – w przypadku podejrzenia kompromitacji odwołaj i wygeneruj nowy w panelu klienta.

Zapytania bez ważnego klucza API odpowiadają statusem 401. Klucz może być w dowolnym momencie wyposażony w miesięczny limit słów; po jego osiągnięciu API odpowiada statusem 402, dopóki nie zwiększysz limitu.

Authorization: Bearer bd_live_ihr_schluessel

Tłumaczenie tekstu

POST/api/v1/translate

Główny punkt końcowy tłumaczy jeden lub więcej tekstów na język docelowy. Pole format kontroluje sposób przetwarzania: text (domyślnie), html (znaczniki pozostają nietknięte) lub json (tłumaczone są tylko wartości łańcuchowe, klucze i struktura pozostają niezmienione).

Odpowiedź zawiera tłumaczenia w kolejności wprowadzenia, policzone słowa źródłowe i obliczone koszty w centach. Opcjonalny nagłówek Idempotency-Key zapobiega podwójnemu przetwarzaniu przy powtórzeniach sieciowych: identyczne klucze zwracają zapisaną pierwszą odpowiedź.

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"
}

Parametr

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 webhooki

POST/api/v1/batches

W przypadku dużych ilości lub etapu recenzji pracuj asynchronicznie: punkt końcowy Batch przyjmuje do 1 000 tekstów i natychmiast odpowiada identyfikatorem zadania. Gdy zadanie zostanie zakończone – w przypadku recenzji po próbce w języku ojczystym – API wywołuje zapisany przez Państwa adres URL webhooka z wynikiem.

Wywołania webhooka są podpisane nagłówkiem HMAC-SHA-256, który Państwo weryfikują przy użyciu swojego sekretu webhooka. Jeśli serwer nie odpowie statusem 2xx, dostarczanie jest powtarzane do pięciu razy z rosnącymi odstępami; zadania pozostają dostępne do pobrania przez GET przez dodatkowe 30 dni.

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

Glosariusze

POST/api/v1/glossaries

Glosariusze zabezpieczają terminologię: każdy wpis to termin źródłowy i jego obowiązkowe tłumaczenie na każdy język docelowy. Przesyłane jako CSV w panelu klienta lub przez API; poziom 'pro' i 'review' wymuszają dopasowania, 'basic' traktuje je jako zalecenie.

Na konto możliwe jest do 20 glosariuszy, każdy z 5.000 wpisów. Zmiany obowiązują natychmiast dla wszystkich kolejnych zapytań – wersjonuj glosariusze jak kod i testuj zmiany najpierw za pomocą klucza sandbox.

Języki

GET/api/v1/languages

Endpoint języków dostarcza aktualnie dostępne języki docelowe i źródłowe z kodem ISO oraz nazwą własną. Używaj go zamiast sztywno zakodowanej listy – nowe języki pojawiają się tam automatycznie.

Zużycie

GET/api/v1/usage

Punkt końcowy zużycia pokazuje dla każdego klucza przetłumaczone słowa i poniesione koszty bieżącego miesiąca, a także ustawiony limit miesięczny. Te same liczby widzisz graficznie w panelu klienta w sekcji „API i zużycie”.

Kody błędów

Błędy są zwracane jako JSON z polami error (kod odczytywalny maszynowo) i message (opis). Obsłuż przynajmniej następujące przypadki:

Limity i uczciwe korzystanie

Domyślnie obowiązuje 60 zapytań na minutę na klucz oraz 30 000 znaków na zapytanie; klucz sandbox jest dodatkowo ograniczony do konta testowego. Wyższe limity odblokowujemy po krótkiej weryfikacji – zgłoś się ze swoim przypadkiem użycia.

Liczenie słów: Liczone są słowa tekstu źródłowego (zgodnie z regułami podziału na słowa Unicode), osobno dla każdego języka docelowego. W przypadku formatów HTML i JSON uwzględniane są tylko tłumaczalne węzły tekstowe i wartości łańcuchowe – znaczniki, klucze i zmienne nie są liczone.

Ochrona danych

Przetwarzanie wyłącznie w celu świadczenia usług na serwerach w UE; treści nie są wykorzystywane do trenowania modeli i są usuwane z dzienników przetwarzania po 30 dniach. W przypadku korzystania z produkcji zawieramy umowę powierzenia przetwarzania danych zgodnie z art. 28 RODO – szczegóły w Centrum Zaufania.

Nie przesyłaj rzeczywistych danych osobowych przez sandbox. Pseudonimizuj treści testowe lub korzystaj z syntetycznych przykładów.

Dziennik zmian

Lipiec 2026

Uruchomienie publicznej piaskownicy: punkty końcowe tłumaczeń, wsadowe, glosariuszy, języków i zużycia.

Planowane

Samodzielne zarządzanie kluczami produkcyjnymi, profile stylów na markę, pamięć tłumaczeń (Translation Memory) na konto.

API jest wersjonowane pod /v1; rozszerzenia zgodne wstecznie (nowe opcjonalne pola, nowe języki) są wprowadzane bez zmiany wersji. Zmiany przełomowe pojawiają się jako nowa wersja z co najmniej dwunastomiesięcznym okresem współistnienia.