Saltar al contenido principal

Encuentra tu próxima herramienta

Documentación/Primeros pasos/Inicio rápido de la API: tu primera conversión
Primeros pasos

Inicio rápido de la API: tu primera conversión

Crea una clave de API, envía un archivo, espera a que termine el trabajo y descarga el resultado, con solicitudes listas para copiar y pegar.

Respuesta breve

Crea una clave en Panel → API y claves y envía POST https://maxscanner.app/api/v1/jobs/ con la URL pública del archivo, un nombre de archivo y el formato de destino. La API devuelve un jobId al instante; consulta GET /api/v1/jobs/{jobId}/ cada pocos segundos hasta que status sea "completed" y descarga output.downloadUrl en un plazo de cinco minutos.

Inicio rápido

  1. 1Abre Panel → API y claves, elige Crear clave de API, marca "Procesar archivos" y copia la clave (solo se muestra una vez).
  2. 2Guarda la clave en una variable de entorno como MAXSCANNER_API_KEY, nunca en código del lado del cliente.
  3. 3Envía POST /api/v1/jobs/ con url, filename y format. Guarda el jobId de la respuesta 202.
  4. 4Consulta GET /api/v1/jobs/{jobId}/ cada 2–10 segundos hasta que status sea completed o failed.
  5. 5Descarga output.downloadUrl de inmediato: el enlace firmado caduca a los cinco minutos.

Antes de empezar

Todas las solicitudes van a https://maxscanner.app/api/v1/ y envían la clave como token Bearer. Las URL de las solicitudes terminan en barra: una URL sin ella recibe una redirección 308 que la mayoría de los clientes HTTP siguen, pero incluir la barra te ahorra un viaje de ida y vuelta.

El plan Free permite 10 solicitudes al día y 100 al mes, suficiente para crear y probar una integración. Los planes de pago usan en su lugar créditos mensuales; cada endpoint cuesta de 0 a 3 créditos.

  • URL base: https://maxscanner.app/api/v1/
  • Encabezado: Authorization: Bearer <your key>
  • Cuerpo: JSON con Content-Type: application/json
  • Archivos: hasta 50 MB mediante importación por URL o subida directa

Convierte un archivo de Word a PDF

El endpoint de trabajos elige el procesador adecuado según los formatos de entrada y salida. Si pasas una URL pública, el servidor descarga el archivo por sí mismo al crear el trabajo (hasta 50 MB en 30 segundos; no sigue redirecciones, así que usa el enlace final del archivo); para archivos privados, usa una subida directa y pasa sourceKey en su lugar (consulta la guía Archivos y subidas). Añade un encabezado Idempotency-Key para que un reintento nunca cree un segundo trabajo.

curl -X POST 'https://maxscanner.app/api/v1/jobs/' \
  -H "Authorization: Bearer $MAXSCANNER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: quickstart-0001' \
  -d '{ "url": "https://example.com/report.docx", "filename": "report.docx", "format": "pdf" }'

Espera el resultado

Los trabajos son asíncronos para que los archivos grandes nunca mantengan abierta tu conexión HTTP. Consulta la URL de estado empezando con un intervalo de unos 2 segundos y alargándolo hasta 10 segundos. Un archivo de Office pequeño suele terminar en menos de 20 segundos; un vídeo 1080p puede tardar minutos. Cuando status es completed, output incluye el tipo de contenido, el tamaño en bytes y una downloadUrl firmada.

curl 'https://maxscanner.app/api/v1/jobs/6f0c2a6e-8a1b-4a53-9a0e-2b1f4c9d7e11/' \
  -H "Authorization: Bearer $MAXSCANNER_API_KEY"

Siguientes pasos

Sustituye el sondeo por un webhook cuando proceses más que unos pocos archivos, lee la guía de trabajos para conocer las reglas de reintento y elige la guía de la función que corresponda a tu tarea: OCR, herramientas PDF, imágenes, multimedia o ejecución de un flujo de trabajo guardado.

Preguntas frecuentes

¿Necesito instalar un SDK?

No. La API es HTTPS y JSON sin más, así que sirve cualquier lenguaje o herramienta no-code capaz de enviar una solicitud HTTP. La guía de ejemplos de código incluye versiones completas en Node.js, Python, PHP y cURL.

¿Cuánto tiempo es válido un enlace de descarga?

Cinco minutos. Si caduca, vuelve a solicitar el estado del trabajo para obtener un enlace nuevo.

¿Hay un modo de prueba?

Usa el plan Free para hacer pruebas: tiene los mismos endpoints y limita cada cuenta a 10 solicitudes al día y 100 al mes.

Guías relacionadas