Validate, understand, fix

What the validation pipeline checks

UBL is the XML document syntax. EN 16931 defines the core electronic invoice semantics, and Peppol BIS Billing adds its usage rules. Ironfang Finance sends the supplied XML bytes to its self-hosted Java service. PHIVE runs the registered upstream validation artefacts, using Saxon for their XSLT checks. Ironfang Finance returns structured findings with the original rule identifiers and validation layers.

1. XML well-formedness: the document must parse safely. Malformed XML is distinct from a business-rule failure.
2. UBL schema: the supported Invoice or CreditNote must have the structure and data types defined by its UBL schema.
3. EN 16931: upstream artefacts check the applicable semantic and calculation rules.
4. Peppol: upstream BIS Billing artefacts check the applicable profile and usage rules.
5. Service failures: timeouts, unavailable validators and internal failures are indeterminate. They do not establish whether the invoice is valid.

A failed prerequisite can leave later layers skipped. Warnings remain visible even when the overall verdict is valid. PHIVE and the official artefacts determine validity; rule explanations do not alter the verdict. Validation never silently repairs your XML.

Which versions checked my document?

Each result names its exact ruleset and engine image. The live ruleset registry lists VESIDs, document types, specification releases, checksums and lifecycle dates. Newer validators also provide a runtime object with the validator, PHIVE, phive-rules, phive-rules-peppol and Saxon versions, the upstream VES name and deprecation status.

Runtime metadata is a verified observation at observed_at, not a live readiness guarantee. Older retained validators may omit it. Library versions and Peppol specification releases are separate identities; an upstream validity date is included only when PHIVE supplies one. The registry lifecycle label sendable selects the active release for latest; it does not mean Ironfang Finance can send an invoice.

Generation uses the final XML bytes

The generator accepts structured generation-input/v1 JSON and creates UBL. The exact final byte array must pass the selected production validator before Ironfang Finance returns it, base64 encoded with its SHA-256. A generation failure returns no successful invoice artifact. Fix rejected input in your source system; Ironfang Finance does not bypass upstream rules to make an invoice pass.

Durable API work

Job and batch endpoints are available with a Ironfang Finance API key. They accept validation or generation with a Ironfang Finance write key, return a job ID for polling, and preserve the selected ruleset across retries. Read keys retrieve metadata and completed results. Cancellation preserves work that already completed. A completed validation can be valid or invalid; service failures remain indeterminate and uncharged.

The OpenAPI contract describes request limits, idempotency and cancellation. Durable jobs use the same PHIVE path and do not transmit invoices or add legal certification.

Your first validation

1. Open the free validator and try the sample or upload XML, up to 5 MiB.
2. Read the verdict and each layer: XML, UBL schema, EN 16931 and Peppol. A service failure is not an invalid invoice.
3. Follow a rule explanation where available, fix your source document and validate again.
4. Download JSON and an unsigned readable report. Open the report to print or save it as a PDF.

Rule explanations

• BR-CO-10: Line amounts do not add up

  The document-level line total must match the sum of the individual line net amounts.

• BR-CO-13: The total before VAT is inconsistent

  The total before VAT starts from the line total, subtracts document allowances and adds document charges.

• BR-01: The specification identifier is missing

  Invoice and CreditNote documents need a non-empty CustomizationID identifying their specification.

• PEPPOL-EN16931-R004: Check the billing specification identifier

  This rule checks the Peppol Billing identifier prefix and rejects a double-colon sequence in the identifier.

• PEPPOL-EN16931-R020: Add the seller electronic address

  The seller Party must include an EndpointID. This rule checks its presence; other rules check its scheme and value.

• FW-XML-001: The XML could not be read safely

  The document has malformed XML, an unsupported encoding or a prohibited XML construct. No later validation layer can run until this is fixed.

This initial collection covers the failures in our reviewed validation fixtures. Other rules retain their engine finding and identifier; we do not guess at a fix.

Saved results and privacy

