Pular para o conteúdo

Integre fluxos de trabalho de documentos ao seu aplicativo

Desde o carregamento de um arquivo até a sua tradução, verificação do progresso e download do resultado. Cada etapa é explicada na ordem em que você integra, com pontos de entrada para gerenciamento de arquivos, processamento de documentos e serviços de áudio e vídeo.

Base URL https://omnidoc.top/api/v1 · HTTPS · JSON · Autenticação por chave API · as traduções de arquivos são executadas como trabalhos assíncronos

Este site descreve a API da nuvem HTTP.

01 Comece com uma solicitação que não consome créditos

Seção intitulada “01 Comece com uma solicitação que não consome créditos”

Confirme se sua chave e sua rede estão funcionando antes de enviar arquivos. A verificação de saldo não consome créditos nem gera nenhum trabalho de tradução.

  1. Obtenha uma chave de API

    Faça login no console da API API e crie uma chave que comece com sk_. Use uma chave separada para cada aplicação e defina um orçamento para ela.

    Uma chave serve para a conta que a criou. Mantenha-a no servidor e leia-a de uma variável de ambiente; nunca a inclua no código-fonte da página web nem em um repositório público.

  2. Verifique o saldo

    Defina a variável de ambiente OMNIDOC_API_KEY e, em seguida, execute qualquer um dos exemplos abaixo. O sucesso retorna JSON; 401 indica que a chave apresenta um problema e precisa ser verificada. Nunca exiba a chave completa em tickets, capturas de tela ou logs.

    Terminal window
    export OMNIDOC_API_KEY="sk_your_key"
    curl --fail-with-body --silent --show-error \
    'https://omnidoc.top/api/v1/billing/credits/balance' \
    -H "X-API-Key: $OMNIDOC_API_KEY"

Um carregamento bem-sucedido apenas indica que o arquivo foi armazenado. Após criar um job, aguarde até que ele atinja um estado final e, em seguida, liste e baixe seus resultados.

EtapaMétodo e caminhoO que manter
Solicitar um envioPOST /upload/presignupload_url, upload_headers, finalize_token
Envie o arquivoPUT para o upload_url retornadoResposta de sucesso; esta solicitação não contém uma chave API
Confirme o carregamentoPOST /upload/finalizedocument.id
Crie uma traduçãoPOST /jobsTrabalho id
Verifique o statusGET /jobs/{job_id}completed ou failed
Liste os resultadosGET /artifacts?job_id={job_id}IDs e formatos de artefatos
Baixar um resultadoGET /artifacts/{artifact_id}/downloadBytes do arquivo e o nome do arquivo de resposta

Para o carregamento direto, envie o upload_headers do servidor exatamente como foi retornado e nunca envie X-API-Key para o endereço de armazenamento. Se o endereço de carregamento expirar ou a transferência falhar, solicite um novo. Detalhes: protocolo de carregamento , início rápido , ciclo de trabalho completo de Node.js e campos da solicitação de tradução .

Cada entrada lista os caminhos, campos de solicitação e exemplos. O status do serviço da sua conta e os limites da sua chave aplicam-se a todos eles.

Uma chave de API identifica uma conta. Não é uma senha pública para baixar um arquivo.

Cabeçalho da solicitação

Use X-API-Key: sk_… ou Authorization: Bearer sk_…, um dos dois por solicitação. Envie Content-Type: application/json com corpos JSON.

O que uma chave pode alcançar

Uma chave acessa apenas os recursos que sua conta pode utilizar; o status do serviço, o orçamento da chave e as configurações de tradução permitidas continuam a ser aplicados. Alterações na conta e a criação, rotação ou revogação de chaves são realizadas no console.

Veja autenticação, orçamentos e rotação e serviços e permissões .

05 Incorporar o tratamento de falhas de compilação à integração

Seção intitulada “05 Incorporar o tratamento de falhas de compilação à integração”

Um timeout não significa que o trabalho não foi criado. Diferencie erros retentivos de solicitações que precisam ser corrigidas, para que nada seja enviado ou processado duas vezes.

  • Criação idempotente : gere um Idempotency-Key para cada nova operação de criação; ao repetir a mesma operação, reutilize a chave original e o corpo da solicitação exatamente igual. Operações de documentos, trabalhos de mídia e criação de voz exigem a chave; para outros endpoints de criação, consulte suas páginas de referência.
  • Notificações assíncronas : o polling é adequado para uma primeira integração; para acompanhamento contínuo, use SSE , e para receber os estados finais em segundo plano, utilize um webhook .
StatusVerifique primeiroO que fazer
401 / 403Chave, permissões, propriedade de recursosCorrija as credenciais ou permissões; não tente novamente sem verificar.
402Créditos disponíveisRecarregue e envie novamente
409Chave e corpo da idempotência, estado do recursoConsulte a operação original antes de iniciar uma nova
422Erros de campo na respostaCorrija os parâmetros ou o arquivo
429Negócios code e Retry-AfterOs limites de taxa e de fila podem ser aguardados; um orçamento de chaves esgotado deve ser aumentado primeiro.
5xxErro temporário do serviçoRetrocesso exponencial limitado; mantenha a chave de idempotência para solicitações de criação

Mantenha o cabeçalho de resposta X-Request-Id, o horário da requisição e o caminho para solução de problemas; nunca registre a chave completa. Todos os códigos de erro e exemplos de tentativa são encontrados na referência de erro . .

06 Verifique como funciona a cobrança antes de integrar

Seção intitulada “06 Verifique como funciona a cobrança antes de integrar”

Sem créditos

O upload, a verificação de trabalhos, o download de resultados e a leitura do saldo e dos registros de liquidação não consomem créditos; o mesmo vale para glossários, projetos, tags, pesquisa e compartilhamento.

Cobrado por uso

A tradução de arquivos, as ferramentas de documentos, a tradução instantânea e os serviços de áudio e vídeo são cobrados com base no uso efetivo; a criação de uma tarefa não representa o custo final.

Antes do início de uma tarefa, apenas o limite de saldo é verificado; após sua conclusão, a utilização efetiva é cobrada. Caso o saldo seja insuficiente, a diferença é registrada como dívida, sendo quitada prioritariamente com créditos recebidos posteriormente. É possível conciliar cobranças e reembolsos por tarefa ou por operação de crédito. Quando o orçamento de uma chave é esgotado, ainda é possível consultar as tarefas, resultados e registros associados a essa chave.