Digitalização por API

A digitalização por API transforma um PDF em uma cópia digitalizada realista com uma chamada REST, o que atende a fluxos automatizados e integrações em aplicativos. Crie o trabalho, envie o PDF e consulte o status ou aguarde o webhook: três passos, a partir de qualquer ambiente ou linguagem capaz de fazer uma requisição HTTP. Espaço de cores, resolução, rotação, desfoque, ruído, brilho, contraste e borda são todos configuráveis.

Como funciona uma chamada

  1. Criar o trabalho

    POST /v1/scan-jobs

    Envie sua config e, se quiser, um webhookUrl; você recebe um jobID e um uploadURL pré-assinado.

  2. Enviar o PDF

    PUT {uploadURL}

    Faça PUT do arquivo diretamente para o endereço S3 pré-assinado do passo anterior — não é preciso token.

  3. Obter a cópia digitalizada

    GET /v1/scan-jobs/{jobID}

    Consulte o status ou aguarde o webhook; assim que o trabalho estiver completed, baixe a cópia pelo downloadURL.

Onde se encaixa

Produção em lote no backend

Contratos, faturas e relatórios gerados no servidor passam diretamente pelo efeito de digitalização, sem que ninguém repita o processo à mão na página web.

Dentro de um sistema existente

Acrescente a um CRM, ERP ou sistema de tickets uma ação “exportar cópia digitalizada” que chama a API.

Cadeias de automação

CI, n8n, Zapier e afins iniciam um trabalho a partir de um evento, e no fim o webhook passa a vez ao passo seguinte.

Filas grandes de arquivos

Os trabalhos são assíncronos: depois de criados, cada um é processado de forma independente, e o progresso fica disponível por status e createdAfter.

Linguagens e ambientes

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLLinha de comando / CI
MaisQualquer cliente HTTP

A API usa apenas HTTP e JSON, por isso qualquer linguagem ou plataforma de automação capaz de fazer uma requisição consegue chamá-la.

Exemplos de código

API Bearer Token

O token pertence à sua conta e pode ser gerado de novo a qualquer momento. A digitalização por API exige uma conta Pro: sem um token válido a API responde 401 e sem a função Pro responde 403.

Experimentar

Ajuste os parâmetros, veja o corpo da requisição mudar com eles e faça as três chamadas à API.

Parâmetros de digitalização

Uma execução de teste chama a API com seu token e exige uma conta Pro; os parâmetros e o corpo da requisição podem ser consultados à vontade.

POST/v1/scan-jobs
{
  "config": {
    "rotate": 1,
    "rotate_var": 0.5,
    "colorspace": "gray",
    "blur": 0,
    "noise": 0,
    "border": false,
    "brightness": 1.3,
    "contrast": 1.3,
    "resolution": 150,
    "output_format": "image/jpeg"
  }
}

Informações do trabalho de digitalização

exemplo
{
  "jobID": "3f9c1e64-0000-4000-8000-00000000a71b",
  "userID": "8f21c4b0-0000-4000-8000-000000004a17",
  "createdAt": 1724409600,
  "status": "completed",
  "inputUploadedAt": 1724409601,
  "completedAt": 1724409602,
  "numPages": 6,
  "downloadURL": "https://…/output/3f9c.pdf?X-Amz-…"
}

Referência da API

MétodoCaminhoDescrição
POST/v1/scan-jobsCria um trabalho de digitalização. Envie config e, se necessário, webhookUrl; você recebe o objeto do trabalho com o status created e um uploadURL pré-assinado.
PUT{uploadURL}O endereço S3 pré-assinado do passo anterior, que não está em api.lookscanned.ioEnvia o PDF de origem com Content-Type: application/pdf e Content-Length. O endereço já traz a própria assinatura, por isso não acrescente o cabeçalho Authorization.
GET/v1/scan-jobs/{jobID}Lê um único trabalho, para consulta periódica. Enquanto o status é created, traz uploadURL; quando fica completed, traz downloadURL.
GET/v1/scan-jobsLista seus trabalhos, com filtros por jobID, status ou createdAfter.
Statuscreatedprocessingcompletedfailed
  • 401 sem token válido
  • 403 a conta não é Pro
  • 404 trabalho inexistente

Corpo da requisição

CampoTipoPadrãoDescrição
webhookUrlstring · —É chamado uma vez quando o trabalho termina, para você não precisar ficar consultando o status.
config.colorspace'gray' | 'sRGB' · graygrayEspaço de cores da imagem gerada; gray é uma digitalização em preto e branco.
config.resolutionnumber · 7272Resolução da imagem gerada, em DPI.
config.rotatenumber · —Rotação de todo o documento, em graus.
config.rotate_varnumber · —Amplitude da rotação aleatória de cada página, em graus — o aspecto de uma folha colocada torta.
config.blurnumber · 00Intensidade do desfoque.
config.noisenumber · 00Intensidade do ruído.
config.brightnessnumber · 11Brilho; 1 deixa a imagem inalterada.
config.contrastnumber · 11Contraste; 1 deixa a imagem inalterada.
config.borderboolean · falsefalseSe a página leva uma borda de digitalização.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegFormato de imagem em que as páginas são compostas.

Todos os campos podem ser omitidos. Os valores iniciais de “Experimentar” — resolução 150, rotação 1, brilho e contraste 1,3 — são a combinação recomendada pelo aplicativo web, não os padrões da API.

Campos do objeto do trabalho que vale a pena acompanhar

status
created / processing / completed / failed — determina se os dois endereços abaixo aparecem.
uploadURL
Apenas enquanto está created. Endereço de envio pré-assinado, com prazo de validade.
downloadURL
Apenas depois de completed. Endereço de download pré-assinado, com prazo de validade.
inputUploadedAt / completedAt
Quando terminou o envio da origem e quando terminou o trabalho; a diferença é o tempo de processamento.

Perguntas frequentes

A digitalização por API precisa de Pro?

Sim. Sem um token válido a API responde 401, e uma conta sem a função Pro recebe 403. Depois de mudar para Pro e fazer login, o token aparece nesta página.

Como sei quando um trabalho termina?

De duas maneiras: consultar GET /v1/scan-jobs/{jobID} periodicamente, ou passar um webhookUrl ao criar o trabalho e deixar que o serviço avise você uma única vez.

O resultado é igual ao da digitalização na página web?

É igual. Os dois usam a mesma implementação do efeito de digitalização, e o espaço de cores, a resolução, a rotação, o desfoque, o ruído, o brilho, o contraste e a borda em config correspondem às mesmas opções da página web, com outros nomes: parâmetros iguais dão resultados iguais. Só muda o lugar onde o trabalho acontece — localmente na página, remotamente pela API.

Posso salvar os endereços de envio e de download e reutilizá-los?

É melhor não salvar. uploadURL e downloadURL são endereços pré-assinados com prazo; quando expiram é preciso ler o trabalho de novo para obter novos.

Quanto tempo demora um trabalho?

Depende do número de páginas e da resolução. Poucas páginas costumam ficar prontas em segundos; resoluções mais altas ou documentos mais longos demoram mais. A diferença entre inputUploadedAt e completedAt dá o tempo real.

E se um trabalho falhar?

O status passa a failed. As causas comuns são um arquivo que não é um PDF válido, restrições de criptografia ou um envio interrompido. Confira se o arquivo abre e crie um trabalho novo.

Posso consultar trabalhos anteriores?

Sim. GET /v1/scan-jobs lista seus trabalhos e aceita filtros por jobID, status e createdAfter, o que basta para conferir contas ou repetir um download.