Escaneo por API

El escaneo por API convierte un PDF en una copia escaneada realista mediante una llamada REST, ideal para procesos automatizados e integraciones. Crea el trabajo, sube el PDF y consulta el estado o espera el webhook: tres pasos desde cualquier entorno o lenguaje capaz de enviar una petición HTTP. El espacio de color, la resolución, la rotación, el desenfoque, el ruido, el brillo, el contraste y el borde son configurables.

Cómo funciona la llamada

  1. Crear el trabajo

    POST /v1/scan-jobs

    Envía tu config y, opcionalmente, webhookUrl; recibes un jobID y una uploadURL prefirmada.

  2. Subir el PDF

    PUT {uploadURL}

    Haz PUT del archivo directamente a la dirección S3 prefirmada del paso anterior: no hace falta token.

  3. Recoger la copia escaneada

    GET /v1/scan-jobs/{jobID}

    Consulta el estado o espera el webhook; cuando el trabajo esté completed, descárgala desde downloadURL.

Dónde encaja

Producción por lotes desde el backend

Los contratos, las facturas y los informes generados en el servidor pasan directamente por el efecto de escaneo, sin que nadie repita el proceso a mano en la web.

Dentro de un sistema existente

Añade una acción «exportar copia escaneada» a un CRM, un ERP o un sistema de tickets y deja que llame a la API.

Procesos automatizados

CI, n8n, Zapier y similares lanzan un trabajo con un evento, y el webhook da paso al siguiente al terminar.

Grandes colas de archivos

Los trabajos son asíncronos: se crean y cada uno se procesa por su cuenta, con el progreso disponible mediante status y createdAfter.

Lenguajes y entornos

TypeScriptfetch / axios
Node.jsfetch / undici
Pythonrequests / httpx
Gonet/http
PHPcURL / Guzzle
Rubynet/http
JavaHttpClient
cURLLínea de comandos / CI
MásCualquier cliente HTTP

La API es HTTP y JSON estándar, así que cualquier lenguaje o plataforma de automatización capaz de enviar una petición puede usarla.

Ejemplos de código

API Bearer Token

El token pertenece a tu cuenta y puedes regenerarlo cuando quieras. El escaneo por API requiere una cuenta Pro: sin un token válido la API responde 401, y sin el rol Pro responde 403.

Pruébalo

Ajusta los parámetros, mira cómo cambia el cuerpo de la petición y lanza las tres llamadas a la API.

Parámetros de escaneo

La prueba llama a la API con tu token y necesita una cuenta Pro; los parámetros y el cuerpo de la petición se pueden consultar libremente.

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"
  }
}

Información del trabajo de escaneo

ejemplo
{
  "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-…"
}

Referencia de la API

MétodoRutaDescripción
POST/v1/scan-jobsCrea un trabajo de escaneo. Envía config y, opcionalmente, webhookUrl; recibes el objeto del trabajo con status created y una uploadURL prefirmada.
PUT{uploadURL}La dirección S3 prefirmada del paso anterior, que no está en api.lookscanned.ioSube el PDF de origen con Content-Type: application/pdf y Content-Length. La dirección lleva su propia firma, así que no añadas la cabecera Authorization.
GET/v1/scan-jobs/{jobID}Consulta un único trabajo para hacer sondeo. Con created incluye uploadURL; con completed, downloadURL.
GET/v1/scan-jobsLista tus propios trabajos, filtrados por jobID, status o createdAfter.
Estadocreatedprocessingcompletedfailed
  • 401 sin token válido
  • 403 la cuenta no es Pro
  • 404 el trabajo no existe

Cuerpo de la petición

CampoTipoPredeterminadoDescripción
webhookUrlstring · —Se llama una vez cuando el trabajo termina, así no hace falta ir consultando el estado.
config.colorspace'gray' | 'sRGB' · graygrayEspacio de color de la imagen de salida; gray es un escaneo en blanco y negro.
config.resolutionnumber · 7272Resolución de la imagen de salida, en PPP.
config.rotatenumber · —Rotación de todo el documento, en grados.
config.rotate_varnumber · —Margen de la rotación aleatoria por página, en grados: el aspecto del papel colocado torcido.
config.blurnumber · 00Cantidad de desenfoque.
config.noisenumber · 00Cantidad de ruido.
config.brightnessnumber · 11Brillo; 1 lo deja sin cambios.
config.contrastnumber · 11Contraste; 1 lo deja sin cambios.
config.borderboolean · falsefalseSi se añade un borde de escaneo a la página.
config.output_format'image/png' | 'image/jpeg' · image/jpegimage/jpegFormato de imagen al que se renderizan las páginas.

Todos los campos son opcionales. Los valores de partida de «Pruébalo» (resolución 150, rotación 1, brillo y contraste 1,3) son la combinación que recomienda la aplicación web, no los valores predeterminados de la API.

Campos del objeto del trabajo que conviene vigilar

status
created / processing / completed / failed: determina si aparecen las dos direcciones siguientes.
uploadURL
Solo mientras está created. Dirección de subida prefirmada que caduca.
downloadURL
Solo cuando está completed. Dirección de descarga prefirmada que caduca.
inputUploadedAt / completedAt
Cuándo terminó de subirse el origen y cuándo terminó el trabajo; la diferencia es el tiempo de procesamiento.

Preguntas frecuentes

¿El escaneo por API necesita Pro?

Sí. Sin un token válido la API responde 401, y una cuenta sin el rol Pro recibe 403. Si mejoras la cuenta e inicias sesión, el token aparece en esta página.

¿Cómo sé cuándo ha terminado un trabajo?

De dos formas: consulta GET /v1/scan-jobs/{jobID} periódicamente, o pasa un webhookUrl al crear el trabajo y deja que el servicio te avise una vez.

¿El resultado es igual que al escanear en la web?

Sí. Ambos usan la misma implementación del efecto de escaneo, y el espacio de color, la resolución, la rotación, el desenfoque, el ruido, el brillo, el contraste y el borde de config son las mismas opciones de la web con otro nombre: con los mismos parámetros se obtiene el mismo resultado. Solo cambia dónde ocurre el trabajo: en local en la página, en remoto a través de la API.

¿Puedo guardar las direcciones de subida y descarga para reutilizarlas?

Es mejor no hacerlo. uploadURL y downloadURL son direcciones prefirmadas con caducidad; cuando expiran hay que volver a consultar el trabajo para obtener unas nuevas.

¿Cuánto tarda un trabajo?

Depende del número de páginas y de la resolución. Unas pocas páginas suelen terminar en segundos, y una resolución mayor o un documento más largo tardan más. La diferencia entre inputUploadedAt y completedAt es el tiempo real transcurrido.

¿Qué pasa si un trabajo falla?

El estado pasa a failed. Las causas habituales son un archivo que no es un PDF válido, restricciones de cifrado o una subida interrumpida. Comprueba que el archivo se abre y crea un trabajo nuevo.

¿Puedo consultar trabajos anteriores?

Sí. GET /v1/scan-jobs lista tus propios trabajos y admite filtros por jobID, status y createdAfter, suficiente para cuadrar cuentas o repetir una descarga.