API i connexió MCP

Com funciona

El processament d'un PDF pot trigar de segons a diversos minuts: validació de conformitat, conversió, etiquetatge de l'estructura i descripció de les imatges. Per això l'API és asíncrona: no esperes mai amb la connexió oberta.

1. Puges el PDF indicant el tipus: audit (informe, gratis) o conversion (genera el PDF/A accessible, consumeix quota del pla).
2. La resposta és immediata (202 Accepted) i conté l'id del document. La feina entra a la cua i el servidor la processa en segon pla.
3. Consultes l'estat amb aquest id tantes vegades com vulguis (o, per MCP, esperes amb wait_for_document).
4. Quan l'estat és done: demanes l'informe i/o descarregues el PDF/A.

L'id té la forma AAAAMMDD-HHMMSS-xxxxxx i és el mateix identificador que veuràs a la teva àrea de client.

Autenticació

Requisit de pla: l'API i l'MCP estan inclosos a partir del pla Business. Amb un pla inferior no es poden crear credencials i les crides responen 403 plan_required. Veure els plans.

Totes les crides (tret de /api/v1/ping) requereixen una clau d'API creada a El meu compte → Credencials d'API. La clau identifica el teu compte: els documents que creïs són teus i consumeixen el teu pla.

Authorization: Bearer pdfa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Si el teu entorn no permet enviar la capçalera Authorization, pots fer servir X-Api-Key: pdfa_…. El paràmetre ?api_key= també funciona, però no és recomanable (queda als registres del servidor).

• La clau només es mostra una vegada, en crear-la: desa-la com una contrasenya.
• Fes servir una clau per integració i revoca la que ja no facis servir; la revocació és immediata.
• No hi ha sessió ni cookies: cada petició és independent.
• Fes servir HTTPS en producció perquè la clau no viatgi mai en clar.

API REST

Mètode	Ruta	Descripció	Clau
GET	/api/v1/ping	Comprovació de vida. No requereix credencial.	no
GET	/api/v1/account	Pla contractat, límits i consum del mes.	sí
GET	/api/v1/documents	Llista els teus documents. Paràmetres: page, per_page, type, status.	sí
POST	/api/v1/documents	Puja un PDF i l'encua (type=audit|conversion). Retorna l'id amb què es consulta l'estat. Respon 202 Accepted.	sí
GET	/api/v1/documents/{id}	Estat del processament: queued, processing, done o error, amb avenç i nota.	sí
PUT	/api/v1/documents/{id}	Actualitza les metadades del document (filename).	sí
DELETE	/api/v1/documents/{id}	Elimina el document complet: original, PDF/A i informe. Irreversible.	sí
GET	/api/v1/documents/{id}/report	Informe d'accessibilitat complet (auditoria + conversió). Paràmetres: include_findings=0|1, max_findings.	sí
GET	/api/v1/documents/{id}/audit	Només el resultat de l'auditoria de l'original.	sí
POST	/api/v1/documents/{id}/audit	Torna a auditar l'original (per exemple, després d'un canvi de criteris). 202 Accepted.	sí
GET	/api/v1/documents/{id}/conversion	Estat i resultat de la conversió: not_requested, processing o done.	sí
POST	/api/v1/documents/{id}/conversion	Encua una conversió NOVA del document. 409 si ja n'hi ha una en curs.	sí
PUT	/api/v1/documents/{id}/conversion	Assegura la conversió: idempotent, no duplica la feina ni la quota. És la indicada si la teva integració reintenta.	sí
DELETE	/api/v1/documents/{id}/conversion	Esborra només el PDF/A generat; conserva l'original i l'auditoria.	sí
GET	/api/v1/documents/{id}/file/{original|pdfa}	Descarrega el PDF triat (application/pdf).	sí
POST	/mcp	Servidor MCP (JSON-RPC 2.0). Té la seva pròpia pàgina de documentació.	sí

1. Pujar un document

Tres maneres d'enviar el PDF: multipart amb el camp file (recomanada per a fitxers grans), JSON amb file_base64 o file_url, o el PDF cru al cos.

# multipart (auditoria)
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 amb URL (conversió a PDF/A accessible)
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 l'estat amb l'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"
  }
}

