Finance API V1 and V2

The Ironfang Finance API has two versions that run side by side. V1, under /finance/v1, is unchanged: its clients keep their Peppol shapes, and it never returns a V2 result. V2, under /finance/v2, validates more families and formats and reports exactly what was checked. Nothing has to move: a V1 integration keeps working, and V2 is where the other families are.

Which API serves what

GET /finance/v2/einvoices/rulesets lists exactly which family, variant, syntax, document type and scope each active V2 release covers; nothing else is supported. The family guides say more: XRechnung and ZUGFeRD / Factur-X.

Requests

Both versions take the document as the request body, choosing with query parameters, or as multipart/form-data with one document part and an optional options part holding the same choices as JSON. Query parameters are not read for multipart requests, and an unknown or repeated parameter or part is 400 malformed_request in both.

Results

A V1 result has the schema financewolf/einvoice/validation-result/v1, a V2 result ironfang/finance/einvoice/validation-result/v2. Both say outcome valid or invalid for a completed validation, decided by the fatal findings alone; anything that stopped a verdict is a Problem with outcome: indeterminate and nothing charged, in both. The fields that differ:

operation_id, status, counts, findings_summary, timing and usage are in both. counts in V2 also counts information findings.

Findings

In both, message is one of Ironfang's fixed messages: the official rule texts are not repeated, because they can carry invoice values. rule_id is the official identifier, unchanged.

Retained results

GET /finance/v2/einvoices/results lists validations and generations made through V1 and validations made through V2 together, each saying which API made it (api_version), the schema of its retained document (result_schema) and its family, with filters on each. GET /finance/v2/einvoices/results/{id} returns any of them in the schema it was made under, and DELETE erases either. V1's own list shows only V1 results, and reading a V2 result through V1 is 404: a V2 result is not a document V1's schema describes. Results are kept for 30 days in both.

Webhook events and deliveries

A finished operation queues one event, delivered to every enabled webhook or S3 destination and signed the same way whichever API made it. An operation made through V1 sends financewolf/einvoice/event/v1, whose result_url is under /finance/v1. An operation made through V2 sends ironfang/finance/einvoice/event/v2, whose result_url is under /finance/v2 and whose data also carries the family, variant and scope the result was made under. A receiver that takes both should branch on schema.

GET /finance/v2/einvoices/deliveries lists deliveries of both kinds, each with its api_version and its event as queued, and can filter on api_version. POST /finance/v2/einvoices/deliveries/{id}/retry retries a failed one of either kind. V1's delivery list, read and retry see only deliveries of V1 events.

Jobs and batches

POST /finance/v2/einvoices/jobs queues one V2 validation and POST /finance/v2/einvoices/batches 1 to 100 together, all or none. Each job carries document_base64, its media_type and the synchronous options. A document synchronous validation would refuse is refused on acceptance with the same Problem, and nothing is queued or charged. A job's result, usage and event are exactly a synchronous validation's.

V1 and V2 jobs share each organisation's queue: at most 100 unfinished jobs and 25 MiB of their documents, held encrypted until they finish, at most 24 hours. V1's job and batch lists show only V1 work; V2's show both.

What both share

• Ironfang platform API keys (Authorization: Bearer) with the same scopes: finance:einvoices:write to validate, finance:einvoices:read to read.
• Anonymous validation without a key: nothing is stored, and tighter rate limits apply.
• An optional Idempotency-Key on authenticated requests: the same key and request return the first result and are not charged again. V2 keys are V2's own, apart from V1's.
• Problems as RFC 9457 application/problem+json; branch on code.
• One Finance allowance: a completed validation through either API is one operation.
• Uploaded documents are not stored by synchronous validation.

The contracts: V1 and V2.

Example

No single document goes through both APIs today, because Peppol has no V2 release. The request mechanics are the same, so this pairs a V1 Peppol call with a V2 XRechnung call, and adds the PDF only V2 takes.

# V1: a Peppol BIS Billing 3 invoice (UBL). Peppol is validated through V1.
curl --fail-with-body --silent --show-error \
  "https://api.ironfang.uk/finance/v1/einvoices/validate?ruleset=latest&profile=peppol-bis-billing-3" \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: peppol-invoice-0001" \
  --data-binary @peppol-invoice.xml

# V2: an XRechnung invoice (UBL or CII). The same request mechanics,
# with the family named instead of a profile.
curl --fail-with-body --silent --show-error \
  "https://api.ironfang.uk/finance/v2/einvoices/validate?ruleset=latest&family=xrechnung" \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: xrechnung-invoice-0001" \
  --data-binary @xrechnung-invoice.xml

# V2: a ZUGFeRD / Factur-X hybrid PDF. Only V2 takes a PDF.
curl --fail-with-body --silent --show-error \
  "https://api.ironfang.uk/finance/v2/einvoices/validate?family=zugferd-facturx" \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @zugferd-invoice.pdf