Żviluppatur

Dokumentazzjoni tal-API

Kull ma għandek bżonn għall-integrazzjoni tal-API ta' Traduzzjoni Baduno: awtentikazzjoni, endpoints, eżempji, kodiċijiet ta' żball u limiti. L-URL bażi għal kull sejħa huwa https://www.baduno.com/api/v1 – biss fuq HTTPS.

URL bażihttps://www.baduno.com/api/v1

Introduzzjoni

L-API ta' Traduzzjoni tittraduċi test, HTML u JSON strutturat f'sa 24 lingwi uffiċjali tal-UE. It-talbiet u t-tweġibiet huma JSON (UTF-8). Kull talba tagħżel livell ta' kwalità: basic (IA), pro (IA b'infurzar ta' terminoloġija) jew review (verifika addizzjonali ta' kampjuni minn kelliema nattivi, asinkronu).

Biex tipprova, uża ċ-ċavetta pubblika tal-sandbox miż-żona tal-klijent – timxi bħall-produzzjoni iżda hija limitata għal kwota ta' test. Iċ-ċwievet ta' produzzjoni huma disponibbli wara attivazzjoni qasira permezz tal-kont tiegħek tal-klijent.

Ċavetta tas-Sandbox Pubblikabd_test_sandbox_2026

Awtentikazzjoni

Kull talba ġġorr iċ-ċavetta tal-API tiegħek fl-header Authorization bħala Bearer token. Iċ-ċwievet jibdew b'bd_test_ (sandbox) jew bd_live_ (produzzjoni). Immaniġġja ċ-ċwievet bħal passwords: qatt fil-kodiċi tal-frontend, qatt fir-repository – f'każ ta' suspett ta' kompromess, irrevoka u riġenera fiż-żona tal-klijent.

Talbiet mingħajr ċavetta valida jiġu mwieġba mill-API bi status 401. Ċavetta tista' tiġi limitata b'kull xahar f'kliem; meta tintlaħaq, l-API tirrispondi bi status 402 sakemm iżżid il-limitu.

Header

Authorization: Bearer bd_live_ihr_schluessel

Ittraduċi Test

POST/api/v1/translate

L-endpoint ċentrali jittraduċi test wieħed jew aktar f'lingwa fil-mira. Il-qasam format jikkontrolla t-trattament: text (standard), html (l-istruttura tinżamm) jew json (biss valuri ta' string jiġu tradotti, iċ-ċwievet u l-istruttura jibqgħu mhux mibdula).

It-tweġiba fiha t-traduzzjonijiet fl-ordni tal-input, il-kliem sors magħdud u l-ispejjeż ikkalkulati f'ċenteżmi. Bl-header fakultattiv Idempotency-Key, tevita l-ipproċessar doppju f'ripetizzjonijiet tan-netwerk: ċwievet identiċi jagħtu l-ewwel tweġiba maħżuna.

Talba · curl

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

Tweġiba

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

Parametru

`target`	Lingwa mira (ISO 639-1), eż. fr, it, pl. Kamp obbligatorju.
`texts[]`	Lista tat-testi li għandhom jiġu tradotti (1–50 għal kull talba, total massimu ta' 30,000 karattru).
`source`	Lingwa sors (ISO 639-1). Fakultattiv – mingħajr indikazzjoni tiġi rikonoxxuta.
`format`	test, html jew json. Standard: test.
`tier`	Livell ta' kwalità basic, pro jew review. Standard: basic.
`glossary`	ID ta' glossarju mniżżel, li t-terminoloġija tiegħu tiġi infurzata (livell pro u review).

JavaScript

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();

Python

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])

PHP

$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 u Webhooks

POST/api/v1/batches

Għal kwantitajiet kbar jew l-istadju ta' reviżjoni, aħdem b'mod asinkronu: L-endpoint tal-batch jaċċetta sa 1,000 test u jwieġeb immedjatament b'ID tal-impjieg. Hekk kif l-impjieg jitlesta – fil-każ ta' reviżjoni wara l-kampjun tal-lingwa nattiva – l-API ssejjaħ l-URL tal-webhook li rreġistrajt bir-riżultat.

Is-sejħiet tal-webhook huma ffirmati b'header HMAC-SHA-256, li tista' tivverifika bis-sigriet tal-webhook tiegħek. Jekk is-server tiegħek ma jwieġebx bi status 2xx, il-kunsinna tiġi ripetuta sa ħames darbiet b'intervall li qed jikber; l-impjiegi jibqgħu disponibbli għal 30 jum addizzjonali permezz ta' GET.

Batch-Ablauf

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

Glossarji

POST/api/v1/glossaries

