Documentação da API

Introdução

A Translation API traduz texto, HTML e JSON estruturado em até 24 idiomas oficiais da UE. Solicitações e respostas são em JSON (UTF-8). Cada solicitação escolhe um nível de qualidade: básico (IA), profissional (IA com imposição de terminologia) ou revisão (adicionalmente, verificação por amostragem de falantes nativos, assíncrono).

Para testar, utilize a chave pública de sandbox da área do cliente – ela se comporta como a produção, mas é limitada a uma cota de teste. As chaves de produção são obtidas após uma breve ativação através da sua conta de cliente.

Chave pública de sandboxbd_test_sandbox_2026

Autenticação

Cada solicitação inclui sua chave de API no cabeçalho de autorização como token Bearer. As chaves começam com bd_test_ (sandbox) ou bd_live_ (produção). Trate as chaves como senhas: nunca no código front-end, nunca no repositório – em caso de suspeita de comprometimento, revogue e gere uma nova na área do cliente.

Solicitações sem chave válida são respondidas pela API com status 401. Uma chave pode ser configurada a qualquer momento com um limite mensal de palavras; ao atingi-lo, a API responde com status 402 até que você aumente o limite.

Authorization: Bearer bd_live_ihr_schluessel

Traduzir texto

POST/api/v1/translate

O endpoint central traduz um ou mais textos para um idioma de destino. O campo format controla o tratamento: text (padrão), html (marcação permanece intacta) ou json (apenas valores de string são traduzidos, chaves e estrutura permanecem inalteradas).

A resposta contém as traduções na ordem de entrada, as palavras de origem contadas e os custos calculados em centavos. Com o cabeçalho opcional Idempotency-Key, você evita o processamento duplicado em repetições de rede: chaves idênticas fornecem a primeira resposta armazenada.

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

Parâmetro

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

Lote e Webhooks

POST/api/v1/batches

Para grandes volumes ou a etapa de revisão, trabalhe de forma assíncrona: o endpoint de lote aceita até 1.000 textos e responde imediatamente com um ID de job. Assim que o job estiver concluído – na revisão após a amostragem em idioma nativo – a API chama a sua URL de webhook configurada com o resultado.

As chamadas de webhook são assinadas com um cabeçalho HMAC-SHA-256, que você verifica com seu segredo de webhook. Se o seu servidor não responder com status 2xx, a entrega será repetida até cinco vezes com intervalos crescentes; os jobs permanecem acessíveis por GET por mais 30 dias.

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

Glossários

POST/api/v1/glossaries

Glossários garantem sua terminologia: cada entrada contém um termo fonte e sua tradução obrigatória por idioma alvo. O upload é feito como CSV na área do cliente ou via API; os níveis pro e review aplicam as correspondências de forma obrigatória, enquanto basic as usa como recomendação.

Por conta, são possíveis até 20 glossários com 5.000 entradas cada. As alterações entram em vigor imediatamente em todas as solicitações seguintes – portanto, versione os glossários como código e teste as alterações primeiro com a chave de sandbox.

Idiomas

GET/api/v1/languages

O endpoint de idiomas fornece os idiomas de destino e origem atualmente disponíveis com código ISO e nome nativo. Use-o em vez de uma lista fixa – novos idiomas aparecem automaticamente lá.

Consumo

GET/api/v1/usage

O endpoint de consumo exibe, por chave, as palavras traduzidas e os custos incorridos no mês atual, bem como o limite mensal definido. Os mesmos números podem ser vistos graficamente na área do cliente em "API & Consumo".

Códigos de erro

Os erros são retornados como JSON com os campos error (código legível por máquina) e message (descrição). Trate pelo menos os seguintes casos:

Limites & Justiça

Por padrão, aplicam-se 60 requisições por minuto e chave, bem como 30.000 caracteres por requisição; a chave de sandbox é adicionalmente limitada ao contingente de teste. Liberamos limites maiores após uma breve análise – entre em contato conosco com seu caso de uso.

Contagem de palavras: são contadas as palavras do texto de origem (limites de palavras Unicode), uma vez por idioma de destino. Nos formatos HTML e JSON, apenas nós de texto traduzíveis ou valores de string são contados – marcação, chaves e variáveis não têm custo.

Privacidade

Processamento exclusivamente para a prestação de serviços em servidores da UE; os conteúdos não são utilizados para treinamento de modelos e são excluídos dos registros de processamento após 30 dias. Para uso em produção, celebramos um contrato de processamento de dados conforme Art. 28 do GDPR – detalhes no Trust Center.

Não envie dados pessoais reais através da sandbox. Pseudonimize o conteúdo de teste ou use exemplos sintéticos.

Registro de alterações

Julho de 2026

Início da sandbox pública: endpoints de tradução, lote, glossário, idiomas e consumo.

Planejado

Autogestão de chaves de produção, perfis de estilo por marca, memória de tradução (Translation Memory) por conta.

A API é versionada em /v1; extensões compatíveis com versões anteriores (novos campos opcionais, novos idiomas) ocorrem sem alteração de versão. Alterações que quebram compatibilidade aparecem como uma nova versão com pelo menos doze meses de operação paralela.