API de RapidTranslate

Introducción

La API de RapidTranslate permite a tu aplicación enviar documentos para su traducción c certificada , consultar el estado y los precios actualizados, y recibir los archivos finalizados, sin que tu equipo tenga que pasar por nuestro proceso de pago. Está diseñada para empresas que realizan pedidos de traducción en nombre de sus propios clientes.

Todas las solicitudes deben dirigirse a https://www.rapidtranslate.org/api/v1 a través de HTTPS. Las solicitudes y respuestas están en formato JSON, salvo en el caso de la creación de pedidos, en la que se suben archivos como multipart/form-data. Todos los importes se devuelven como céntimos enteros en dólares estadounidenses, y todas las marcas de tiempo están en formato UTC ISO-8601.

Colección Postman

¿Prefieres explorar la API antes de escribir código? Nuestra colección de Postman tiene todos los puntos finales preconfigurados, incluyendo la autenticación, los cuerpos de ejemplo y los parámetros de consulta.

Descargar la colección de Postman

1. En Postman, selecciona «Archivo» → «Importar» y elige el archivo descargado.
2. Abre la colección Variables y establecer apiKey a una clave de Configuración de la empresa → Claves API.
3. (Opcional) Establecer baseUrl para tu entorno; el valor predeterminado es «production».
4. Envía cualquier solicitud. Utiliza una clave de entorno de prueba para realizar pruebas sin realizar pedidos facturables.

Autenticación

Autentifica cada solicitud con tu clave secreta de API como token «bearer» y solicita una respuesta en formato JSON. Ambos encabezados son obligatorios:

Autorización: Bearer TU_CLAVE_API
Accept: application/json

Genera y renueva las claves en tu panel de control, en la sección «Configuración empresarial» → «Claves de API». Las claves se muestran una sola vez al crearlas y se almacenan en forma de hash; si pierdes una clave, renuévala. Cada clave pertenece a un modo (Live o Sandbox) y tiene un conjunto fijo de ámbitos.

Ámbitos de aplicación

Cada punto final requiere una capacidad específica en la clave. Si a la clave le falta el ámbito requerido, devuelve 403 acceso prohibido_ámbito.

Modo de prueba y entorno de pruebas

El modo de prueba es una propiedad de la clave, no de tu cuenta. Una clave de Sandbox se ejecuta en un entorno totalmente simulado; una clave de producción realiza pedidos reales y facturables. Puedes utilizar ambas al mismo tiempo.

Los pedidos de entorno de prueba utilizan la misma validación, la misma asignación de campos y los mismos precios reales, pero omiten el almacenamiento de archivos, el OCR y la gestión de pedidos. Al crearse, un pedido de entorno de prueba recorre automáticamente su ciclo de vida (en tramitación → finalizado), activando los mismos webhooks que un pedido real y, por último, entregando un documento de muestra estático.

Cada respuesta y cada webhook lleva un modo en directo Marca esta opción para que tu integración pueda crear una rama sin comprobar la clave:

• livemode: true — pedido real y facturable
• livemode: false — entorno de pruebas / pedido de prueba

Límites de frecuencia

Las solicitudes están sujetas a un límite de frecuencia por organización. El límite predeterminado es 120 solicitudes por minuto. Si se supera, devuelve 429 rate_limited; vuelve a intentarlo tras una breve pausa. Si tu integración necesita un límite más alto, ponte en contacto con support@rapidtranslate.org.

Respuestas

Cada respuesta correcta envuelve su contenido en un datos clave. Los puntos finales de la lista añaden un meta bloque con paginación.

Recurso único

{
  "data": {
    "id": "9b1c...-uuid",
    "reference": "APO-10432",
    "status": "processing",
    "total": 11270,
    "currency": "USD"
  }
}

Lista paginada

{
  "data": [ ... ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 134,
    "last_page": 6
  }
}

Errores

Los errores utilizan códigos de estado HTTP estándar y devuelven un formato estable y legible por máquina código_de_error junto con un mensaje de origen humano. Los errores de validación añaden un campo con clave errores objeto.