Sondeja cada 5-10 s. Una auditoria sol trigar entre 10 i 60 s; una conversió completa, entre 1 i 5 min segons la mida i el nombre d'imatges.

3. Informe i descàrrega

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

# PDF/A accessible
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 document ja pujat

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

5. Un verb, una acció

Cada combinació de ruta + verb és una acció diferent. En particular: POST /documents/{id}/conversion encua una conversió nova i falla amb 409 si ja n'hi ha una en marxa, mentre que PUT sobre la mateixa ruta és idempotent (si el PDF/A ja existeix, o ja s'està generant, no repeteix la feina ni torna a consumir quota): és la que convé fer servir en integracions que reintenten. DELETE /documents/{id}/conversion esborra només el PDF/A generat i conserva l'original i la seva auditoria; DELETE /documents/{id} ho esborra tot.

Estructura de l'informe

La nota global és la mitjana de les tres dimensions d'accessibilitat. PDF/UA es valida amb un validador de conformitat automàtic (autoritatiu); WCAG i EAA s'avaluen sobre els fets del document i les regles PDF/UA incomplertes.

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

Estats d'un document

Estat	Significat
queued	Acceptat i esperant el treballador de la cua.
processing	En marxa. progress_pct i step indiquen en quina fase és.
done	Acabat: ja hi ha informe i, si era una conversió, PDF/A descarregable.
error	Ha fallat; el camp error explica per què. Es reintenta automàticament fins a 3 vegades abans de donar-se per vençut.

Límits i quotes

Límit	Valor
Peticions per minut i clau	120
Documents per hora i clau	60
Mida màxima de pujada (servidor)	128 MB
Mida màxima a file_base64	24 MB · per sobre, fes servir multipart o file_url
Auditoria gratuïta	fins a 100 MB per document
Conversions	segons el teu pla (mida per document i nombre al mes)

El consum del mes es compta en donar d'alta cada conversió i queda registrat de manera permanent: esborrar un document no retorna quota. En superar la freqüència reps 429 amb la capçalera Retry-After. Si el pla no cobreix una conversió, reps 402 quota_exceeded: l'auditoria continua estant disponible gratis. Consulta el teu consum en qualsevol moment amb GET /api/v1/account o l'eina get_account.

Errors

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

Codi	HTTP	Quan
unauthorized	401	Falta la clau, o és invàlida, revocada o caducada.
quota_exceeded	402	El pla no permet aquesta conversió (mida per document, límit mensual o conversions gratuïtes exhaurides).
email_not_verified	403	El compte no ha verificat el seu email.
plan_required	403	El pla contractat no inclou l'accés a l'API ni a l'MCP (s'inclou a partir del pla Business). El camp required_plan de la resposta indica el pla necessari.
not_found	404	L'id no existeix al teu compte (o la ruta no existeix).
method_not_allowed	405	Aquest verb no està permès en aquesta ruta; la capçalera Allow indica els que sí.
already_running	409	Ja hi ha una feina d'aquest tipus en marxa per a aquest document (fes servir PUT si vols una crida idempotent).
report_not_ready	409	El document encara no ha acabat de processar-se.
invalid_request	422	Paràmetres incorrectes: el fitxer no és un PDF, falta el contingut, tipus desconegut…
too_many_requests	429	S'ha superat el límit de freqüència. Reintenta segons Retry-After.
internal_error	500	Error inesperat del servidor. Si persisteix, escriu-nos.
api_disabled	503	L'API està temporalment desactivada.

Retenció i privacitat

• Els teus PDF no són mai públics: només se serveixen autenticats i només al compte propietari.
• Els documents es conserven 30 dies i després s'eliminen automàticament (original, PDF/A i informe). De cada alta i cada esborrat en queda un registre amb la data (sense el contingut del document), que és el que sosté el recompte del teu pla i el teu historial. Pots esborrar-los abans amb DELETE /api/v1/documents/{id} o delete_document.
• La conversió genera automàticament les metadades i la descripció de les imatges; el contingut dels teus documents no es fa servir per entrenar models.
• Consulta l'avís de privacitat i les condicions.