API y conexión MCP

Cómo funciona

El procesado de un PDF puede tardar de segundos a varios minutos: validación de conformidad, conversión, etiquetado de la estructura y descripción de las imágenes. Por eso la API es asíncrona: nunca esperas con la conexión abierta.

1. Subes el PDF indicando el tipo: audit (informe, gratis) o conversion (genera el PDF/A accesible, consume cuota del plan).
2. La respuesta es inmediata (202 Accepted) y contiene el id del documento. El trabajo entra en la cola y lo procesa el servidor en segundo plano.
3. Consultas el estado con ese id cuantas veces quieras (o, por MCP, esperas con wait_for_document).
4. Cuando el estado es done: pides el informe y/o descargas el PDF/A.

El id tiene la forma AAAAMMDD-HHMMSS-xxxxxx y es el mismo identificador que verás en tu área de cliente.

Autenticación

Requisito de plan: la API y el MCP están incluidos a partir del plan Business. Con un plan inferior no se pueden crear credenciales y las llamadas responden 403 plan_required. Ver planes.

Todas las llamadas (salvo /api/v1/ping) requieren una clave de API creada en Mi cuenta → Credenciales de API. La clave identifica a tu cuenta: los documentos que crees son tuyos y consumen tu plan.

Authorization: Bearer pdfa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Si tu entorno no permite enviar la cabecera Authorization, puedes usar X-Api-Key: pdfa_…. El parámetro ?api_key= también funciona, pero no es recomendable (queda en los registros del servidor).

• La clave solo se muestra una vez, al crearla: guárdala como una contraseña.
• Usa una clave por integración y revoca la que ya no uses; la revocación es inmediata.
• No hay sesión ni cookies: cada petición es independiente.
• Usa HTTPS en producción para que la clave nunca viaje en claro.

API REST

Método	Ruta	Descripción	Clave
GET	/api/v1/ping	Comprobación de vida. No requiere credencial.	no
GET	/api/v1/account	Plan contratado, límites y consumo del mes.	sí
GET	/api/v1/documents	Lista tus documentos. Parámetros: page, per_page, type, status.	sí
POST	/api/v1/documents	Sube un PDF y lo encola (type=audit|conversion). Devuelve el id con el que se consulta el estado. Responde 202 Accepted.	sí
GET	/api/v1/documents/{id}	Estado del procesado: queued, processing, done o error, con avance y nota.	sí
PUT	/api/v1/documents/{id}	Actualiza los metadatos del documento (filename).	sí
DELETE	/api/v1/documents/{id}	Elimina el documento completo: original, PDF/A e informe. Irreversible.	sí
GET	/api/v1/documents/{id}/report	Informe de accesibilidad completo (auditoría + conversión). Parámetros: include_findings=0|1, max_findings.	sí
GET	/api/v1/documents/{id}/audit	Solo el resultado de la auditoría del original.	sí
POST	/api/v1/documents/{id}/audit	Vuelve a auditar el original (por ejemplo, tras un cambio de criterios). 202 Accepted.	sí
GET	/api/v1/documents/{id}/conversion	Estado y resultado de la conversión: not_requested, processing o done.	sí
POST	/api/v1/documents/{id}/conversion	Encola una conversión NUEVA del documento. 409 si ya hay una en curso.	sí
PUT	/api/v1/documents/{id}/conversion	Asegura la conversión: idempotente, no duplica el trabajo ni la cuota. Es la indicada si tu integración reintenta.	sí
DELETE	/api/v1/documents/{id}/conversion	Borra solo el PDF/A generado; conserva el original y la auditoría.	sí
GET	/api/v1/documents/{id}/file/{original|pdfa}	Descarga el PDF elegido (application/pdf).	sí
POST	/mcp	Servidor MCP (JSON-RPC 2.0). Tiene su propia página de documentación.	sí

1. Subir un documento

Tres formas de enviar el PDF: multipart con el campo file (recomendada para archivos grandes), JSON con file_base64 o file_url, o el PDF crudo en el cuerpo.