Il-glossarji jiżguraw it-terminoloġija tiegħek: kull entrata terminu sors u t-traduzzjoni vinkolanti tiegħu għal kull lingwa fil-mira. Jitniżżlu bħala CSV fiż-żona tal-klijent jew permezz tal-API; il-livell pro u review jiskattaw ir-riżultati b'mod vinkolanti, basic jużahom bħala rakkomandazzjoni.

Għal kull kont huma possibbli sa 20 glossarju b'5,000 entrata kull wieħed. Il-bidliet jaffettwaw immedjatament it-talbiet kollha sussegwenti – għalhekk, agħmel verżjonijiet tal-glossarji bħall-kodiċi u ittestja l-bidliet l-ewwel biċ-ċavetta sandbox.

Lingwi

GET/api/v1/languages

L-endpoint tal-lingwi jipprovdi l-lingwi fil-mira u s-sors disponibbli bħalissa bil-kodiċi ISO u l-isem nattiv. Użah minflok lista fissa – lingwi ġodda jidhru hemmhekk awtomatikament.

Konsum

GET/api/v1/usage

Il-punt tat-tmiem tal-konsum juri għal kull ċavetta l-kliem tradott u l-ispejjeż imgħarrġa tax-xahar kurrenti, kif ukoll il-limitu mensili stabbilit. L-istess numri tista' tara grafikament fiż-żona tal-klijent taħt “API & Konsum”.

Kodiċi ta' żbalji

L-iżbalji jiġu bħala JSON bl-oqsma error (kodiċi li jinqara mill-magna) u message (deskrizzjoni). Immaniġġja mill-inqas dawn il-każijiet:

401	`invalid_key`	Ċavetta API nieqsa jew invalida.
402	`quota_exceeded`	Limitu ta' kull xahar jew kreditu eżawrit – Żid il-limitu fiż-żona tal-klijent.
413	`payload_too_large`	Talba kbira wisq – Aqsam it-testi (mass. 30,000 karattru kull talba).
422	`unsupported_language`	Lingwa mmirata mhux disponibbli jew parametru invalidu – Dettalji fil-qasam tal-messaġġ.
429	`rate_limited`	Limitu tar-rata milħuq – irrepeti b'intervall esponenzjali; l-header Retry-After jindika l-ħin ta' stennija.
500	`internal`	Żball mhux mistenni fuq in-naħa tagħna – stenna ftit u erġa' pprova; jekk iseħħ ta' spiss, ikkuntattja l-appoġġ.

Limiti & Ġustizzja

B'mod standard, japplikaw 60 talba kull minuta u ċavetta, u 30,000 karattru għal kull talba; iċ-ċavetta sandbox hija wkoll limitata għall-kwota tat-test. Nħallu limiti ogħla wara verifika qasira – ikkuntattjana bil-każ ta' użu tiegħek.

Għadd tal-kliem: Jingħaddu l-kliem tat-test sors (limiti tal-kliem Unicode), darba għal kull lingwa fil-mira. Għall-formati html u json, jingħaddu biss nodi tat-test li jistgħu jiġu tradotti jew valuri string – markup, ċwievet u varjabbli ma jiswew xejn.

Privatezza

Ipproċessar esklussivament għall-forniment tas-servizz fuq servers tal-UE; il-kontenut mhux użat għat-taħriġ ta' mudelli u jitħassar mill-prokolli tal-ipproċessar wara 30 jum. Għall-użu fil-produzzjoni, nikkonkludu ftehim ta' proċessar tad-data skont l-Art. 28 tar-Regolament Ġenerali dwar il-Protezzjoni tad-Data (GDPR) – dettalji fiċ-Ċentru ta' Fiduċja.

Tibgħat l-ebda dejta personali reali permezz tas-sandbox. Agħmel pseudonimizzazzjoni tal-kontenut tat-test jew uża eżempji sintetiċi.

Protokoll tal-Bidliet

Lulju 2026: Bidu tas-sandbox pubbliku: punti finali ta' traduzzjoni, lott, glossarju, lingwi u konsum.
Ippjanat: Amministrazzjoni awtonoma taċ-ċwievet tal-produzzjoni, profili ta' stil għal kull marka, memorja ta' traduzzjoni (Translation Memory) għal kull kont.

L-API hija verżjonata taħt /v1; estensjonijiet kompatibbli b'lura (oqsma fakultattivi ġodda, lingwi ġodda) isiru mingħajr bidla fil-verżjoni. Bidliet li jkissru jidhru bħala verżjoni ġdida b'mill-inqas tnax-il xahar ta' tħaddim parallel.

Itlob offerta mhux vinkolanti

Tweġiba fi żmien 24 siegħa f'jiem tax-xogħol.