← PDFtoSCAN Acceder / Obtener API key

Documentación API

Usa la conversión PDFtoSCAN desde tus aplicaciones. Todas las peticiones requieren una API key (obtén una tras registrarte).

URL base

Todos los endpoints son relativos a:

https://pdftoscan.com/api/v1

Autenticación

Incluye tu API key en cada petición con uno de estos métodos:

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

Para obtener una API key: registrarte, luego en tu Área personal genera una nueva. La clave se muestra solo una vez—guárdala de forma segura.

Convertir a aspecto escaneado

POST /convert.php

Sube un PDF o imagen, o envía la URL de un archivo, y recibe un PDF con aspecto escaneado (inclinación, ruido, fondo sucio opcional, A4 opcional).

Petición

Método: POST
Content-Type: multipart/form-data (o application/x-www-form-urlencoded con file_url puedes usar application/x-www-form-urlencoded)

Parámetros

Parámetro	Tipo	Requerido	Descripción
`file` o `pdf`	file	No	Archivo PDF, JPG, PNG, TIFF o WebP a convertir (subida). Usa file o file_url.
`file_url`	string	No	URL HTTP(S) de un PDF o imagen a convertir. Usa subida de archivo o file_url (máx. 50 MB, timeout 30 s).
`color_mode`	string	No	color o bw. Por defecto: bw (blanco y negro).
`rotate`	number	No	Inclinación en grados (-1.5 a 1.5). Por defecto: 0.
`noise`	number	No	Cantidad de ruido 0–1. Por defecto: 0.1 (10%).
`dirty_background`	string	No	1 (por defecto) para bordes negros sucios, 0 para desactivar.
`force_a4`	string	No	1 (por defecto) para A4, 0 para tamaño original.

Respuesta

Éxito (200): El body es el PDF. Guarda o transmite el contenido binario.

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

Códigos de estado

Code	Significado
200	Éxito — la respuesta es el PDF.
400	Petición incorrecta — archivo faltante, formato erróneo o error de subida.
401	No autorizado — API key faltante o no válida.
405	Método no permitido — usa POST.
500	Error del servidor — conversión fallida.
503	Servicio no disponible — conversión no disponible en el servidor.

Ejemplos

cURL

Subir un archivo:

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

O enviar la URL de un archivo:

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

Se permiten peticiones desde cualquier origen. Se soportan peticiones OPTIONS de preflight.

Uso y límites

Cada conversión se cuenta por API key. En tu área personal puedes ver el uso total y de los últimos 7 y 30 días. No hay límites de tasa integrados; aplican los límites de subida y recursos del servidor.

Formatos soportados

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

Salida: Siempre PDF (con aspecto escaneado).