Digitalização por API

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

Como decorre uma chamada

  1. Criar o trabalho

    POST /v1/scan-jobs

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

  2. Enviar o PDF

    PUT {uploadURL}

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

  3. Recolher a cópia digitalizada

    GET /v1/scan-jobs/{jobID}

    Consulte o estado ou espere pelo webhook; assim que o trabalho estiver completed, baixe-a a partir de 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 ficheiros

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

Linguagens e ambientes

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

A API é HTTP e JSON normais, por isso qualquer linguagem ou plataforma de automação capaz de fazer um pedido 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 o papel Pro responde 403.

Experimentar

Ajuste os parâmetros, veja o corpo do pedido 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 o seu token e exige uma conta Pro; os parâmetros e o corpo do pedido 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; recebe o objeto do trabalho com o estado 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. Em created traz uploadURL; em completed, downloadURL.
GET/v1/scan-jobsLista os seus trabalhos, com filtros por jobID, status ou createdAfter.
Estadocreatedprocessingcompletedfailed
  • 401 sem token válido
  • 403 a conta não é Pro
  • 404 trabalho inexistente

Corpo do pedido

CampoTipoPredefiniçãoDescrição
webhookUrlstring · —É chamado uma vez quando o trabalho termina, para não ter de andar a consultar o estado.
config.colorspace'gray' | 'sRGB' · graygrayEspaço de cor da imagem produzida; gray é uma digitalização a preto e branco.
config.resolutionnumber · 7272Resolução da imagem produzida, 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 aspeto de uma folha pousada torta.
config.blurnumber · 00Intensidade do desfoque.
config.noisenumber · 00Intensidade do ruído.
config.brightnessnumber · 11Brilho; 1 deixa-o inalterado.
config.contrastnumber · 11Contraste; 1 deixa-o inalterado.
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 de partida de «Experimentar» — resolução 150, rotação 1, brilho e contraste 1,3 — são a combinação recomendada pela aplicação web, não as predefinições da API.

Campos do objeto do trabalho a que vale a pena atender

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 descarregamento 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?

Precisa. Sem um token válido a API responde 401, e uma conta sem o papel Pro recebe 403. Depois de mudar para Pro e iniciar sessão, 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 o contacte uma vez.

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

É igual. Ambos usam a mesma implementação do efeito de digitalização, e o espaço de cor, a resolução, a rotação, o desfoque, o ruído, o brilho, o contraste e a borda em config correspondem às opções com o mesmo nome na página web: parâmetros iguais dão resultados iguais. Só muda o sítio onde o trabalho acontece — localmente na página, remotamente através da API.

Posso guardar os endereços de envio e de descarregamento e reutilizá-los?

É melhor não guardar. uploadURL e downloadURL são endereços pré-assinados com prazo; quando expiram é preciso voltar a ler o trabalho 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 estado passa a failed. As causas habituais são um ficheiro que não é um PDF válido, restrições de cifra ou um envio interrompido. Confirme que o ficheiro abre e crie um trabalho novo.

Posso consultar trabalhos anteriores?

Pode. GET /v1/scan-jobs lista os seus trabalhos e aceita filtros por jobID, status e createdAfter, o que chega para conferir contas ou repetir um descarregamento.