Skip to content

PDFCLOUD-6572 Add ZUGFeRD PDF validation - #58

Merged
datalogics-kam merged 16 commits into
mainfrom
pdfcloud-6572-add-zugferd-pdf-validation
Nov 13, 2026
Merged

datalogics-kam merged 16 commits into
mainfrom
pdfcloud-6572-add-zugferd-pdf-validation

Conversation

@datalogics-tsmith

@datalogics-tsmith datalogics-tsmith commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

PDFCLOUD-6572

Why this change

The Python SDK does not expose pdfRest's ZUGFeRD validation operation, so callers cannot use the typed clients to verify an existing ZUGFeRD or Factur-X PDF. This adds a supported way to check package structure, embedded invoice XML, visible-content consistency, and PDF/A-3 conformance before accepting or distributing an electronic invoice.

What changed (high level)

New synchronous and asynchronous validate_zugferd_pdf helpers accept an uploaded PDF resource and return a typed validation response. A dedicated Pydantic payload model owns resource validation and wire serialization, while public response models preserve status, content-match results, findings, and free-tier notices with forward-compatible handling of additional response fields.

The change also adds focused unit coverage, live endpoint coverage, creation-to-validation live coverage, a runnable example, and API documentation. The branch has been refreshed against main after #57 merged, so the final diff contains only validation work and uses the split ZUGFeRD creation helpers introduced there.

Behavior changes

Callers can submit one uploaded PDF and receive its overall VALID or INVALID status, independent PDF/A result, content-match status, input resource metadata, and detailed findings. Non-PDF inputs and multiple resources fail locally before transport. Free-tier responses with redacted comparison details remain parseable through the typed models.

The live suites verify validation of default XML-created invoices, font-rendered invoices, and PDFs regenerated with allow_regeneration=True. The API is additive and does not change existing helper behavior.

Validation

The focused ZUGFeRD creation and validation unit suites passed all 501 tests. The complete non-live Nox matrix passed on Python 3.10–3.14 with 3,471 tests and 10 expected skips per interpreter. The client-class function coverage gate passed. Ruff formatting and linting passed, and basedpyright reported zero errors.

The focused validation endpoint suite passed all 6 sync and async cases against the local service, including default creation-to-validation, invalid-document reporting, and invalid resource IDs. The restored creation-to-validation scenarios passed all 8 focused sync and async cases, covering three requested font resources and mismatched-PDF regeneration. GitHub Actions was triggered from the main repository branch after the review-fix push.

Risks and follow-ups

PR #57 is merged and this branch now includes current main; GitHub reports the PR as mergeable. Demo-tier deployments can return DEMO_REDACTED for content comparison details, but callers still receive a parseable response and the overall validation status. Required review and the remaining CI jobs must complete before merge.

- Add typed rendering options for invoice appearance and localization.
- Validate uploaded resources, color channels, fonts, and regeneration.
- Serialize the public input shape into the pdfRest wire contract.

Assisted-by: Codex
- Add synchronous and asynchronous helpers for uploaded invoice XML.
- Support optional PDFs, logos, rendering controls, and request options.
- Cover serialization, validation, response mapping, and both transports.

Assisted-by: Codex
- Exercise every closed rendering option through both client transports.
- Verify regenerated PDFs, response metadata, and server-side rejection.
- Add a deterministic minimum-profile invoice fixture.

Assisted-by: Codex
- Add a standalone typed example with a deterministic invoice fixture.
- Verify the generated PDF and print useful response metadata.
- Link the helper from the API guide and example inventories.

Assisted-by: Codex
- Compose page ranges from typed ascending selections and reject invalid
  combinations before transport.
- Add deterministic sync and async annotation assertions with a printable
  PDF fixture.

Assisted-by: Codex
- Validate a single uploaded PDF resource before request serialization.
- Model validation findings and response status fields returned by pdfRest.
- Export the public response models for typed client consumers.

