Document-Translator.com
Menú
ES

API de traducción de documentos

Añade la traducción de documentos a tu aplicación o flujo de trabajo. Envía texto extraído, tradúcelo al idioma que elijas y reconstruye el documento en tu propio cliente. Usa créditos prepagados, sin suscripción.

Inicio rápido

  1. Inicia sesión y crea una clave de API. Guarda la clave en la configuración de secretos de tu servidor. Las traducciones mediante API requieren créditos prepagados; el cupo gratuito del navegador no se aplica.
  2. Extrae el texto del documento en tu cliente, asigna un ID estable a cada segmento y solicita un presupuesto. Conserva el documento original localmente para reconstruirlo.
  3. Empieza con el ID de cotización, una clave de idempotencia estable y la misma carga. Consulta el estado hasta que esté listo, recupera los segmentos traducidos y reconstruye el documento.

La API de traducción acepta texto extraído y devuelve segmentos traducidos. Crea el archivo terminado en tu cliente y, si quieres, guarda ese archivo traducido para descargarlo más adelante. No subas el archivo original.

Crear un presupuesto

POST /api/v1/quotes
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "version": "document-ir/1",
  "format": "txt",
  "fingerprint": "<64-character SHA-256 of the source file>",
  "sourceLanguage": "auto",
  "targetLanguage": "Spanish",
  "segments": [
    {
      "id": "s0",
      "text": "Hello, world."
    }
  ]
}

La respuesta incluye el ID del presupuesto, el recuento de palabras de origen, el coste exacto en créditos y la fecha de caducidad. Los presupuestos son válidos durante diez minutos. Solicitar un presupuesto no reserva créditos ni guarda el texto del documento.

Iniciar la traducción

POST /api/v1/translations
Authorization: Bearer doctr_...
Content-Type: application/json

{
  "quoteId": "<quote id>",
  "idempotencyKey": "<stable key, 16–80 letters, digits, underscores or hyphens>",
  "payload": {
    "version": "document-ir/1",
    "format": "txt",
    "fingerprint": "<the same source fingerprint>",
    "sourceLanguage": "auto",
    "targetLanguage": "Spanish",
    "segments": [
      {
        "id": "s0",
        "text": "Hello, world."
      }
    ]
  }
}

Vuelve a enviar al iniciar la carga original citada. El servidor verifica quién es su propietario y su hash canónico antes de guardar el texto o reservar créditos. El orden de las claves del objeto JSON no importa; si cambias el texto, el orden de los segmentos, el formato, la huella digital o los idiomas, necesitarás una nueva cotización.

Crea un flujo de trabajo para traducir documentos

Extrae el texto y reconstruye las descargas en tu aplicación. Envía el contenido que se muestra arriba y, después, usa los ID de segmento devueltos para insertar cada traducción en su documento.

// Run this on your server. Keep your API key private.
const response = await fetch(
  'https://document-translator.com/api/v1/quotes',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  }
);
if (!response.ok) throw new Error('Quote request failed');
const quote = await response.json();
// Show the price before starting with the same payload.

DOCX conserva las estructuras originales compatibles. La exportación a PDF reajusta el texto y no reproduce exactamente el diseño de las páginas. No se admiten PDF escaneados ni protegidos con contraseña. Revisa las traducciones y el formato importantes antes de usarlos.

Créditos de traducción y claves de API

Cada documento de la API usa un crédito de la cuenta dentro de los límites de carga. Los créditos se reservan al iniciar y se cobran cuando está lista una traducción completa y validada. Los créditos adicionales de registro funcionan mediante la API; la cuota diaria gratuita solo está disponible en el sitio web.

Crea hasta cinco claves de API activas por cuenta. Las claves se muestran una sola vez, se guardan como hashes y se pueden revocar en la sección Cuenta. Una clave activa puede acceder a las traducciones de pago de esa cuenta, incluidos los trabajos creados con otra clave de la misma cuenta. Las claves no autorizan el inicio de sesión ni los pagos.

Reintentos y solicitudes interrumpidas

