API Reference - e-invoice.be

Overview

The e-invoice.be API enables you to create, send, and manage Peppol-compliant e-invoices and credit notes. All invoices are automatically converted to UBL BIS Billing 3.0 format and transmitted via the Peppol network.

Base URLs

e-invoice.be provides two environments: Production:

https://api.e-invoice.be

Staging:

https://api-dev.e-invoice.be

Key difference: Staging uses email delivery instead of the Peppol network. Documents are sent as UBL XML attachments to the company_email address, making it perfect for testing without affecting real recipients. The same API credentials work in both environments.

Environment Details

Learn more about production vs. staging environments

Authentication

All API requests require authentication using an API key in the Authorization header:

curl -X GET "https://api.e-invoice.be/api/documents/" \
     -H "Authorization: Bearer YOUR_API_KEY"

See the Authentication guide for details on obtaining and using API keys.

API Structure

The e-invoice.be API is organized into several main sections:

Documents

Create, manage, and send invoices and credit notes via Peppol. Key Endpoints:

POST /api/documents/ - Create a new document
GET /api/documents/ - List all documents
GET /api/documents/{id} - Get document details
POST /api/documents/{id}/send - Send document via Peppol
DELETE /api/documents/{id} - Delete a document

Schemas:

Document - Invoice and credit note structure
LineItem - Line item structure

Related Guides:

Validation

Validate invoice JSON or UBL XML before creating documents. Key Endpoints:

POST /api/validate/json - Validate JSON invoice data
POST /api/validate/ubl - Validate UBL XML
GET /api/validate/peppol-id - Verify Peppol participant ID

Related Guides:

Inbox

Receive and manage incoming invoices from other Peppol participants. Key Endpoints:

GET /api/inbox/ - List received documents
GET /api/inbox/{id} - Get received document details
POST /api/inbox/{id}/accept - Accept received invoice
POST /api/inbox/{id}/reject - Reject received invoice

Lookup

Search for Peppol participants and verify their registration status. Key Endpoints:

GET /api/lookup/participants - Search for participants
GET /api/lookup - Get participant details

Related Guides:

Lookup Participants

Alternative Formats

Create documents from UBL XML or PDF files. Key Endpoints:

POST /api/documents/ubl - Create from UBL XML
POST /api/documents/pdf - Create from PDF (with metadata)

Related Guides:

Webhooks

Configure webhook endpoints to receive real-time notifications about document events. Key Endpoints:

GET /api/webhooks/ - List webhook subscriptions
POST /api/webhooks/ - Create webhook subscription
DELETE /api/webhooks/{id} - Delete webhook subscription

Related Guides:

Webhooks

Admin API (Resellers Only)

For resellers and service providers managing multiple customer organizations, we provide a separate Admin API with organization-level capabilities:

Tenant Management - Create and manage customer organizations
API Key Provisioning - Generate API keys for customers
Peppol Registration - Register customers on the Peppol network
Credential Rotation - Manage API keys without customer involvement

The Admin API requires an organization API key and is only available to approved reseller partners.

Admin API Documentation

Complete guide to the Admin API for managing customer tenants (resellers only)

Learn more about our Reseller Programme.

Request & Response Format

Request Format

All requests use JSON format:

curl -X POST "https://api.e-invoice.be/api/documents/" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "document_type": "INVOICE",
       "invoice_id": "INV-2024-001",
       "invoice_date": "2024-10-24",
       "currency": "EUR",
       "vendor_name": "Your Company BVBA",
       "vendor_tax_id": "0208:0123456789",
       "customer_name": "Customer Company NV",
       "customer_tax_id": "0208:0987654321",
       "items": [
         {
           "description": "Professional Services",
           "quantity": 10,
           "unit": "C62",
           "unit_price": 100.00,
           "tax_rate": "21.00"
         }
       ]
     }'

Response Format

Successful responses return JSON with a 2xx status code:

{
  "id": "doc_abc123",
  "document_type": "INVOICE",
  "state": "DRAFT",
  "invoice_id": "INV-2024-001",
  "created_at": "2024-10-24T10:00:00Z",
  "updated_at": "2024-10-24T10:00:00Z"
}

