Automatización e integración

Claves API, cargas por lote y callbacks sin adivinar las reglas del runtime.

Esta página resume la superficie de integración activa: cómo autenticarte, preparar subidas, consultar jobs individuales o lotes y adjuntar callbacks terminales dentro de la ruta Pro API actual.

Última actualización: 6 de abril de 2026

Inicio rápido

El flujo operativo es deliberadamente estrecho: primero prepara el job, luego sube el archivo al destino devuelto y después consulta o espera el callback.

1Crea una clave API desde la cuenta bajo un plan Pro.
2Envía POST /uploads/prepare o POST /uploads/batch/prepare solo con metadatos.
3Sube el binario exactamente al upload target devuelto por la respuesta.
4Consulta GET /jobs/:jobId o GET /job-batches/:batchId hasta que el resultado quede ready.
5Añade callbackUrl y callbackSecret si quieres una notificación terminal push.

Autenticación y modelo de acceso

Las solicitudes server-to-server pueden autenticarse con X-API-Key. Los flujos del navegador usan el token de sesión de la cuenta, pero el modelo de integración se apoya en las claves API.

- Las claves API se crean en la cuenta y el token completo solo se muestra una vez.
- La preparación por lotes y los webhook callbacks están limitados a la ruta Pro API.
- Los jobs pesados de audio y video siguen gastando créditos de media de la cuenta propietaria.
- El estado de un job individual puede revisarse con autenticación de la cuenta propietaria o con el status token firmado de la respuesta prepare.
- El estado de un lote exige autenticación de la cuenta propietaria y no ofrece una ruta pública con token.

Encabezados para polling autenticado

bash

curl https://your-swapmyfile-host.example/jobs/job_123 \
  -H "X-API-Key: smf_live_your_key"

curl https://your-swapmyfile-host.example/jobs/job_123?token=job_status_token

Flujo individual de prepare-upload-poll

Un job individual empieza solo con metadatos. La API devuelve el registro del job, el upload target, un status token firmado y la lista de checks que van después de recibir la subida.

- POST /uploads/prepare valida la solicitud antes de transferir el cuerpo del archivo.
- La respuesta puede devolver un destino API multipart o un destino direct PUT con completeUrl.
- Después de completar la subida, consulta GET /jobs/:jobId hasta que el estado sea ready o failed.
- Cuando el estado es ready, usa job.downloadUrl como enlace firmado del resultado.
- callbackUrl y callbackSecret son opcionales por job y pueden enviarse ya en prepare.

Preparar un job individual

bash

curl -X POST https://your-swapmyfile-host.example/uploads/prepare \
  -H "Content-Type: application/json" \
  -H "X-API-Key: smf_live_your_key" \
  -d '{
    "converterSlug": "jpg-to-png",
    "inputFilename": "hero.jpg",
    "inputMime": "image/jpeg",
    "inputSize": 245001
  }'

Preparación por lotes y estado agregado

La preparación por lotes permite abrir varios upload targets con una sola solicitud API. El backend actual acepta hasta 25 items por lote y devuelve el batch record junto con las entradas de subida por job.

- POST /uploads/batch/prepare acepta una etiqueta opcional y un array jobs.
- Cada job sigue enviando su converterSlug, filename, mime type, size y ajustes de callback si hacen falta.
- La etiqueta del lote está limitada a 80 caracteres.
- La UI pública de lotes mantiene un solo conversor por página, pero el payload API es job por job.
- Consulta GET /job-batches/:batchId con la misma autenticación de la cuenta propietaria para seguir el estado agregado.

Preparar una solicitud por lotes

bash

curl -X POST https://your-swapmyfile-host.example/uploads/batch/prepare \
  -H "Content-Type: application/json" \
  -H "X-API-Key: smf_live_your_key" \
  -d '{
    "label": "April content refresh",
    "jobs": [
      {
        "converterSlug": "jpg-to-png",
        "inputFilename": "hero-01.jpg",
        "inputMime": "image/jpeg",
        "inputSize": 245001
      },
      {
        "converterSlug": "webp-to-png",
        "inputFilename": "hero-02.webp",
        "inputMime": "image/webp",
        "inputSize": 198221
      }
    ]
  }'

Callbacks terminales

Los callbacks están pensados para el borde terminal del pipeline, no para cada estado intermedio. SwapMyFile envía callbacks solo cuando un job termina en ready o failed.

- Los eventos soportados son job.ready y job.failed.
- callbackUrl debe ser una URL absoluta http o https y callbackSecret es opcional.
- Cuando callbackSecret está presente, la solicitud incluye x-swapmyfile-signature con sha256=<hmac> sobre el body JSON crudo.
- La entrega también incluye los encabezados x-swapmyfile-event y x-swapmyfile-job-id.
- Una respuesta 2xx marca la entrega como correcta. Las entregas fallidas se reintentan hasta 3 veces dentro de una ventana corta.

Payload representativo de callback

json

{
  "event": "job.ready",
  "deliveredAt": "2026-04-06T12:00:00.000Z",
  "job": {
    "jobId": "job_123",
    "converterSlug": "jpg-to-png",
    "status": "ready",
    "inputFilename": "hero.jpg",
    "outputFilename": "hero.png",
    "downloadUrl": "/downloads/signed/example",
    "callback": {
      "url": "https://client.example/hooks/swapmyfile",
      "status": "pending",
      "attempts": 0
    }
  }
}

FAQ de integración

¿Puede una sesión guest usar la ruta API?

No. Los usuarios guest pueden usar el flujo del navegador, pero las claves API, los callbacks y la preparación por lotes están ligados a una cuenta Pro con sesión.

¿Los callbacks sustituyen por completo el polling?

No siempre. Los callbacks son útiles para estados terminales, pero el polling sigue siendo la forma más simple de ver jobs en progreso, avance del lote o disponibilidad de descarga.

¿Puedo consultar un job individual sin guardar credenciales de cuenta?

Sí. La respuesta prepare de un job individual incluye un status token firmado que puedes usar en GET /jobs/:jobId?token=... para acceso solo de estado.

Abre la cuenta antes de automatizar contra producción.

Crea la clave API, revisa los límites del plan de la cuenta propietaria y recarga créditos de media antes si el flujo incluye audio o video pesado.

Abrir cuenta Revisar precios