# multipart (auditoría)
curl -X POST https://pdfaccesible.com/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@annual-report-2026.pdf" \
  -F "type=audit"

# JSON con URL (conversión a PDF/A accesible)
curl -X POST https://pdfaccesible.com/api/v1/documents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"conversion","file_url":"https://example.com/annual-report-2026.pdf"}'

HTTP/1.1 202 Accepted
{
  "id": "20260730-120501-a1b2c3",
  "status": "queued",
  "type": "conversion",
  "filename": "annual-report-2026.pdf",
  "size_bytes": 1048576,
  "progress_pct": 0,
  "step": "Queued",
  "created_at": "2026-07-30T12:05:01+02:00",
  "expires_at": "2026-08-29T12:05:01+02:00",
  "score": null,
  "error": null,
  "links": { "self": "https://pdfaccesible.com/api/v1/documents/20260730-120501-a1b2c3", "web": "…" }
}

2. Consultar el estado con el id

curl https://pdfaccesible.com/api/v1/documents/20260730-120501-a1b2c3 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "20260730-120501-a1b2c3",
  "status": "done",
  "progress_pct": 100,
  "step": "Completed",
  "score": 100,
  "breakdown": { "overall": 100, "wcag": 100, "pdf_ua": 100, "eaa": 100 },
  "converted": true,
  "links": {
    "self":     "https://pdfaccesible.com/api/v1/documents/20260730-120501-a1b2c3",
    "report":   "https://pdfaccesible.com/api/v1/documents/20260730-120501-a1b2c3/report",
    "original": "https://pdfaccesible.com/api/v1/documents/20260730-120501-a1b2c3/file/original",
    "pdfa":     "https://pdfaccesible.com/api/v1/documents/20260730-120501-a1b2c3/file/pdfa"
  }
}

Sondea cada 5-10 s. Una auditoría suele tardar entre 10 y 60 s; una conversión completa, entre 1 y 5 min según el tamaño y el número de imágenes.

3. Informe y descarga

# informe completo (nota global, por norma y hallazgos)
curl "https://pdfaccesible.com/api/v1/documents/20260730-120501-a1b2c3/report?max_findings=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# PDF/A accesible
curl -L -o accessible.pdf \
  https://pdfaccesible.com/api/v1/documents/20260730-120501-a1b2c3/file/pdfa \
  -H "Authorization: Bearer YOUR_API_KEY"

4. Convertir un documento ya subido

curl -X PUT https://pdfaccesible.com/api/v1/documents/20260730-120501-a1b2c3/conversion \
  -H "Authorization: Bearer YOUR_API_KEY"

5. Un verbo, una acción

Cada combinación de ruta + verbo es una acción distinta. En particular: POST /documents/{id}/conversion encola una conversión nueva y falla con 409 si ya hay una en marcha, mientras que PUT sobre la misma ruta es idempotente (si ya existe el PDF/A, o ya se está generando, no repite el trabajo ni vuelve a consumir cuota): es la que conviene usar en integraciones que reintentan. DELETE /documents/{id}/conversion borra solo el PDF/A generado y conserva el original y su auditoría; DELETE /documents/{id} lo borra todo.

Estructura del informe

La nota global es la media de las tres dimensiones de accesibilidad. PDF/UA se valida con un validador de conformidad automático (autoritativo); WCAG y EAA se evalúan sobre los hechos del documento y las reglas PDF/UA incumplidas.

