Changelog

What's new

Every change to the Flowie Exchange API, newest first. Additive changes land continuously under /v1/; deprecations are announced six months in advance and flagged with a Sunset response header.

How to read this

New additive — always safe to adopt.
Changed behavior refined — read carefully.
Deprec sunset date announced.
Break only ever in a new major (/v2/…).
Fix bug fix.

v3.1.1 — Belgium HERMES retired

2026-05-04

Belgium's regulator-side reporting hub HERMES was decommissioned by FPS Finance on 2025-12-31 (consultation-only access expired 2026-03-31). Flowie's HermesAdapter and the BE branch of the compliance dispatcher have been removed. Belgian invoices are now pure Peppol — the delivery itself is the compliance event.

Changed

No compliance.reported events fire for Belgian invoices. If your webhook router branches on data.platform == "HERMES", drop the branch — see migration guide for the full diff.

Changed

BE-CIUS validation now surfaces synchronously: POST /v1/documents/send returns 422 with the BE-CIUS schematron rule code in error.details[].code + the failing XPath. Replaces the old deferred compliance.reported.failed + HER-* path. Same checks, faster feedback.

Deprec

HERMES_REPORT_URL / HERMES_REPORT_TOKEN environment variables are no longer read. simulateCompliance: "reject_HER_001" sandbox value is also retired. Historical compliance_reports rows with platform=HERMES are retained for audit; new ones won't be created.

Docs

Belgium compliance page (compliance/be.html) rewritten with sourced timeline (2024-02-06 → 2028-01-01), 4-corner Peppol diagram, end-to-end send example, lifecycle table comparing FR/IT/BE, BR-BE-* error catalog, sandbox tests, and HERMES → Peppol migration table.

v3.1.0 — AI agents & multi-org

2026-05-03

First-class Model Context Protocol surface for AI agents, plus organization switching for JWT users in multiple orgs.

New

MCP servers. /exchange/mcp (curated, 34 tools across Documents / Directory / Companies / Lifecycle / Compliance / Partners) and /exchange/mcp/full (every documented operation, 94 tools). Same Bearer token as REST, same quotas, same sandbox. Full guide →

New

POST /v1/documents/send accepts type: "event" — pure audit-trail records, persisted as documents but never routed over Peppol. Useful for ERP-side notifications you want to keep alongside real invoices.

New

Organization switching for multi-org JWT users: switch the active organization without re-login. Existing flw_* API keys are unaffected (single-tenant by design).

Changed

MCP transport upgraded from legacy SSE to streamable-HTTP (MCP spec 2025-06-18). Reconfigure existing clients as "transport": "streamable-http".

v3.0.0 — Unified surface

2026-04-13

First stable cut of the Exchange API. The legacy /api/… endpoints continue to work but are deprecated.

New

Resource-oriented surface under /v1/: companies, documents, partners, webhooks, events, compliance, platform, api-keys, stats.

New

Lifecycle state machine with auto-reporting to PPF (FR), SDI (IT), HERMES (BE).

New

Idempotency-Key is accepted on every POST with a 24h TTL.

New

Cursor-based pagination everywhere (limit, cursor, hasMore).

New

Platform keys with X-Flowie-Company for tenant-scoped calls.

New

AFNOR XP Z12-013 adapter under /afnor/flow-service and /afnor/directory-service.

New

cXML PunchOut callback at /document/callback.

Deprec

All /api/… endpoints. Sunset date: 2027-04-01. Mapping table in the migration guide.

v2.9.0

2026-03-28

New

POST /v1/documents/search accepts compound AND/OR/NOT filter trees.

New

Webhook deliveries now include X-Flowie-Attempt header.

Changed

Directory verify latency dropped from p95 420ms → 90ms via SMP cache.

v2.8.0

2026-03-10

New

AI tag recommendation: POST /v1/categorization/objects/tags/auto.

New

Structured document view at GET /v1/documents/{id}/structured — all scalars flattened, ready for warehouses.

Fix

VAT normalization now strips all whitespace (was only stripping leading/trailing).

v2.7.0

2026-02-14

New

Company identifier resolution: vat: and peppol: prefixes accepted in any {company_id} / {partner_id} path param.

New

Batch lifecycle update: POST /v1/documents/lifecycle/batch, up to 500 per call.

Changed

HERMES (BE) reporting enabled by default for newly created BE companies. Existing companies untouched.

v2.6.0

2026-01-22

New

Circuit-breaker visibility at GET /health/readiness. Per-upstream state.

New

Webhook secret rotation: PATCH /v1/webhooks/{id} with {"rotateSecret": true}. Old secret stays valid for 60 minutes.

Fix

Idempotency cache correctly distinguishes requests differing only in a query param.

v2.5.0

2025-12-05

New

PPF (FR) adapter graduated from beta. Registered PDP status confirmed by DGFiP.

New

ISO 20022 / SEPA export at POST /v1/payments/export/iso20022.

v2.4.0

2025-10-18

New

Events API (/v1/events) — durable twin of every webhook, replayable.

New

Rate-limit headers (X-RateLimit-*) added to every response.

Changed

Free tier rate limit raised from 30 to 60 req/min.