Test the entire API without sending a real invoice

Every endpoint, every webhook, every regulatory platform has a deterministic sandbox counterpart. Use the rows below to trigger any outcome you need to test — the recipient is unreachable, PPF rejects with code 00058, the rate-limit kicks in, the lifecycle reaches paid after a 30-second delay. No real Peppol traffic is generated.

Base URLs

Test API keys

curl -X POST https://back.flowie.ink/exchange/v1/sandbox/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"label":"my-laptop"}'

Key types — personal, platform, white-label

By default /v1/sandbox/bootstrap mints a personal key (prefix flw_test_) that behaves like a regular tenant integration. Pass "keyType": "platform" or "white_label" to mint a multi-tenant key that satisfies the platform-key gate on /v1/platform/*:

curl -X POST https://back.flowie.ink/exchange/v1/sandbox/bootstrap \
  -H "Content-Type: application/json" \
  -d '{"label":"my-platform","keyType":"platform"}'

If you already have a Flowie dashboard JWT, you can also create longer-lived keys explicitly:

curl -X POST https://back.flowie.ink/exchange/v1/api-keys \
  -H "Authorization: Bearer $FLOWIE_DASHBOARD_JWT" \
  -d '{"name":"local-dev","scopes":["*"]}'

Or grab one from the dashboard Settings → API keys → New key (test mode). As with live keys, the full string is shown once.

What sandbox synthesises (vs. live infra)

Sandbox keys never reach the live Peppol network, the einvoice-validator, the tag service, the payment service, the request-log store, or org-v2's BOR. Each route either short-circuits to a synthetic response or runs in a memory-only mode so the contract is exercisable without external dependencies. The table below is the canonical list — anything not on it behaves identically to production.

Test VAT numbers

Pass any of these to POST /v1/companies or /companies/resolve to deterministically trigger a behavior.

Test Peppol IDs (recipient side)

End-to-end recipient simulators

Each test Peppol ID below is a fully simulated recipient. Sending to it triggers a full lifecycle including counterparty acks/rejects.

Lifecycle simulators

For your own sent documents, you can advance the lifecycle on demand:

# Force a sandbox document to "paid" right now
curl -X POST …/v1/documents/{doc_id}/lifecycle \
  -H "Authorization: Bearer $TEST_KEY" \
  -d '{
    "status":          "paid",
    "paymentDate":     "2026-04-25",
    "paymentAmount":   2359.50,
    "paymentCurrency": "EUR",
    "paymentReference":"SBX-PAY-001"
  }'

The compliance hooks fire normally — see compliance simulators below.

Compliance platform simulators (PPF / SDI)

To exercise the compliance pipeline, set the company's metadata.simulateCompliance field. The next lifecycle update on any of that company's docs uses the simulated response. Belgium has no regulator-side report (HERMES decommissioned 2025-12-31) — BE invoices skip this pipeline entirely.

# Set the simulator on a sandbox company
curl -X PATCH …/v1/companies/{company_id} \
  -H "Authorization: Bearer $TEST_KEY" \
  -d '{"metadata": {"simulateCompliance": "reject_00058"}}'

Triggering each webhook event

Each row below is a copy-pasteable curl that produces exactly one webhook delivery against your registered sandbox endpoint.

To replay any past event byte-identically:

curl -X POST …/v1/events/{event_id}/replay \
  -H "Authorization: Bearer $TEST_KEY"

Need fixture payloads to seed your tests without hitting the API? See webhook fixtures.

Forcing specific errors

Pass X-Sandbox-Force-Error on any request to make the API return that error code:

curl …/v1/companies \
  -H "Authorization: Bearer $TEST_KEY" \
  -H "X-Sandbox-Force-Error: UPSTREAM_UNAVAILABLE"

Forcing a rate-limit

Sandbox rate-limits are normally generous. To force a 429 right now:

curl -X POST …/v1/sandbox/rate-limit/exhaust \
  -H "Authorization: Bearer $TEST_KEY" \
  -d '{"durationSeconds": 60}'

Every subsequent call returns 429 with a real Retry-After header for the next 60 seconds. Useful for testing your backoff implementation under realistic conditions.

Time-travel

For sandbox companies you can advance the clock to verify deferred behaviors (60-day late payments, 12-month deprecation windows, idempotency cache TTL):

curl -X POST …/v1/sandbox/clock/advance \
  -H "Authorization: Bearer $TEST_KEY" \
  -d '{"companyId": "comp_…", "by": "60d"}'

Accepts by as 1h, 3d, 2w, 1m, 1y. The clock is per-company and never affects another tenant. POST …/clock/reset snaps it back.

Reset & data lifetime

# Nuke EVERYTHING in your sandbox tenant
curl -X POST …/v1/sandbox/reset \
  -H "Authorization: Bearer $TEST_KEY" \
  -d '{"confirm": "yes"}'

Local webhook tunnels

To receive webhooks while running your handler on localhost, use any tunnel:

ngrok http 3000
# OR
cloudflared tunnel --url http://localhost:3000

Then point a sandbox webhook at https://<random>.ngrok.io/hooks. The dashboard's Resend button sends a byte-identical retry — perfect for iterating on your signature verifier.

Copy-paste bootstrap scripts

Spin up a complete test scenario (one sender, one recipient simulator, one webhook, three sent invoices) with a single shell script:

#!/usr/bin/env bash
set -euo pipefail
BASE="https://back.flowie.ink/exchange/v1"
KEY="$FLOWIE_TEST_KEY"
H=(-H "Authorization: Bearer $KEY" -H "Content-Type: application/json")

# 1. Create a sandbox sender
SEND=$(curl -s -X POST "$BASE/companies" "${H[@]}" \
  -d '{"vatNumber":"BE0000000001"}')
COMP=$(echo "$SEND" | jq -r .id)
echo "→ sender: $COMP"

# 2. Register a webhook (replace URL with your tunnel)
curl -s -X POST "$BASE/webhooks" "${H[@]}" \
  -d '{"url":"'"$WEBHOOK_URL"'","events":["*"]}' > /dev/null

# 3. Send 3 invoices to the happy-path simulator
for n in 001 002 003; do
  curl -s -X POST "$BASE/documents/send" "${H[@]}" \
    -H "Idempotency-Key: bootstrap-$n" \
    -d '{
      "type":"invoice",
      "from":"'"$COMP"'",
      "to":"0208:SIM_HAPPY",
      "document":{
        "number":"INV-2026-'"$n"'",
        "issueDate":"2026-04-25",
        "currency":"EUR",
        "lines":[{"description":"Test","quantity":1,"unitPrice":100,"vatRate":21}]
      }
    }' | jq -r '.id + " → " + .status'
done

The same script in Python · Node · Go on GitHub.

Gotchas

• Sandbox keys never reach production. If you accidentally point a flw_test_… key at https://back.flowie.ink, you get 401 INVALID_TOKEN. Production rejects test keys and vice versa.
• Webhook signatures use the webhook's own secret, not a global sandbox secret. Each webhook you create has its own.
• Time-travel is per-company. Two parallel test runs on different sandbox companies don't interfere.
• Idempotency cache TTL is the same in sandbox (24h). If a test reuses the same key within that window, you'll see the cached response, not a fresh send.
• Test data is not anonymized in logs. Don't paste real customer VATs into sandbox just because "it's only a test."