Si no está seguro de que la solicitud de inicio se haya completado, vuelva a utilizar el mismo ID de cotización, la misma carga útil y la misma clave de idempotencia. Los reintentos idénticos devuelven el trabajo existente sin realizar otro cargo. Si cambia la carga útil o reutiliza una clave para otra cotización, se devuelve 409. Los metadatos del trabajo y de idempotencia se conservan durante siete días tras la finalización.

Un trabajo fallido que se pueda reanudar puede volver a intentarse mientras el texto de origen siga disponible. El reintento conserva el ID del trabajo y reutiliza los fragmentos completados. Cada trabajo permite un máximo de tres intentos de procesamiento. Si falla la descarga, puedes volver a intentar acceder al resultado sin iniciar otra traducción.

Consultas periódicas y descargas

GET /api/v1/translations/JOB_ID
GET /api/v1/translations?ids=JOB_ID_1,JOB_ID_2
GET /api/v1/translations/JOB_ID/result
PUT /api/v1/translations/JOB_ID/files/txt
GET /api/v1/translations/JOB_ID/files/txt
POST /api/v1/translations/JOB_ID/retry
DELETE /api/v1/translations/JOB_ID

La consulta del estado por lotes acepta un máximo de diez ID y devuelve { jobs: [...] }, que contiene solo trabajos autorizados y no eliminados. Consulta aproximadamente cada cinco segundos mientras se procesan y cada quince segundos mientras están en cola. Alterna los lotes de forma equitativa si estás recuperando más de diez trabajos. Pausa las consultas en las pestañas ocultas y detente cuando el trabajo llegue a un estado final o se produzca un error de autorización permanente.

Cuando el estado sea «ready», obtén el resultado con la misma autorización de cuenta. Contiene la correspondencia de segmentos traducidos para reconstruir el documento localmente. Los resultados están disponibles durante 24 horas después de completarse; las entradas no válidas caducan una hora después de su creación. Los resultados caducados devuelven 410. Los trabajos eliminados o inaccesibles devuelven 404.

Guarda un archivo terminado mediante PUT, con su cuerpo binario, Content-Length y el Content-Type correspondiente. Se admiten las extensiones docx, pdf, txt y md, con un archivo guardado por formato y un límite de salida de 50 MB. Si se repite una operación de guardado correcta, se conserva el archivo existente. GET descarga el archivo guardado; savedFormats en el estado del trabajo enumera los formatos disponibles. Guardar y descargar utilizan las mismas comprobaciones de propiedad del trabajo, no cuestan créditos adicionales y nunca amplían el plazo de 24 horas.

DELETE cancela el trabajo sin terminar o elimina el texto disponible y los archivos guardados. Eliminar un resultado completado no lo reembolsa ni amplía su plazo de descarga. Esta versión no incluye webhooks de finalización.

Saldo e historial de la cuenta

GET /api/v1/translations?before=NEXT_CURSOR&limit=5
GET /api/v1/translations?active=1&before=NEXT_CURSOR
GET /api/account/balance

El historial está limitado al propietario actual y utiliza el cursor de paginación devuelto. El endpoint de saldo utiliza la sesión de la cuenta del navegador y devuelve información mínima de inicio de sesión y saldo. Mientras el Checkout esté pendiente, consulte el endpoint cada cinco segundos, hasta diez veces; pause las consultas cuando la página esté oculta y deténgalas cuando se acrediten los créditos o se cierre la sesión de la cuenta.

Límites y errores

Los errores incluyen un mensaje y un código. 400 indica datos no válidos, 401 autorización no válida, 402 créditos insuficientes, 404 trabajo no disponible, 409 presupuesto o estado en conflicto, 410 caducidad, 429 límite de solicitudes o capacidad y 503 servicio no disponible.

Los documentos originales permanecen en tu dispositivo. El texto extraído se procesa mediante nuestro proveedor de traducción y los archivos traducidos guardados se almacenan de forma privada para su descarga. El almacenamiento temporal se limpia periódicamente; también se aplican las políticas de retención del proveedor. Detalles de privacidad