Anonymous XML and results are processed transiently. When signed in or using an API key, result JSON and findings are stored for 30 days, and you can delete them sooner. Synchronous validation does not retain uploaded XML. Durable API jobs, when enabled, retain encrypted XML or generation input until completion, cancellation or 24-hour expiry cleanup. Backups follow their own retention policy. Authenticated generated XML is retained with its result for 30 days. Downloaded copies stay under your control.

After deletion or expiry, a small operation record retains hashes, ruleset, outcome, timestamps and usage metadata until organisation erasure. This prevents an old retry from running or charging again. Reusing its Idempotency-Key returns 410 result_gone; request a new validation with a new key only when intended.

JSON generation and four runnable quickstarts - Signed reports and verification

Use the API

POST XML to /financewolf/v1/einvoices/validate. Authenticated results are listed at /financewolf/v1/einvoices/results; GET or DELETE a result by operation ID. Read requires financewolf:einvoices:read; validation, generation and deletion require financewolf:einvoices:write. Authenticated ruleset reads require financewolf:einvoices:rulesets:read. Send the platform API key as a Bearer token; Ironfang Finance has no MCP tools or OAuth delegation today.

OpenAPI contract - API key and integration examples - Privacy policy

Run in PostmanView the collection

The collection is generated from the OpenAPI contract and opens with three requests that need no credential: list the rulesets, validate a sample invoice and generate one from JSON. You can also download it. Keep API keys in a private environment or vault and select the invoice files you intend to send.

Availability

SDKs, CLI and GitHub Action

Python and TypeScript validation SDKs, a Python CLI and the official GitHub Action are publicly released as v0.1.0. They cover synchronous Invoice and CreditNote validation against a selected ruleset, with distinct outcomes for valid documents, invalid documents and service failures. Find installation instructions and the pinned public Action reference in the integration guide. Install TypeScript from npm or download the Python release from GitHub.

Signed webhooks and artifact delivery

Authenticated accounts can configure signed event webhooks and S3-compatible artifact delivery as separate destinations. Each destination has its own retry history; delivery failures do not change a document verdict or charge for another validation. Verify webhook signatures and deduplicate event identifiers at your receiver.

S3 qualification covers SeaweedFS 4.46 in the tested configuration; other providers need their own checks. PDFs and signed report ZIPs are not automatically exported. Delivery to a customer endpoint or bucket does not prove recipient acceptance, accounting ingestion or payment, and does not transmit the invoice over Peppol.

Free and paid plans

Free accounts include 250 validations per UTC calendar month, with no card required. Authenticated generation requires a paid Build, Pro or Platform subscription. Paid plans share one allowance between validation and generation, following the monthly subscription period. Compare the current prices and allowances.

Paid plans serve UK and EU businesses, including sole traders. UK VAT numbers are optional. EU automatic checkout requires a verified VAT number and matching business details; businesses without a VAT number, or with verified details needing review, require approval before payment. Enter your business details, request review and choose a plan in the billing portal.

One completed validation counts even if it finds invoice errors; one successful generation counts once. Unfinished work reserves allowance. Downloads and idempotent replays add no usage. Malformed requests and service failures do not use allowance. The cap stops new account operations until capacity is available, your period renews or you upgrade; there are no automatic overage charges.

The anonymous validator and JSON playground remain free with request and rate limits. Anonymous use has no saved history or account allowance. Ironfang Finance subscriptions, payment details and invoice history are separate from Ironfang Render and Ironfang Audit.

Request limits

XML and generation JSON are limited to 5 MiB. Validation has a 10-second deadline and returns at most 1,000 inline findings. Inspect finding counts and truncation indicators; a shortened finding list is not a complete audit. Rate limits return HTTP 429; respect Retry-After when provided. See the OpenAPI contract for input and field limits.

What a valid result does not establish

• It does not transmit the invoice through the Peppol network.
• It does not make Ironfang a Peppol Access Point.
• It does not register a Peppol participant or prove its registration.
• It does not certify legal or tax compliance.
• It does not guarantee that a recipient will accept, book or pay the invoice.

A valid result means that these bytes passed the selected supported ruleset. Recipient requirements, business context and legal or tax questions require separate review.