Error Responses

Errors return JSON with an appropriate HTTP status code:

{
  "detail": "Invalid authentication credentials"
}

Common status codes:

400 Bad Request - Invalid request data
401 Unauthorized - Missing or invalid API key
404 Not Found - Resource not found
422 Unprocessable Entity - Validation error
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Pagination

List endpoints support pagination with skip and limit parameters:

GET /api/documents/?skip=0&limit=100

Parameters:

skip - Number of records to skip (default: 0)
limit - Maximum records to return (default: 100, max: 1000)

Response:

{
  "documents": [...],
  "total": 250,
  "skip": 0,
  "limit": 100
}

Rate Limiting

API requests are rate-limited to ensure service quality:

Standard tier: 100 requests per minute
Premium tier: 1000 requests per minute

Exceeding limits returns 429 Too Many Requests with a Retry-After header.

Document States

Documents progress through different states:

State	Description
`DRAFT`	Created but not sent
`TRANSIT`	Being transmitted via Peppol
`SENT`	Successfully delivered
`FAILED`	Transmission failed
`RECEIVED`	Received from another party

Outbound Document Flow

Documents you create and send follow this state progression:

Automatic Retry Strategy: Documents in TRANSIT state use an exponential backoff strategy with multiple retry attempts over 24 hours before transitioning to FAILED. This ensures maximum delivery success even during temporary network issues or recipient downtime.Manual Retry: Documents in FAILED state can be retried by calling POST /api/documents/{id}/send again, which will transition them back to TRANSIT for another delivery attempt.Coming soon: Detailed transmission attempt history will be available in a future release, allowing you to view all retry attempts, timestamps, and failure reasons for each transmission.

Inbound Document Flow

Documents received from other Peppol participants:

Track state changes via webhooks or by polling the document endpoint.

Supported Currencies

The API supports the following ISO 4217 currency codes: EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, CNY, INR, SEK, NOK, DKK, SGD, HKD Default: EUR

Peppol Participant IDs

Peppol IDs use the format scheme:identifier: Common schemes:

Belgium: 0208:0123456789 (CBE number)
Netherlands: 0106:12345678 (KVK number)
Germany: 0204:DE123456789 (VAT number)
France: 0009:12345678901234 (SIRET)

See the complete Peppol ID schemes list.

Getting Started

Quickstart

Get started in 5 minutes

Authentication

Set up API authentication

Creating Invoices

Learn how to create e-invoices

Validation

Validate before sending

OpenAPI Specification

The complete OpenAPI specification is available at:

https://api.e-invoice.be/api/openapi.json

You can use this specification to:

Generate client libraries in your programming language
Import into API testing tools (Postman, Insomnia, etc.)
Validate request/response structures

Need Help?

Support

Contact our support team

GitHub

View our open-source projects

Overview

Schemas

Documents

Inbox

Outbox

Validate

Lookup

Tenant

Webhooks

Conversion

​Overview

​Base URLs

Environment Details

​Authentication

​API Structure

​Documents

​Validation

​Inbox

​Lookup

​Alternative Formats

​Webhooks

​Admin API (Resellers Only)

Admin API Documentation

​Request & Response Format

​Request Format

​Response Format

​Error Responses

​Pagination

​Rate Limiting

​Document States

​Outbound Document Flow

​Inbound Document Flow

​Supported Currencies

​Peppol Participant IDs

​Getting Started

Quickstart

Authentication

Creating Invoices

Validation

​OpenAPI Specification

​Need Help?

Support

GitHub

Overview

Base URLs

Authentication

API Structure

Documents

Validation

Inbox

Lookup

Alternative Formats

Webhooks

Admin API (Resellers Only)

Request & Response Format

Request Format

Response Format

Error Responses

Pagination

Rate Limiting

Document States

Outbound Document Flow

Inbound Document Flow

Supported Currencies

Peppol Participant IDs

Getting Started

OpenAPI Specification

Need Help?