Documentación de API

Introducción

La API de traducción traduce texto, HTML y JSON estructurado a hasta 24 idiomas oficiales de la UE. Las solicitudes y respuestas son JSON (UTF-8). Cada solicitud elige un nivel de calidad: básico (IA), profesional (IA con imposición de terminología) o revisión (adicionalmente, verificación por muestreo de hablantes nativos, asíncrono).

Para probar, use la clave pública de sandbox del área de clientes: se comporta como producción, pero está limitada a una cuota de prueba. Las claves de producción se obtienen después de una breve activación a través de su cuenta de cliente.

Clave pública de sandboxbd_test_sandbox_2026

Autenticación

Cada solicitud lleva su clave API en el encabezado Authorization como token Bearer. Las claves comienzan con bd_test_ (sandbox) o bd_live_ (producción). Trate las claves como contraseñas: nunca en código frontend, nunca en el repositorio; ante sospecha de compromiso, revóquelas y genere nuevas en el área de clientes.

Las solicitudes sin clave válida reciben el estado 401. Una clave puede tener un límite mensual en palabras; al alcanzarlo, la API responde con estado 402 hasta que aumente el límite.

Authorization: Bearer bd_live_ihr_schluessel

Traducir texto

POST/api/v1/translate

El endpoint central traduce uno o varios textos a un idioma de destino. El campo format controla el tratamiento: text (predeterminado), html (el marcado se conserva) o json (solo se traducen los valores de cadena, las claves y la estructura permanecen sin cambios).

La respuesta contiene las traducciones en el orden de entrada, las palabras de origen contadas y los costos calculados en céntimos. Con el encabezado opcional Idempotency-Key evita el procesamiento doble en reintentos de red: claves idénticas devuelven la primera respuesta almacenada.

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

Batch y Webhooks

POST/api/v1/batches

Para grandes volúmenes o la fase de revisión, trabaje de forma asíncrona: el endpoint de batch acepta hasta 1.000 textos y responde inmediatamente con un ID de trabajo. Una vez que el trabajo esté completo – en el caso de revisión después de la muestra en lengua materna – la API llama a su URL de webhook registrada con el resultado.

Las llamadas de webhook están firmadas con un encabezado HMAC-SHA-256, que usted verifica con su secreto de webhook. Si su servidor no responde con un estado 2xx, la entrega se repetirá hasta cinco veces con intervalos crecientes; los trabajos además permanecen disponibles durante 30 días mediante GET.

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

Glosarios

POST/api/v1/glossaries

Los glosarios aseguran su terminología: por cada entrada, un término origen y su traducción vinculante por idioma de destino. Se carga como CSV en el área de cliente o mediante API; el nivel pro y review aplican las coincidencias de forma vinculante, basic las usa como recomendación.

Por cuenta, son posibles hasta 20 glosarios con 5.000 entradas cada uno. Los cambios afectan inmediatamente a todas las solicitudes siguientes – por lo tanto, versionen los glosarios como código y prueben los cambios primero con la clave de sandbox.

Idiomas

GET/api/v1/languages

El endpoint de idiomas proporciona los idiomas de destino y origen actualmente disponibles con código ISO y autodenominación. Úselo en lugar de una lista hardcodeada – los nuevos idiomas aparecen allí automáticamente.

Consumo

GET/api/v1/usage

El endpoint de consumo muestra, por clave, las palabras traducidas y los costos incurridos del mes actual, así como el límite mensual establecido. Las mismas cifras las puede ver gráficamente en el área de clientes bajo «API y consumo».

Códigos de error

Los errores se presentan como JSON con los campos error (código legible por máquina) y message (descripción). Como mínimo, maneje estos casos:

Límites y uso justo

De forma predeterminada, se aplican 60 solicitudes por minuto y clave, así como 30.000 caracteres por solicitud; la clave de sandbox está adicionalmente limitada al cupo de prueba. Desbloqueamos límites superiores tras una breve revisión – contáctenos con su caso de uso.

Conteo de palabras: Se cuentan las palabras del texto fuente (límites de palabras Unicode), una vez por idioma de destino. En los formatos html y json, solo cuentan los nodos de texto traducibles o valores de cadena; el marcado, las claves y las variables no tienen costo.

Protección de datos

Procesamiento exclusivamente para la prestación del servicio en servidores de la UE; los contenidos no se utilizan para entrenar modelos y se eliminan de los registros de procesamiento después de 30 días. Para el uso en producción, celebramos un contrato de procesamiento de datos según el Art. 28 del RGPD; más detalles en el Centro de confianza.

No envíe datos personales reales a través del entorno de pruebas. Seudonimice los contenidos de prueba o utilice ejemplos sintéticos.

Registro de cambios

Julio de 2026

Inicio del sandbox público: endpoints de traducción, lotes, glosario, idiomas y consumo.

Planificado

Autogestión de claves de producción, perfiles de estilo por marca, memoria de traducción (Translation Memory) por cuenta.

La API tiene versionado bajo /v1; las extensiones compatibles hacia atrás (nuevos campos opcionales, nuevos idiomas) se realizan sin cambio de versión. Los cambios que rompen la compatibilidad aparecen como una nueva versión con al menos doce meses de operación paralela.