Sandbox & Test Mode

Test the full compliance engine without affecting production quotas.

Overview

Test mode runs the real compliance engine — same validation, same remediation, same results. The only differences are: no quota consumed, evidence packs are watermarked, and every response clearly signals test mode.

Test Keys

Test API keys use the sk_test_ prefix, while production keys use sk_live_. Both keys are created automatically when you sign up or regenerate your API key. Manage your keys from your Dashboard → API section.

Authorization: Bearer sk_test_abc123...

Test keys work with all endpoints:

/v2/validate-and-fix — Validate + remediate in one call (recommended)
/v1/validate — Validation only
/v1/fixer/fix — Granular remediation with flow tracking
/v1/fixer/fix-with-input — Input-required error resolution
/v1/evidence-pack — Evidence pack generation

Test vs Production

Feature	Test Mode (`sk_test_`)	Production (`sk_live_`)
Validation engine	Full engine, all 1,300+ rules	Full engine, all 1,300+ rules
Remediation	All fix types available	All fix types available
Evidence packs	Watermarked “TEST MODE”	Production-grade, signed
Quota impact	No quota consumed	Counts against monthly quota
Rate limits	100 requests/hour (fixed)	Based on plan tier
Response headers	Includes `X-Test-Mode: true`	No test mode header
Response body	`_meta.testMode: true`	No testMode field
Webhooks	Payload includes `testMode: true`	No testMode field

Example Request

curl -X POST https://api.invoicenavigator.eu/api/v2/validate-and-fix \
  -H "Authorization: Bearer sk_test_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"xml": "<Invoice>...</Invoice>", "remediation_policy": "safe"}'

Example Response

{
  "success": true,
  "data": {
    "validationRef": "VAL-1740744832000-XYZ123AB",
    "originalValid": false,
    "fixedValid": true,
    "engine": "hybrid",
    "fixesApplied": 1,
    "fixSummary": {
      "totalIssues": 1,
      "autoFixable": 1,
      "needsInput": 0,
      "blocked": 0,
      "canAutoFixAll": true
    },
    "remainingIssues": [],
    "_links": {
      "self": "/api/v2/validate-and-fix",
      "evidencePack": "/api/v1/evidence-pack?validationRef=VAL-1740744832000-XYZ123AB"
    }
  },
  "_meta": {
    "testMode": true,
    "processingTimeMs": 87
  }
}

The response also includes the X-Test-Mode: true header.

Evidence Packs

Evidence packs generated with a test key include a visible “TEST MODE” watermark on every page and a warning banner stating the pack is not valid for compliance purposes. The cryptographic hash and verification code still work — only the visual presentation differs.

Webhooks

Webhooks triggered by test mode API requests include testMode: true at the top level of the payload. You can use this to filter or ignore test events in your webhook handler.

{
  "event": "validation.completed",
  "testMode": true,
  "timestamp": "2026-02-27T10:30:00Z",
  "data": {
    "validationRef": "VAL-1740744832000-XYZ123AB",
    "isValid": true,
    "format": "ubl"
  }
}

Rate Limits

Test keys are limited to 100 requests per hour. This limit is separate from your production rate limits — test usage never affects production.

Rate limit headers are included in every response so you can track usage programmatically:

X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1738800000

When the test rate limit is exceeded, the API returns:

{
  "success": false,
  "error": {
    "code": "TEST_RATE_LIMIT_EXCEEDED",
    "message": "Test mode rate limit exceeded (100 requests/hour). Use a production key for higher limits."
  }
}

Sample Invoices

The API includes sample invoices for testing common scenarios. Fetch available samples from the samples endpoint:

curl https://api.invoicenavigator.eu/api/onboarding/samples \
  -H "Authorization: Bearer sk_test_abc123..."

Available samples include:

Valid EN16931 UBL invoice — passes all validation rules
Invoice with BR-01 error — missing business process identifier
Invoice with multiple country-specific errors — triggers DE/FR/IT/NL rules
ZUGFeRD PDF with embedded XML — hybrid format testing

Going to Production

Switch from test mode to production by replacing your sk_test_ key with your sk_live_ key. That's it. Same endpoints, same parameters, same response format.

Replace sk_test_ key with sk_live_ key
Verify error handling for all API response codes
Set up webhook endpoints (if using webhooks)
Configure retry logic for transient failures
Review rate limits for your plan tier
Test with real invoices in test mode first

Important: Production API calls count against your monthly quota. Make sure your integration is thoroughly tested in sandbox mode before switching to live keys.

Ready to start building?

Get your test API key and start integrating in minutes.

Get Your API Key