Environments

​

Overview

​

API Hosts

​

Production API: api.e-invoice.be

• Real Peppol network transmission
• Standard rate limits for production use
• Stable, tested features only
• Use this for live business transactions

​

Development API: api-dev.e-invoice.be

• Testing new features before general release
• Custom customer-specific features under development
• Load testing with different rate limits
• Experimentation without impacting production

​

Test Mode

​

When Test Mode is Enabled

• Documents are not sent via the Peppol network
• Instead, an email is sent with the UBL XML that would have been transmitted
• Admin API tenant registrations simulate the registration without actually registering on Peppol
• All other API functionality works normally

​

Key Points About Test Mode

• Test mode ≠ api-dev.e-invoice.be (they are independent concepts)
• New companies are not automatically in test mode
• Test mode must be explicitly requested
• Works on both production and development API hosts

​

Which Should You Use?

​

Environment Comparison

​

Test Mode Details

​

How Test Mode Works

1. Document creation: Works exactly the same as normal
2. Document sending: Instead of Peppol transmission:
   • Document is validated and converted to UBL XML
   • State transitions: DRAFT → TRANSIT → SENT
   • UBL XML is attached to an email
   • Email is sent to the address configured for your account
   • No actual Peppol transmission occurs
3. All other functionality: Operates normally (webhooks, API endpoints, etc.)

​

When to Use Test Mode

• Development: Building and testing your integration
• Training: Demonstrating the platform without affecting Peppol
• Validation: Testing invoice data and UBL generation
• Staging deploys: QA environments that should mirror production behavior

​

When NOT to Use Test Mode

• Production: Live business transactions must have test mode disabled
• Real invoices: Any invoice that needs to reach a recipient via Peppol

​

Shared Database and Credentials

• Database: Your account, documents, and settings are synchronized
• API credentials: The same API key works on both hosts
• Account information: Registration, Peppol ID, and configuration are identical
• Test mode setting: Test mode applies to both hosts when enabled

​

Switching Between API Hosts

​

Example: Node.js

// Most users should use production API
const BASE_URL = 'https://api.e-invoice.be';

// Only use development API for specific scenarios
// const BASE_URL = 'https://api-dev.e-invoice.be';

const api = axios.create({
  baseURL: BASE_URL,
  headers: {
    'Authorization': `Bearer ${process.env.E_INVOICE_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

​

Example: Python

import os

# Most users should use production API
BASE_URL = 'https://api.e-invoice.be'

# Only use development API for specific scenarios
# BASE_URL = 'https://api-dev.e-invoice.be'

headers = {
    'Authorization': f'Bearer {os.getenv("E_INVOICE_API_KEY")}',
    'Content-Type': 'application/json'
}

​

Example: curl

# Production API (recommended for most users)
curl -X GET "https://api.e-invoice.be/api/me/" \
     -H "Authorization: Bearer YOUR_API_KEY"

# Development API (only for beta features/load testing)
curl -X GET "https://api-dev.e-invoice.be/api/me/" \
     -H "Authorization: Bearer YOUR_API_KEY"

​

Best Practices

​

Recommended Development Workflow

1. Use Production API with Test Mode
   • Request test mode to be enabled on your account
   • Develop and test all integration code on api.e-invoice.be
   • Test mode prevents Peppol transmission but validates everything else
2. Validate Thoroughly
   • Use /api/validate/json extensively during development
   • Test with multiple invoice scenarios
   • Verify calculations, tax rates, and totals
3. Test End-to-End
   • Create documents and verify email delivery of UBL XML in test mode
   • Import received UBL into accounting software to confirm compatibility
   • Test webhooks and error handling
4. Disable Test Mode for Production
   • Contact [email protected] to disable test mode
   • Start with a small volume of real invoices
   • Monitor for any issues during initial rollout

​

Configuration Management

# .env
E_INVOICE_API_KEY=your_api_key
E_INVOICE_BASE_URL=https://api.e-invoice.be

​

Testing Received Documents

1. Enable test mode on your account
2. Create a document with your own company as the recipient
3. Send the document (it will be emailed, not sent via Peppol)
4. Check your inbox via GET /api/inbox/
5. Test accept/reject workflows with POST /api/inbox/{id}/accept

​

Frequently Asked Questions

​

Do I need test mode?

​

Which API host should I use?

​

What’s the difference between test mode and the development API?

• Test mode: A setting on your account that prevents Peppol transmission (available on both API hosts)
• Development API (api-dev.e-invoice.be): A separate API host with experimental features and configurable rate limits

​

Can I use different API keys for different environments?

​

How do I switch from testing to production?

​

Can I test webhooks with test mode?

​

Next Steps