Document-Translator.com
Menu
PT

API de tradução de documentos

Adicione a tradução de documentos ao seu app ou fluxo de trabalho. Envie o texto extraído, traduza para o idioma escolhido e reconstrua o documento no seu próprio cliente. Use créditos pré-pagos, sem assinatura.

Início rápido

  1. Inicie sessão e crie uma chave de API. Guarde a chave na configuração secreta do seu servidor. As traduções pela API exigem créditos pré-pagos; a franquia gratuita do navegador não se aplica.
  2. Extraia o texto do documento no seu cliente, atribua um ID estável a cada segmento e solicite uma cotação. Mantenha o documento original localmente para reconstruí-lo.
  3. Comece com o ID da cotação, uma chave de idempotência estável e o mesmo payload. Consulte o estado até estar pronto, obtenha os segmentos traduzidos e reconstrua o documento.

A API de tradução aceita texto extraído e retorna segmentos traduzidos. Monte o arquivo concluído no seu dispositivo e, se quiser, salve esse arquivo traduzido para download posterior. Não envie o arquivo original.

Criar um orçamento

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

A resposta inclui o ID do orçamento, a contagem de palavras de origem, o custo exato em créditos e a validade. Os orçamentos duram dez minutos. Solicitar um orçamento não reserva créditos nem salva o texto do documento.

Iniciar a tradução

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

Envie novamente o payload original citado no início. O servidor verifica o respetivo proprietário e o hash canónico antes de armazenar texto ou reservar créditos. A ordem das chaves do objeto JSON não importa; alterar o texto, a ordem dos segmentos, o formato, a impressão digital ou os idiomas requer uma nova cotação.

Crie um fluxo de trabalho para tradução de documentos

Extraia o texto e recrie os downloads no seu aplicativo. Envie o payload exibido acima e use os IDs de segmento retornados para inserir cada tradução de volta no documento correspondente.

// 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.

O DOCX preserva as estruturas originais compatíveis. A exportação em PDF reorganiza o texto e não reproduz exatamente o layout das páginas. PDFs digitalizados ou protegidos por senha não são compatíveis. Revise as traduções e a formatação importantes antes de usar.

Créditos de tradução e chaves de API

Cada documento enviado pela API usa um crédito da conta, dentro dos limites de envio. Os créditos são reservados no início e cobrados quando uma tradução completa e validada fica pronta. Os créditos bônus de cadastro funcionam pela API; a franquia gratuita diária está disponível somente no site.

Crie até cinco chaves de API ativas por conta. As chaves são exibidas uma única vez, armazenadas como hashes e podem ser revogadas em Conta. Uma chave ativa pode acessar as traduções pagas dessa conta, inclusive trabalhos criados com outra chave da mesma conta. As chaves não autorizam o início de sessão nem pagamentos.

Novas tentativas e solicitações interrompidas

Após uma solicitação de início cujo resultado seja incerto, reutilize o mesmo ID de orçamento, payload e chave de idempotência. Tentativas idênticas retornam o trabalho existente sem uma nova cobrança. Um payload alterado ou uma chave reutilizada para outro orçamento retorna 409. Os metadados do trabalho e da chave de idempotência são mantidos por sete dias após o encerramento.

Um trabalho com falha que possa ser retomado pode ser tentado novamente enquanto o texto de origem estiver disponível. A nova tentativa mantém o ID do trabalho e reutiliza os trechos concluídos. Os trabalhos permitem até três tentativas de processamento. Falhas no download podem ser tentadas novamente no endpoint do resultado, sem iniciar outra tradução.

Consultas periódicas e downloads

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

A consulta de status em lote aceita até dez IDs e retorna { jobs: [...] }, contendo apenas trabalhos autorizados e não excluídos. Consulte a cada cinco segundos, aproximadamente, durante o processamento e a cada quinze segundos enquanto estiver na fila. Alterne os lotes de forma equilibrada ao recuperar mais de dez trabalhos. Pause as consultas em abas ocultas e pare quando o trabalho chegar a um estado final ou ocorrer um erro permanente de autorização.

Quando o estado for ready, obtenha o resultado usando a mesma autorização da conta. Ele contém o mapeamento dos segmentos traduzidos para reconstrução local. Os resultados ficam acessíveis por 24 horas após a conclusão; entradas sem sucesso expiram uma hora após a criação. Resultados expirados retornam 410. Trabalhos excluídos ou inacessíveis retornam 404.

Salve um arquivo concluído usando PUT com o corpo binário, Content-Length e Content-Type correspondente. As extensões compatíveis são docx, pdf, txt e md, com um arquivo salvo por formato e um limite de saída de 50 MB. Repetir um salvamento bem-sucedido mantém o arquivo existente. GET baixa o arquivo salvo; savedFormats no status do trabalho lista os formatos disponíveis. O salvamento e o download usam as mesmas verificações de titularidade do trabalho, não consomem créditos adicionais e nunca prolongam o prazo de 24 horas.

DELETE cancela trabalhos não concluídos ou remove textos disponíveis e arquivos salvos. Excluir um resultado concluído não gera reembolso nem prolonga o prazo para download. Esta versão não oferece webhooks de conclusão.

Saldo e histórico da conta

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

O histórico é limitado ao proprietário atual e usa o cursor de paginação retornado. O endpoint de saldo usa a sessão da conta no navegador e retorna informações mínimas de login e saldo. Enquanto o Checkout estiver pendente, consulte-o a cada cinco segundos, por no máximo dez tentativas; pause quando a página estiver oculta e pare quando os créditos forem adicionados ou a conta encerrar a sessão.

Limites e erros

Os erros incluem uma mensagem e um código. 400 indica entrada inválida; 401, autorização inválida; 402, créditos insuficientes; 404, trabalho indisponível; 409, cotação ou estado conflitante; 410, expiração; 429, limite de taxa ou capacidade; e 503, serviço indisponível.

Os documentos originais permanecem no seu dispositivo. O texto extraído é processado pelo nosso provedor de tradução, e os arquivos traduzidos salvos são armazenados em modo privado para download. O armazenamento temporário é limpo periodicamente; também se aplicam as políticas de retenção do provedor. Detalhes de privacidade