Assisted-by: Codex
- Send uploaded PDF resource IDs to the validation endpoint.
- Return typed results from synchronous and asynchronous clients.
- Preserve request customization and timeout support.

Assisted-by: Codex
- Verify payload serialization and local resource validation.
- Exercise response literals, aliases, findings, and demo redactions.
- Assert sync and async request customization and transport behavior.

Assisted-by: Codex
- Exercise valid and invalid validation requests through both clients.
- Confirm created and regenerated invoices pass validation and PDF/A checks.
- Accept confirmed and demo-redacted content comparison results.

Assisted-by: Codex
- Create a deterministic invoice before validating its conformance.
- Display typed status, PDF/A, content-match, and finding details.
- Add the workflow to the runnable example inventory.

Assisted-by: Codex
- Link the validation helper from the electronic invoice API guide.
- Describe package, content, and PDF/A conformance validation.

Assisted-by: Codex
@netlify

netlify Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for pdfrest-python ready!

Name Link
🔨 Latest commit a090e2a
🔍 Latest deploy log https://app.netlify.com/projects/pdfrest-python/deploys/6af77155d7f28c7e2a3fae65
😎 Deploy Preview https://deploy-preview-58--pdfrest-python.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@datalogics-kam datalogics-kam left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed only PR #58's incremental changes over PR #57 (7d951b6 to 02cb915), excluding the inherited creation implementation.

Requesting changes for the two inline test-coverage findings: add a real nonconforming-document validation case to the live suite, and make mocked response scenarios and assertions match across the synchronous and asynchronous clients. No runtime or CI regression was found.

Validation passed: 26 focused unit tests, 16 focused live tests, the Python 3.10–3.14 non-live Nox matrix (3,257 passed and 10 expected skips per interpreter), all class-coverage gates, Ruff formatting/lint, and basedpyright. Exploratory validation of the existing report.pdf fixture returned INVALID with pdfa=false through both clients; please preserve that behavior in regression tests.

Comment thread tests/test_validate_zugferd_pdf.py Resolved

@datalogics-kam datalogics-kam left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Follow-up to the existing review, scoped to the validation changes over PR #57 at the unchanged head 02cb915.

The existing findings remain recorded there. This review adds only the uncovered empty-resource-list boundary described inline; please add that regression coverage before merging.

No source files changed and no new runtime defect was found. Tests were not rerun for this posting step because the head is unchanged from the completed audit.

Comment thread tests/test_validate_zugferd_pdf.py Resolved
- Verify INVALID report.pdf responses live through both clients.
- Match valid and demo-redacted response assertions across transports.
- Cover empty resource-list rejection before request execution.

Assisted-by: Codex
@datalogics-kam

Copy link
Copy Markdown
Contributor

This will be approved once #58 is merged.

Thanks!

@datalogics-kam

Copy link
Copy Markdown
Contributor

@datalogics-tsmith This needs a merge or rebase with conflict resolution now that #58 is merged. Probably also a minor version bump.

- Bring the branch up to date with the merged ZUGFeRD creation API and
  current repository changes.
- Preserve the validation helper, response models, example, and tests
  against the split creation helpers.

Assisted-by: Codex
- Advance project metadata from 1.5.0 to 1.6.0.
- Keep the locked editable package version synchronized.

Assisted-by: Codex
- Validate rendered invoices through both client transports.
- Verify regenerated replacement PDFs remain valid and PDF/A conformant.

Assisted-by: Codex

@datalogics-kam datalogics-kam left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The only outstanding thing was the merge fixups, and that's been fixed up.

@datalogics-kam
datalogics-kam merged commit 63984f9 into main Nov 13, 2026
19 checks passed
@datalogics-kam
datalogics-kam deleted the pdfcloud-6572-add-zugferd-pdf-validation branch November 13, 2026 20:33

This branch was previously deployed

1 inactive deployment
ci-live — a090e2a5 Deployed Nov 13, 2026 by datalogics-tsmith via Examples (Python 3.14) #626
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants