← PDFtoSCAN Entrar / Obter API key

Documentação API

Use a conversão PDFtoSCAN nas suas aplicações. Todas as pedidos requerem uma API key (obtenha uma após registo).

URL base

Todos os endpoints são relativos a:

https://pdftoscan.com/api/v1

Autenticação

Inclua a sua API key em cada pedido com um destes métodos:

Header Header X-API-Key: sua-api-key
Header Header Authorization: Bearer sua-api-key

Para obter uma API key: registo, depois na sua Área pessoal gere uma nova. A chave é mostrada apenas uma vez—guarde-a em segurança.

Converter para aspecto digitalizado

POST /convert.php

Envie um PDF ou imagem, ou o URL de um ficheiro, e receba um PDF com aspecto digitalizado (inclinação, ruído, fundo sujo opcional, A4 opcional).

Pedido

Método: POST
Content-Type: multipart/form-data (ou application/x-www-form-urlencoded com file_url pode usar application/x-www-form-urlencoded)

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`file` ou `pdf`	file	Não	Ficheiro PDF, JPG, PNG, TIFF ou WebP a converter (carregamento). Use file ou file_url.
`file_url`	string	Não	URL HTTP(S) de um PDF ou imagem a converter. Use carregamento de ficheiro ou file_url (máx. 50 MB, timeout 30 s).
`color_mode`	string	Não	color ou bw. Predefinido: bw (preto e branco).
`rotate`	number	Não	Inclinação em graus (-1.5 a 1.5). Predefinido: 0.
`noise`	number	Não	Quantidade de ruído 0–1. Predefinido: 0.1 (10%).
`dirty_background`	string	Não	1 (predefinido) para bordas sujas, 0 para desativar.
`force_a4`	string	Não	1 (predefinido) para A4, 0 para tamanho original.

Resposta

Sucesso (200): O body é o ficheiro PDF.

Erro (4xx/5xx): Body JSON: {"ok": false, "error": "mensagem"}

Códigos de estado

Code	Significado
200	Sucesso — a resposta é o PDF.
400	Pedido inválido — ficheiro em falta, formato errado ou erro de envio.
401	Não autorizado — API key em falta ou inválida.
405	Método não permitido — use POST.
500	Erro do servidor — conversão falhou.
503	Serviço indisponível — conversão não disponível no servidor.

Exemplos

cURL

Carregar um ficheiro:

curl -X POST "https://pdftoscan.com/api/v1/convert.php" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@/path/to/document.pdf" \
  -F "color_mode=bw" \
  -F "force_a4=1" \
  -o scanned.pdf

Ou enviar o URL de um ficheiro:

curl -X POST "https://pdftoscan.com/api/v1/convert.php" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d "file_url=https://example.com/document.pdf" \
  -d "color_mode=bw" \
  -d "force_a4=1" \
  -o scanned.pdf

JavaScript (fetch)

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('color_mode', 'bw');
formData.append('force_a4', '1');

const response = await fetch('https://pdftoscan.com/api/v1/convert.php', {
  method: 'POST',
  headers: { 'X-API-Key': 'YOUR_API_KEY' },
  body: formData
});

if (!response.ok) {
  const err = await response.json();
  throw new Error(err.error || 'Request failed');
}
const blob = await response.blob();
// e.g. save or open blob as PDF

Python

import requests

url = 'https://pdftoscan.com/api/v1/convert.php'
headers = {'X-API-Key': 'YOUR_API_KEY'}
files = {'file': open('document.pdf', 'rb')}
data = {'color_mode': 'bw', 'force_a4': '1'}

r = requests.post(url, headers=headers, files=files, data=data)

if r.status_code != 200:
    print(r.json().get('error', 'Error'))
else:
    with open('scanned.pdf', 'wb') as f:
        f.write(r.content)

CORS

Pedidos do browser são permitidos de qualquer origem. Pedidos OPTIONS de preflight são suportados.

Uso e limites

Cada conversão é contada por API key. Na sua área pessoal pode ver o uso total e dos últimos 7 e 30 dias. Não há limites de taxa integrados; aplicam-se os limites de upload e recursos do servidor.

Formatos suportados

Entrada: PDF, JPG, JPEG, PNG, TIFF, WebP.

Saída: Sempre PDF (com aspecto digitalizado).