Core concepts

Verification

Inspect existing signatures before editing, then cryptographically verify a signed PDF and retrieve a sealed proof.

Inspect

POST /api/verification/inspect reads PDF structure (multipart file, optional password) and tells you whether signatures already exist. It does not validate crypto. Use it before adding text, dates, or QR codes that would invalidate existing signatures. Requires a Bearer token.

json

{
  "schema_version": "1.0",
  "filename": "doc.pdf",
  "page_count": 2,
  "signed": true,
  "signatures_count": 1,
  "has_document_timestamp": false
}

Verify

POST /api/verification/verify runs PAdES / CAdES checks (certificate chain, optional TSA, optional OCSP/CRL).

Multipart : file, password optional, options optional as a JSON string
JSON : document_url (or url) plus options. URL mode requires a Bearer token — anonymous URL fetch is rejected (SSRF).

json

{
  "document_url": "https://files.acme.test/signed.pdf",
  "options": {
    "generate_proof": true,
    "check_revocation": false,
    "revocation_mode": "soft-fail",
    "decrypt_dkbsign_data": true,
    "include_raw_certificates": false
  }
}

History is GET /api/verification/verifications with page, page_size (1–100), verdict, document_sha256, date_from, date_to.

Verdicts

Verdict	Meaning
`VALID`	Integrity and trust checks passed
`INVALID`	The signature or document failed a check
`INDETERMINATE`	Missing data (no trust anchor, unknown revocation). This is never upgraded to VALID.

The report (schema_version 1.2) includes global_verdict, per-signature signature_verdict, certificate, integrity, timestamp, revocation, optional dkbsign_data, and a proof block when generated.

Proofs

When generate_proof is true (default), fetch GET /api/verification/proofs/{proof_id} or the PDF rendering on .../proofs/{proof_id}/pdf?lang=fr|en. The proof is self-contained: integrity_seal.proof_hash is the SHA-256 of the canonical result object (sorted keys, compact separators, UTF-8).

Errors use this envelope:

json

{ "error": { "code": "INVALID_DOCUMENT", "message": "…", "details": {} } }

Typical codes: INVALID_DOCUMENT, UNSUPPORTED_FORMAT, URL_FETCH_FAILED, FILE_TOO_LARGE, PROOF_NOT_FOUND, RATE_LIMITED, UNAUTHORIZED.