A API da EZDocu para desenvolvedores

Com a API da EZDocu (v1) você conecta o seu próprio sistema (CRM, ERP, site de pedidos) à EZDocu. Seu sistema envia o documento, cria o pedido de tradução ou de diagramação, fica sabendo quando ele terminou e baixa o resultado, sem entrar no painel. São os mesmos pedidos e o mesmo saldo de créditos que você usa na web.

Quem pode criar chaves

Não depende do plano: depende da permissão Chaves de API. O proprietário sempre a tem e, por padrão, os gerentes também. Revisor e Membro vêm com ela desligada; o proprietário pode ligá-la por pessoa em Equipe.

Com acesso somente leitura, você não pode ver, criar nem revogar chaves. Cada chave trabalha com o acesso de quem a criou e nunca faz mais do que essa pessoa. Se essa pessoa for desativada na equipe, a chave dela aparece como Suspensa.

Criar uma chave

1. Entre em Configurações › Chaves de API.
2. Clique em Criar chave.
3. Dê um Nome para reconhecê-la, por exemplo Integração ERP.
4. Escolha o Ambiente: Staging para testar ou Produção para trabalhar de verdade.
5. Marque os Serviços: Tradução, Layout ou os dois. Sem serviços, a chave só consulta.
6. Em Acesso por área, marque leitura ou escrita. Você só pode dar os acessos que tem; Pedidos e Webhooks exigem a permissão «Ver e atribuir todos os documentos».
7. Se quiser, defina um Limite diário de páginas (vazio = sem limite; máximo de 5000).
8. Clique em Criar chave, copie-a com Copiar e clique em Já guardei. A chave completa só é mostrada essa vez.

Você pode ter até 20 chaves ativas. Revogar desativa uma chave na hora, e isso não pode ser desfeito. Trate a chave como uma senha.

Staging e Produção: para onde aponta cada chave

As duas são criadas aqui, em www.ezdocu.ai, em Configurações › Chaves de API. Você não precisa de outra conta.

Cada chave só funciona na sua URL. Comece com Staging; quando funcionar, troque a URL e a chave: as rotas são as mesmas.

Onde fica a documentação

No menu lateral, em Documentação da API. Ela tem o Início rápido, os guias Traduzir um documento, Layout sem tradução e Revisão humana, Webhooks e verificação de assinatura e a referência de cada rota com exemplos.

• Em Ambientes você escolhe Staging ou Produção: mudam a URL base, os exemplos e os downloads (Baixar Postman e Baixar OpenAPI).
• Testar no Swagger chama o servidor do site em que você está: em www é Produção, e criar um pedido cobra créditos. Para a chave de Staging, use o Postman ou o seu código.

O fluxo básico

Cada requisição leva o cabeçalho Authorization: Bearer <sua chave>. Todo POST, PATCH, PUT e DELETE leva também Idempotency-Key: se você repetir a requisição com a mesma chave de idempotência, nunca são criados dois pedidos nem há cobrança dupla.

1. Envie o arquivo com POST /uploads (ele devolve uma URL de envio), mande o arquivo para essa URL e confirme com POST /uploads/{id}/complete. Se ele já estiver em uma URL https:// pública, informe-a em file_url ao criar o pedido.
2. Crie o pedido com POST /orders. Em mode vai translate (traduzir) ou layout (diagramar no mesmo idioma). Ao traduzir, indique target_language, por exemplo en-US. O idioma do documento é detectado automaticamente.
3. Aguarde o resultado: com o webhook order.completed (recomendado) ou consultando GET /orders/{id} a cada 15 a 30 segundos.
4. Baixe: com o pedido em completed, o detalhe traz um link por arquivo, válido por 1 hora.

Quais arquivos você recebe

PDF, DOCX e HTML (um HTML por página e um com todas), na combinação que você pedir, além do certificado e do original. O conteúdo do documento nunca vem no JSON da resposta: só os links e os dados do pedido. Ao traduzir, o certificado e a assinatura digital do PDF vão por padrão; você pode tirá-los na requisição.

Webhooks

São criados pela API (POST /webhooks), não em Configurações. A EZDocu envia um POST assinado para a sua URL https:// a cada evento:

O segredo da assinatura (whsec_…) é mostrado uma única vez. Seu servidor deve responder 2xx em menos de 10 segundos; caso contrário, a EZDocu tenta de novo durante pouco mais de um dia e meio.

Revisão humana

Com review_required: true, o pedido para em in_review e espera a sua equipe, sem limite de tempo. Quem revisa abre o pedido em Pedidos, clica em Continuar Pedido, revisa e clica em Finalizar Pedido. Então chega order.completed. Quem finaliza escolhe o formato, o certificado e o Selo Human Verified: um pedido sem revisão nunca leva esse selo. A aprovação é feita na web, não pela API.

Créditos e limites

• O mesmo saldo da web: 1 crédito por página, cobrado ao criar o pedido.
• Sem saldo, POST /orders responde 402 INSUFFICIENT_CREDITS e nada é criado nem cobrado.
• Se um pedido cobrado falhar ou você o cancelar, os créditos não são devolvidos automaticamente: escreva para o suporte com o número do pedido.
• Pedir DOCX, HTML, certificado ou revisão não custa nada a mais.
• 100 requisições por minuto por chave (padrão). Arquivos de até 50 MB e 2000 páginas, em PDF, JPG, PNG, TIFF, WebP, HEIC, DOCX ou ODT.

Erros frequentes

Painel de uso

No menu lateral, API abre Uso da API: requisições, pedidos, páginas, erros, webhooks e limites da sua conta, por período, por chave e por membro. Quem tem a permissão Chaves de API pode vê-lo.

Perguntas frequentes

Preciso de um plano especial para usar a API? Não. É preciso ter a permissão Chaves de API, que o proprietário e os gerentes têm.

Meu programador recebe 401 ou 403 com a chave de Staging. O que está acontecendo? Quase sempre é a URL: a chave de Staging (ezk_test_) só funciona em https://staging.ezdocu.ai/api/v1, e a de Produção (ezk_live_), em https://www.ezdocu.ai/api/v1. Se a chave de Staging for nova, espere um minuto antes de usá-la.

Os testes com a chave de Staging gastam créditos? Não: os pedidos são simulados. Só a chave de Produção cobra.

Posso receber a tradução como texto em JSON? Não. A API entrega arquivos: PDF, DOCX ou HTML.