Documentazione API

Introduzione

L'API di traduzione traduce testo, HTML e JSON strutturato in fino a 24 lingue ufficiali dell'UE. Le richieste e le risposte sono in JSON (UTF-8). Ogni richiesta seleziona un livello di qualità: basic (AI), pro (AI con imposizione della terminologia) o review (controllo a campione aggiuntivo da parte di madrelingua, asincrono).

Per provare, utilizzi la chiave sandbox pubblica dall'area clienti – si comporta come la produzione, ma è limitata a un contingente di test. Le chiavi di produzione si ottengono dopo una breve attivazione tramite il Suo account cliente.

Chiave sandbox pubblicabd_test_sandbox_2026

Autenticazione

Ogni richiesta include la Sua chiave API nell'header Authorization come token Bearer. Le chiavi iniziano con bd_test_ (sandbox) o bd_live_ (produzione). Tratti le chiavi come password: mai nel codice frontend, mai nel repository – in caso di sospetta compromissione, revocarle e rigenerarle nell'area clienti.

Le richieste senza chiave valida ricevono risposta con stato 401. Una chiave può essere dotata in qualsiasi momento di un limite mensile in parole; al raggiungimento, l'API risponde con stato 402 fino a quando non si aumenta il limite.

Authorization: Bearer bd_live_ihr_schluessel

Tradurre testo

POST/api/v1/translate

L'endpoint centrale traduce uno o più testi in una lingua di destinazione. Il campo format controlla il trattamento: text (predefinito), html (il markup rimane invariato) o json (vengono tradotti solo i valori stringa, chiavi e struttura rimangono invariati).

La risposta contiene le traduzioni nell'ordine di input, le parole sorgente contate e i costi calcolati in centesimi. Con l'header opzionale Idempotency-Key si evita la doppia elaborazione in caso di ripetizioni di rete: chiavi identiche restituiscono la prima risposta memorizzata.

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

Parametro

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 e Webhook

POST/api/v1/batches

Per grandi volumi o per la fase di revisione, si lavora in modo asincrono: l'endpoint batch accetta fino a 1.000 testi e risponde immediatamente con un ID job. Una volta completato il job – in caso di revisione dopo il campionamento in lingua madre – l'API richiama l'URL del webhook che hai configurato con il risultato.

Le chiamate webhook sono firmate con un header HMAC-SHA-256, che può verificare con il Suo segreto webhook. Se il Suo server non risponde con uno stato 2xx, la consegna viene ripetuta fino a cinque volte con intervalli crescenti; i job rimangono inoltre recuperabili tramite GET per 30 giorni.

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

Glossari

POST/api/v1/glossaries

I glossari garantiscono la vostra terminologia: ogni voce contiene un termine di partenza e la sua traduzione vincolante per lingua di destinazione. Si carica come CSV nell’area clienti o tramite API; i livelli pro e review applicano i risultati in modo vincolante, basic li usa come suggerimento.

Per account sono possibili fino a 20 glossari con 5.000 voci ciascuno. Le modifiche hanno effetto immediato su tutte le richieste successive – pertanto versionate i glossari come codice e testate le modifiche prima con la chiave sandbox.

Lingue

GET/api/v1/languages

L’endpoint lingue fornisce le lingue di destinazione e di origine attualmente disponibili con codice ISO e nome nativo. Utilizzatelo al posto di un elenco predefinito: le nuove lingue vengono visualizzate automaticamente.

Consumo

GET/api/v1/usage

L'endpoint di consumo mostra per ciascuna chiave le parole tradotte e i costi sostenuti del mese in corso, nonché il limite mensile impostato. Gli stessi numeri sono visualizzati graficamente nell'area clienti sotto "API e consumo".

Codici di errore

Gli errori arrivano come JSON con i campi error (codice leggibile dalla macchina) e message (descrizione). Gestire almeno questi casi:

Limiti & Equità

Per impostazione predefinita, sono previste 60 richieste al minuto per chiave e 30.000 caratteri per richiesta; la chiave sandbox è inoltre limitata al contingente di test. Sblocchiamo limiti superiori dopo una breve verifica – ci contatti con il suo caso d'uso.

Conteggio parole: vengono contate le parole del testo sorgente (limiti di parola Unicode), una volta per lingua di destinazione. Per i formati html e json, vengono conteggiati solo i nodi di testo traducibili o i valori stringa: markup, chiavi e variabili non hanno costo.

Protezione dei dati

Elaborazione esclusivamente per l'erogazione del servizio su server UE; i contenuti non vengono utilizzati per l'addestramento di modelli e vengono cancellati dai registri di elaborazione dopo 30 giorni. Per l'uso in produzione stipuliamo un contratto di elaborazione dei dati ai sensi dell'art. 28 GDPR – dettagli nel Trust Center.

Non invii dati personali reali tramite la sandbox. Pseudonimizzi i contenuti di test o utilizzi esempi sintetici.

Registro delle modifiche

Luglio 2026

Avvio della sandbox pubblica: endpoint per traduzioni, batch, glossario, lingue e consumi.

Previsto

Autogestione delle chiavi di produzione, profili di stile per marchio, memoria di traduzione (Translation Memory) per account.

L'API è versionata sotto /v1; le estensioni retrocompatibili (nuovi campi opzionali, nuove lingue) vengono effettuate senza cambio di versione. Le modifiche sostanziali appaiono come nuova versione con almeno dodici mesi di funzionamento parallelo.