API do RapidTranslate

Introdução

A API do RapidTranslate permite que seu aplicativo envie documentos para tradução certificada, consulte o status e os preços atualizados e receba os arquivos finalizados — sem que sua equipe precise acessar nosso sistema de checkout. Ela foi projetada para empresas que fazem pedidos de tradução em nome de seus próprios clientes.

Todas as solicitações devem ser encaminhadas para https://www.rapidtranslate.org/api/v1 por HTTPS. As solicitações e respostas são em JSON, exceto na criação de pedidos, que faz o upload de arquivos como multipart/form-data. Todos os valores são devolvidos como centavos inteiros em dólares americanos, e todos os carimbos de data/hora estão no formato UTC ISO-8601.

Coleção Postman

Prefere explorar a API antes de escrever qualquer código? Nossa coleção no Postman tem todos os endpoints pré-configurados — incluindo autenticação, corpos de exemplo e parâmetros de consulta.

Baixar coleção do Postman

1. No Postman, selecione Arquivo → Importar e escolha o arquivo baixado.
2. Abra a coleção Variáveis e definir apiKey para uma chave de Configurações da empresa → Chaves de API.
3. (Opcional) Definir baseUrl para o seu ambiente — o padrão é “produção”.
4. Envie qualquer solicitação. Use uma chave de Sandbox para testar sem fazer pedidos que gerem cobrança.

Autenticação

Autentifique cada solicitação com sua chave secreta da API como um token de portador e solicite uma resposta em JSON. Ambos os cabeçalhos são obrigatórios:

Autorização: Portador YOUR_API_KEY
Aceitar: application/json

Gere e alterne chaves em seu painel, na seção Configurações de negócios → Chaves de API. As chaves são exibidas uma única vez no momento da criação e armazenadas na forma de hash — caso perca uma chave, alterne-a. Cada chave pertence a um modo (Live ou Sandbox) e possui um conjunto fixo de escopos.

Âmbitos

Cada endpoint exige uma habilidade específica na chave. Uma chave sem o escopo exigido retorna 403 acesso restrito_escopo.

Modo de teste e sandbox

O modo de teste é uma propriedade da chave, não da sua conta. Uma chave de Sandbox opera em um ambiente totalmente simulado; uma chave Live realiza pedidos reais e faturáveis. Você pode usar as duas ao mesmo tempo.

Os pedidos em ambiente de teste utilizam a mesma validação, o mesmo mapeamento de campos e os preços reais, mas não incluem armazenamento de arquivos, OCR e atendimento do pedido. Ao ser criado, um pedido em ambiente de teste percorre automaticamente seu ciclo de vida (em processamento → concluído), acionando os mesmos webhooks que um pedido ativo e, por fim, entregando um documento de amostra estático.

Cada resposta e cada webhook contém um modo ao vivo marque essa opção para que sua integração possa criar ramificações sem verificar a chave:

• livemode: true — pedido real e faturável
• livemode: false — ambiente de teste / pedido de teste

Limites de taxa

As solicitações estão sujeitas a um limite de taxa por organização. A cota padrão é 120 solicitações por minuto. Se for ultrapassado, retorna 429 rate_limited; tente novamente após um breve intervalo. Se sua integração precisar de um limite maior, entre em contato com support@rapidtranslate.org.

Respostas

Cada resposta bem-sucedida envolve sua carga útil em um dados chave. Os pontos finais da lista adicionam um meta bloco com paginação.

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

Erros

Os erros utilizam códigos de status HTTP padrão e retornam um formato estável e legível por máquina código_de_erro juntamente com uma mensagem de texto. Os erros de validação adicionam um campo com chave erros objeto.

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

Status dos pedidos

O número do pedido status segue um ciclo de vida estável. Esses cinco valores são também os mesmos aceitos pela status filtrar por Lista de pedidos:

Enquanto um pedido estiver em andamento, rótulos mais detalhados (por exemplo, Atribuído ao tradutor, Tradução, Enviado) também podem aparecer. Quando for necessária uma aprovação, um pedido pode indicar brevemente pagamento_falhou ou suspensão de crédito caso uma cobrança não tenha sido realizada — definir a forma de pagamento e aprovar novamente.

Valores dos campos

Os conjuntos fixos aceitos ao criar um pedido.

Tipos de tradução

Recuperação

Formas de entrega

Webhooks

Em vez de fazer consultas periódicas, configure um endpoint de webhook para receber eventos assim que eles ocorrerem. Defina sua URL e visualize seu segredo de assinatura em Configurações da empresa → Webhooks. Os webhooks são práticos — a recuperação de um pedido é sempre confiável.

Eventos

Envelope

Todas as entregas vêm no mesmo envelope: um evento bloco (incluindo modo ao vivo) e um específico para o evento dados bloco.

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

O entrega_de_documentos O evento adiciona um documentos matriz (cada uma com nome, download_url, versão, status) e um portal link. O avaliação_do_cliente O evento adiciona um item detalhado preços bloco e um actions.approve objeto com a URL a ser chamada.

Verificação de assinaturas

Cada solicitação é assinada para que você possa confirmar que ela veio do RapidTranslate. Enviamos três cabeçalhos:

Calcule a assinatura esperada como um HMAC-SHA256 da sequência de caracteres "{timestamp}.{raw_request_body}" usando seu segredo de assinatura do webhook e, em seguida, compare-o com o valor do cabeçalho:

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

Node.js (Express) — configure a rota com um analisador de corpo bruto para que os bytes exatos sejam preservados:

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

Três coisas que costumam causar dificuldades às pessoas:

• O X-RapidTranslate-Signature o cabeçalho contém um sha256= prefixo. Compare com 'sha256=' + yourHmac (como acima) ou remova o prefixo antes de comparar — não compare o valor hexadecimal sozinho com o cabeçalho completo.
• Faça o hash do corpo da solicitação bruta exatamente como foi recebido. A resserialização do JSON analisado altera os espaços em branco e a ordem das chaves, de modo que a assinatura não corresponderá — leia o corpo antes que qualquer middleware JSON o analise.
• Comparar em tempo constante (hash_equals / crypto.timingSafeEqual), nunca com == ou ===.

O {timestamp} faz parte da string assinada; portanto, leia-a do cabeçalho e insira-a no início antes de aplicar o hash. Isso também permite rejeitar entregas desatualizadas ou repetidas — por exemplo, qualquer data e hora com mais de cinco minutos.

As entregas com falha são repetidas com recuo exponencial (até 5 tentativas). Responda com um 2xx status para confirmar o recebimento.