# Flowie Exchange API

> One REST API for sending, receiving, and managing electronic invoices over the Peppol network. Covers 40+ countries; auto-reports lifecycle to France PPF, Italy SDI, and Belgium HERMES; supports white-label / multi-tenant platform integrations.

This file follows the [llms.txt](https://llmstxt.org) standard. It exposes the Flowie Exchange API documentation in a form that is fast and unambiguous for large language models to ingest.

**Base URLs**
- Production: `https://back.p2p-flowie.com`
- Sandbox: `https://back.flowie.ink`

**Versioning**: All endpoints below are under `/v1/`. Breaking changes ship under `/v2/…` with a 12-month deprecation window.

**Authentication**: `Authorization: Bearer <token>` — accepts either a Flowie JWT or an Exchange API key (`flw_live_…`, `flw_plat_live_…`, `flw_wl_live_…`, or their `_test_` variants).

**Get a sandbox key without signup** (rate-limited 120/IP/hr):
`POST https://back.flowie.ink/exchange/v1/sandbox/bootstrap` returns a fresh `flw_test_…` key + a starter sandbox company. Pass `{"keyType": "platform"}` (or `"white_label"`) to mint a platform-typed key (`flw_plat_test_…` / `flw_wl_test_…`) that satisfies the platform-key gate on `/v1/platform/*`.

**Need to act on a real user's account?** Use the OAuth-style consent flow with PKCE — see *AI agents — onboarding* below. The agent shows the user a consent URL, the user approves the requested scopes, the agent gets back a scoped API key.

---

## AI agents — onboarding

If you are an AI agent reading this index, start here. There are exactly two paths to get a working API key:

**Path 1 — Sandbox bootstrap (no human involved).** One POST, no auth, returns a 7-day `flw_test_…` key + a starter sandbox company. Use for prototyping, demos, MCP playgrounds, agent CI:

```
POST https://back.flowie.ink/exchange/v1/sandbox/bootstrap
Content-Type: application/json
{"label": "my-agent"}
```

**Path 2 — OAuth-style consent flow (one-time human approval).** RFC 7636 PKCE, public clients, sandbox-issued keys for v1. Four steps:

1. `POST /v1/oauth/authorize` with `{client_name, scopes, code_challenge, code_challenge_method: "S256", state?}` → returns `{request_id, consent_url, expires_in: 600}`.
2. Show the user the `consent_url`. They sign in if needed, review the scope list, click Approve.
3. Server returns a one-time `auth_code` (5-min TTL) — either rendered on screen for OOB (`urn:ietf:wg:oauth:2.0:oob`) or via a redirect.
4. `POST /v1/oauth/token` with `{grant_type: "authorization_code", code, code_verifier}` → returns `{access_token: "flw_test_…", scopes, expires_in, organization_id, company_id}`.

The PKCE `code_verifier` is a 43-128 char random string the agent keeps secret until step 4. The `code_challenge` is `BASE64URL(SHA256(code_verifier))` with no padding.

**Endpoints:**
- [Agent onboarding guide](https://docs.flowie.ink/agent-onboarding.html): Full walkthrough — sandbox + OAuth, with Claude Desktop / Python / curl recipes.
- [GET /v1/oauth/scopes](https://docs.flowie.ink/agent-onboarding.html#scopes): Public scope catalogue (13 scopes — `send`, `documents.read`, `lifecycle`, `compliance`, etc.). No auth.
- [POST /v1/oauth/authorize](https://docs.flowie.ink/agent-onboarding.html#oauth): Step 1 — register consent intent.
- [POST /v1/oauth/token](https://docs.flowie.ink/agent-onboarding.html#pkce): Step 4 — exchange auth code + PKCE verifier for an API key.
- [POST /v1/sandbox/bootstrap](https://docs.flowie.ink/sandbox.html#keys): Path 1 (no consent needed; sandbox-only).
- [MCP for AI agents](https://docs.flowie.ink/mcp.html): Once you have a key, connect via MCP for native tool calls.

---

## Foundations

- [Introduction](https://docs.flowie.ink/index.html): Landing page with quickstart in 8 languages.
- [API reference](https://docs.flowie.ink/reference.html): Every endpoint, with parameters, request/response schemas, and idiomatic code samples.
- [Data model](https://docs.flowie.ink/data-model.html): Entity-relationship diagram + per-resource field reference.
- [Authentication](https://docs.flowie.ink/reference.html#authentication): JWT vs API key, scopes, key types.
- [Idempotency](https://docs.flowie.ink/reference.html#idempotency): `Idempotency-Key` header, 24h cache, retry semantics.
- [Pagination](https://docs.flowie.ink/reference.html#pagination): Cursor-based, with `limit`, `cursor`, `hasMore`.
- [Rate limits & quotas](https://docs.flowie.ink/reference.html#rate-limits): Per-tier, with `X-RateLimit-*` headers.
- [Errors](https://docs.flowie.ink/errors.html): Every error code with cause and remediation.
- [Versioning](https://docs.flowie.ink/reference.html#versioning): Sunset header policy, additive vs breaking changes.

## Resources (REST)

- [Companies](https://docs.flowie.ink/reference.html#companies): Register a Peppol-capable legal entity. Auto-enrichment, SMP registration. CRUD + resolve, search, join requests.
- [Documents](https://docs.flowie.ink/reference.html#documents): Send, receive, list, search, download (XML/PDF), and tag invoices, credit notes, debit notes, purchase orders.
- [Lifecycle](https://docs.flowie.ink/reference.html#lifecycle): Business-level state machine (`issued → under_review → approved → paid`) with allowed-transition enforcement and auto-compliance reporting.
- [Directory](https://docs.flowie.ink/reference.html#directory): Search the public Peppol directory, lookup any participant, verify reachability before sending.
- [Partners](https://docs.flowie.ink/reference.html#partners): Per-company contact book with default routing settings.
- [Webhooks](https://docs.flowie.ink/reference.html#webhooks): HTTPS subscription endpoints for events. CRUD + secret rotation.
- [Events](https://docs.flowie.ink/reference.html#events): Durable event log + replay endpoint (GET `/v1/events`, POST `/v1/events/{id}/replay`).
- [Compliance](https://docs.flowie.ink/reference.html#compliance): Status & report records for PPF/SDI/HERMES.
- [Stats](https://docs.flowie.ink/reference.html#stats): Per-period usage (sent/received/delivered/failed) by company/country/type.
- [Platform](https://docs.flowie.ink/reference.html#platform): Multi-tenant onboarding, platform-key management, branding, per-tenant usage.
- [API keys](https://docs.flowie.ink/reference.html#api-keys): Self-service create / list / revoke.
- [Categorization](https://docs.flowie.ink/reference.html#categorization): Tag groups + AI suggest.
- [Payments](https://docs.flowie.ink/reference.html#payments): Document payment info, record payment, ISO 20022 / SEPA export.
- [Requests](https://docs.flowie.ink/reference.html#requests): GET `/v1/requests/{requestId}` returns the captured failed request envelope (debug inspector).

## AI agents (MCP)

- [MCP guide](https://docs.flowie.ink/mcp.html): Full Model Context Protocol guide — Claude Desktop / Claude Code / Cursor / Python configs + worked workflows (list, send, mark paid, onboard).
- [MCP curated endpoint](https://docs.flowie.ink/mcp.html#endpoints): `https://back.p2p-flowie.com/exchange/mcp` (prod) / `https://back.flowie.ink/exchange/mcp` (sandbox) — 34 tools across Documents, Directory, Companies, Lifecycle, Compliance, Partners. Streamable-HTTP transport.
- [MCP full endpoint](https://docs.flowie.ink/mcp.html#endpoints): `…/exchange/mcp/full` — every documented FastAPI op (94 tools), including admin / sandbox / AFNOR / platform routes.
- [MCP authentication](https://docs.flowie.ink/mcp.html#auth): Same Bearer token as REST (JWT or `flw_*`); the original Authorization header is forwarded to the underlying handler.
- [MCP tool catalog](https://docs.flowie.ink/mcp.html#tools): Per-operation MCP tools — `send_document`, `list_documents`, `update_lifecycle`, `search_directory`, `verify_recipient`, `resolve_company`, etc.
- [MCP direct HTTP](https://docs.flowie.ink/mcp.html#raw-http): JSON-RPC over HTTP POST — `initialize` → `tools/list` → `tools/call` if you don't want the SDK.

## Sandbox & testing

- [Inbound: ERP webhooks → /v1/documents/send](https://docs.flowie.ink/guides.html#ingest): How to wire Dynamics 365 / SAP / NetSuite / Sage / custom systems as inbound sources. Full payload-shape matrix (json / ubl-xml / file=auto / file=raw) × six document types.
- [Order integrations: Quote → SO → PO → Invoice](https://docs.flowie.ink/guides.html#order-flow): S2P and O2C playbooks with cross-references and three-way matching.
- [Sandbox guide](https://docs.flowie.ink/sandbox.html): Every test scenario as a row.
- [Bootstrap a key](https://docs.flowie.ink/sandbox.html#keys): `POST /v1/sandbox/bootstrap` (no auth, 120/IP/hr).
- [Key types](https://docs.flowie.ink/sandbox.html#key-types): Personal / platform / white-label sandbox keys.
- [Sandbox shortcuts](https://docs.flowie.ink/sandbox.html#sandbox-shortcuts): Per-route table of what's synthesised under sandbox keys.
- [Test VAT registry](https://docs.flowie.ink/sandbox.html#test-vats): Magic VATs (e.g. `BE0000000001` happy, `BE0000000404` not-found).
- [Test Peppol IDs](https://docs.flowie.ink/sandbox.html#test-peppol): `0208:TEST_OK`, `0208:TEST_AP_FAIL`, `0208:TEST_TIMEOUT`, etc.
- [Recipient simulators](https://docs.flowie.ink/sandbox.html#test-recipients): Multi-step lifecycle: `0208:SIM_HAPPY`, `SIM_DISPUTE`, `SIM_PARTIAL`.
- [Force any error](https://docs.flowie.ink/sandbox.html#test-errors): `X-Sandbox-Force-Error` header → forced 400/401/403/404/409/422/429/500/503.
- [Force a rate-limit](https://docs.flowie.ink/sandbox.html#test-rate): `POST /v1/sandbox/rate-limit/exhaust`.
- [Time-travel](https://docs.flowie.ink/sandbox.html#test-clock): `POST /v1/sandbox/clock/advance` (`s|m|h|d|w|y`).
- [Reset](https://docs.flowie.ink/sandbox.html#test-reset): `POST /v1/sandbox/reset` to wipe events/idempotency.
- [Live API playground](https://docs.flowie.ink/playground.html): Browser-side request runner.
- [Request inspector](https://docs.flowie.ink/requests.html): Look up any `requestId` from an error response.
- [Webhook fixtures](https://docs.flowie.ink/fixtures/index.html): Downloadable JSON for every event type.

## Webhooks

- [Webhook cookbook](https://docs.flowie.ink/webhooks.html): Event catalog, payload shape, signing, retries, replay.
- [Event catalog](https://docs.flowie.ink/webhooks.html#events): `document.received`, `document.sent`, `document.delivered`, `document.failed`, `document.updated`, `lifecycle.updated`, `company.smp_registered`, `compliance.reported`, `compliance.reported.failed`.
- [HMAC signing](https://docs.flowie.ink/webhooks.html#signing): `X-Flowie-Signature: t=<unix>,v1=<sha256-hex>` over `t + "." + raw_body`. Reject if `|now - t| > 5min`.
- [Retry schedule](https://docs.flowie.ink/webhooks.html#retries): 8 attempts at 0s / 30s / 2m / 10m / 30m / 2h / 6h / 12h. Auto-pause after 8 consecutive failures.
- [Interactive verifier](https://docs.flowie.ink/webhooks.html#verifier): Browser-side HMAC verification widget.

## Compliance (per country)

- [France · PPF](https://docs.flowie.ink/compliance/fr.html): Flowie is registered PDP `0040`. Mandatory receive 2026-09-01, send 2027-09-01. Required fields, error codes (00025/00043/00058/00104/00200/00306/00500), Service Exécutant, e-reporting timing.
- [Italy · SDI](https://docs.flowie.ink/compliance/it.html): Mandatory since 2019. Codice Destinatario routing, FatturaPA XML, intermediario flow, 10-year retention. Error codes 00200/00306/00311/00400/00404/00417/00471.
- [Belgium · HERMES](https://docs.flowie.ink/compliance/be.html): B2B mandate 2026-01-01. BE BIS profile, Mercurius for B2G (federal OVO numbers), OGM-VCS payment reference. Error codes HER-001/002/007, MERC-201, BR-BE-01.

## Guides

- [Sending invoices](https://docs.flowie.ink/guides.html#send-invoice): Register sender → verify recipient → send → listen for `document.delivered`.
- [Receiving invoices](https://docs.flowie.ink/guides.html#receive): Subscribe webhook → verify HMAC → fetch structured view → advance lifecycle.
- [Tracking lifecycle](https://docs.flowie.ink/guides.html#lifecycle-flow): Allowed-state map; mark paid example with auto-compliance.
- [Building a white-label platform](https://docs.flowie.ink/guides.html#white-label): `flw_plat_live_…` keys + `X-Flowie-Company`. Branding, tenant-scoped webhooks.
- [FR · IT · BE compliance](https://docs.flowie.ink/guides.html#compliance): Cross-border concerns, deadline matrix, opt-out flags.
- [Sandbox testing](https://docs.flowie.ink/guides.html#sandbox): Magic identifiers, replay, ngrok loop.
- [Going live checklist](https://docs.flowie.ink/guides.html#go-live): 10-point pre-launch.
- [Migrating from v2](https://docs.flowie.ink/guides.html#migration): Legacy `/api/…` → `/v1/…` mapping table.
- [Platform onboarding kit](https://docs.flowie.ink/onboarding-kit.html): WorkOS-style 6-step walkthrough, scale to 100, billing, observability, offboarding, production checklist.

## Operational

- [Changelog](https://docs.flowie.ink/changelog.html): All API changes — `new`, `changed`, `deprec`, `break`, `fix`. Releases since 2025-10.
- [Status page](https://status.flowie.ink): Real-time uptime (external).
- [OpenAPI spec](https://docs.flowie.ink/openapi.json): Machine-readable contract (OpenAPI 3.1).

## Optional

- [Markdown exports](https://docs.flowie.ink/llms-full.txt): Full content of every doc page concatenated for ingestion.
- [Per-page markdown](https://docs.flowie.ink/llms/): One `.md` per HTML page — `index.md`, `reference.md`, `sandbox.md`, etc.
- [Webhook payload fixtures](https://docs.flowie.ink/fixtures/): One JSON file per event type, schema-stable across patch releases.
- [AFNOR XP Z12-013 adapter](https://docs.flowie.ink/reference.html#afnor): French PDP-interoperability surface under `/afnor/flow-service` and `/afnor/directory-service`.
- [cXML PunchOut callback](https://docs.flowie.ink/reference.html#punchout): `/document/callback` for SAP Ariba / Coupa / Ivalua.