{
  "message": "The given data was invalid.",
  "error_code": "validation_failed",
  "errors": {
    "source_language": ["The selected source language is invalid."]
  }
}

Estados de los pedidos

El número de un pedido estado sigue un ciclo de vida estable. Estos cinco valores son también los que acepta la estado filtrar por Lista de pedidos:

Mientras un pedido está en curso, se pueden utilizar etiquetas más detalladas (por ejemplo, Asignado al traductor, Traducir, Enviado) también pueden aparecer. Cuando se requiera una autorización, una orden puede indicar brevemente pago_fallido o credit_hold Si no se ha podido cobrar un importe, resuelve la cuestión del método de pago y vuelve a dar tu aprobación.

Valores de los campos

Los conjuntos fijos que se aceptan al crear un pedido.

Tipos de traducción

Recuperación

Formas de envío

Webhooks

En lugar de realizar consultas periódicas, configura un punto final de webhook para recibir eventos en tiempo real. Establece tu URL y consulta tu clave secreta de firma en «Configuración empresarial» → «Webhooks». Los webhooks son muy prácticos: la información sobre un pedido que se obtiene a través de ellos es siempre fiable.

Eventos

Sobre

Todos los envíos vienen en el mismo sobre: un evento bloque (incluido modo en directo) y un específico para cada evento datos bloque.

{
  "event": {
    "type": "order_status",
    "id": "evt_9b1c...",
    "livemode": true,
    "sent_at": "2026-08-28T10:20:00+00:00"
  },
  "data": {
    "order": {
      "id": "9b1c2d3e-...-uuid",
      "reference": "APO-10432",
      "status": "completed"
    }
  }
}

En entrega_de_documentos El evento añade un documentos matriz (cada una con nombre, download_url, versión, estado) y un portal enlace. El opinión_del_cliente El evento añade un desglose precios bloque y un actions.approve objeto con la URL a la que hay que acceder.

Verificación de firmas

Cada solicitud está firmada para que puedas confirmar que procede de RapidTranslate. Enviamos tres encabezados:

Calcula la firma esperada como un HMAC-SHA256 de la cadena "{timestamp}.{raw_request_body}" utilizando tu secreto de firma del webhook y, a continuación, compáralo con el valor del encabezado:

// PHP
$expected = 'sha256=' . hash_hmac(
    'sha256',
    $timestamp . '.' . $rawBody,
    $webhookSecret
);
$valid = hash_equals($expected, $signatureHeader);

Node.js (Express): configura la ruta con un analizador de cuerpo sin formato para que se conserven los bytes exactos:

// app.use('/webhooks/rapidtranslate', express.raw({ type: 'application/json' }))
const crypto = require('crypto');

const timestamp = req.get('X-RapidTranslate-Timestamp');
const received  = req.get('X-RapidTranslate-Signature'); // "sha256=..."
const rawBody   = req.body;                               // Buffer, untouched

const expected = 'sha256=' + crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`)
  .digest('hex');

const valid = received &&
  crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

Hay tres cosas que suelen causar problemas:

• En X-RapidTranslate-Signature El encabezado incluye un sha256= prefijo. Se puede comparar con 'sha256=' + yourHmac (como se ha indicado anteriormente) o elimina el prefijo antes de comparar; no compares el valor hexadecimal sin prefijo con el encabezado completo.
• Realiza un hash del cuerpo de la solicitud sin procesar tal y como se ha recibido. Al volver a serializar el JSON analizado, se modifican los espacios en blanco y el orden de las claves, por lo que la firma no coincidirá; lee el cuerpo antes de que cualquier middleware de JSON lo analice.
• Comparar en tiempo constante (hash_equals / crypto.timingSafeEqual), nunca con == o ===.

En {marca de tiempo} forma parte de la cadena firmada, así que léela del encabezado y añádela al principio antes de aplicar el hash. Además, te permite rechazar entregas caducadas o repetidas; por ejemplo, cualquier marca de tiempo anterior a cinco minutos.

Las entregas fallidas se vuelven a intentar con un retardo exponencial (hasta 5 intentos). Responde con un 2xx estado para acusar recibo.