{
  "id": "20260730-120501-a1b2c3",
  "filename": "annual-report-2026.pdf",
  "status": "done",
  "audit": {
    "score": 42,
    "breakdown": { "overall": 42, "wcag": 20, "pdf_ua": 40, "eaa": 67 },
    "pages": 24,
    "pdf_version": "1.7",
    "machine_validated": true,
    "finding_counts": { "pass": 12, "warning": 3, "fail": 9, "info": 4, "na": 1 },
    "standards": {
      "wcag":   { "standard": "WCAG",   "verdict": "fail", "score": 20, "findings_total": 6,
                  "findings": [ { "severity": "fail", "title": "…", "detail": "…", "reference": "WCAG 1.3.1" } ] },
      "pdf_ua": { "standard": "PDF/UA", "verdict": "fail", "score": 40, "findings_total": 3, "findings": [] },
      "eaa":    { "standard": "EAA",    "verdict": "warning", "score": 67, "findings_total": 5, "findings": [] }
    }
  },
  "conversion": {
    "created_at": "2026-07-30T12:09:44+02:00",
    "pdfa_part": 2,
    "tagged": true,
    "result": { "score": 100, "breakdown": { "overall": 100, "wcag": 100, "pdf_ua": 100, "eaa": 100 } }
  },
  "score_improvement": { "before": 42, "after": 100, "delta": 58 }
}

Estados de un documento

Estado	Significado
queued	Aceptado y esperando al trabajador de la cola.
processing	En marcha. progress_pct y step indican en qué fase está.
done	Terminado: ya hay informe y, si era una conversión, PDF/A descargable.
error	Ha fallado; el campo error explica por qué. Se reintenta automáticamente hasta 3 veces antes de darse por vencido.

Límites y cuotas

Límite	Valor
Peticiones por minuto y clave	120
Documentos por hora y clave	60
Tamaño máximo de subida (servidor)	128 MB
Tamaño máximo en file_base64	24 MB · por encima, usa multipart o file_url
Auditoría gratuita	hasta 100 MB por documento
Conversiones	según tu plan (tamaño por documento y número al mes)

El consumo del mes se cuenta al dar de alta cada conversión y queda registrado de forma permanente: borrar un documento no devuelve cuota. Al superar la frecuencia recibes 429 con la cabecera Retry-After. Si el plan no cubre una conversión, recibes 402 quota_exceeded: la auditoría sigue estando disponible gratis. Consulta tu consumo en cualquier momento con GET /api/v1/account o la herramienta get_account.

Errores

{ "error": { "code": "quota_exceeded", "message": "You have used your 3 free conversions…" } }

Código	HTTP	Cuándo
unauthorized	401	Falta la clave, o es inválida, revocada o caducada.
quota_exceeded	402	El plan no permite esta conversión (tamaño por documento, límite mensual o conversiones gratuitas agotadas).
email_not_verified	403	La cuenta no ha verificado su email.
plan_required	403	El plan contratado no incluye el acceso a la API ni al MCP (se incluye a partir del plan Business). El campo required_plan de la respuesta indica el plan necesario.
not_found	404	El id no existe en tu cuenta (o la ruta no existe).
method_not_allowed	405	Ese verbo no está permitido en esa ruta; la cabecera Allow indica los que sí.
already_running	409	Ya hay un trabajo de ese tipo en marcha para ese documento (usa PUT si quieres una llamada idempotente).
report_not_ready	409	El documento aún no ha terminado de procesarse.
invalid_request	422	Parámetros incorrectos: el archivo no es un PDF, falta el contenido, tipo desconocido…
too_many_requests	429	Se ha superado el límite de frecuencia. Reintenta según Retry-After.
internal_error	500	Error inesperado del servidor. Si persiste, escríbenos.
api_disabled	503	La API está temporalmente desactivada.

Retención y privacidad

• Tus PDF nunca son públicos: solo se sirven autenticados y solo a la cuenta propietaria.
• Los documentos se conservan 30 días y después se eliminan automáticamente (original, PDF/A e informe). De cada alta y cada borrado queda un registro con la fecha (sin el contenido del documento), que es lo que sostiene el recuento de tu plan y tu historial. Puedes borrarlos antes con DELETE /api/v1/documents/{id} o delete_document.
• La conversión genera automáticamente los metadatos y la descripción de las imágenes; el contenido de tus documentos no se usa para entrenar modelos.
• Consulta el aviso de privacidad y las condiciones.