CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Mintlify-based documentation site for e-invoice.be, an international Peppol Access Point and SMP operating under the Belgian Peppol Authority (BOSA). The documentation covers API integration, webhooks, and usage guides for electronic invoicing via Peppol. e-invoice.be serves:

Individual companies across multiple industries worldwide
Public and private listed companies
SaaS companies (via reseller programme)
Public and government agencies
Companies with or without ERP systems

Tech Stack

Documentation framework: Mintlify (v4.2.177)
Content format: MDX (Markdown + JSX components)
Package manager: Bun (bun.lock present)
Runtime: Node.js

Development Workflow

Local Development

To run the documentation site locally with live preview:

npx mint dev

This starts a local development server with hot-reloading for real-time preview of changes.

Building

Mintlify handles the build process automatically when deployed. For local validation:

npx mint build

Project Structure

/
├── docs.json              # Mintlify configuration (navigation, theme, colors)
├── index.mdx              # Homepage - overview of e-invoice.be
├── quickstart.mdx         # Getting started guide
├── authentication.mdx     # API authentication guide
├── environments.mdx       # API host and test mode
├── api-reference.mdx      # API reference overview
├── admin-api.mdx          # Admin API documentation
├── reseller-programme.mdx # Partner/reseller information
├── guides/
│   ├── creating-invoices.mdx    # How to create and send e-invoices
│   ├── credit-notes.mdx         # Creating credit notes
│   ├── advanced-invoicing.mdx   # Allowances & charges (document + line level)
│   ├── invoice-totals.mdx       # Calculating invoice totals
│   ├── validation.mdx           # JSON validation during development
│   ├── lookup-participants.mdx  # Peppol participant lookup
│   ├── ubl-documents.mdx        # Sending pre-generated UBL XML
│   └── pdf-documents.mdx        # Creating from PDF files
├── api-reference/
│   └── schemas/
│       ├── document.mdx         # Document schema documentation
│       └── line-item.mdx        # Line item schema documentation
├── essentials/
│   └── webhooks.mdx       # Webhook integration guide
├── images/                # Static assets (logos, screenshots)
└── package.json

Configuration (`docs.json`)

The docs.json file is the central configuration:

Navigation structure: Defines tabs (Guides, API reference, Example invoices) and page organization
Theme: Uses “willow” theme with blue color scheme (#0071b7 primary)
API integration: References OpenAPI spec at https://api.e-invoice.be/api/openapi.json
Branding: IBM Plex Sans font, custom logo at /images/logo.svg

Navigation structure:

Getting started: index, quickstart, authentication, environments
Core guides: creating-invoices, credit-notes, advanced-invoicing, invoice-totals, validation, lookup-participants
Alternative formats: ubl-documents, pdf-documents
Integration: webhooks
Partners: reseller-programme
API reference: Auto-generated from OpenAPI, plus overview page and custom schema documentation
Example invoices: Sample invoice templates

Content Guidelines

File Organization

Getting started guides: Root directory (quickstart.mdx, authentication.mdx, api-reference.mdx)
Core guides: /guides/ directory (creating-invoices, credit-notes, advanced-invoicing, invoice-totals, validation, lookup-participants, ubl-documents, pdf-documents)
Integration guides: /essentials/ directory (webhooks)
API schemas: /api-reference/schemas/ directory (document.mdx, line-item.mdx)
Images: /images/ directory for static assets
ALWAYS update docs.json navigation after creating new pages
Use .mdx extension for all content files

MDX Components

Mintlify provides built-in components used throughout the docs:

<Card title="Title" icon="icon-name" href="/path">
  Description
</Card>

<CardGroup cols={2}>
  <Card>...</Card>
  <Card>...</Card>
</CardGroup>

<Warning>
Important warning message
</Warning>

<Note>
Additional context or information
</Note>

<Tip>
Helpful tip or best practice
</Tip>

Front Matter

Every MDX file requires YAML front matter:

---
title: "Page Title"
description: "Page description for SEO"
---

API Documentation

OpenAPI Specification

The API reference tab auto-generates from the OpenAPI specification at:

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

Current OpenAPI version: 1.1.0

Updating API Documentation

The API documentation in Mintlify is automatically generated from the OpenAPI spec. To update the API reference:

Backend changes: Modify the OpenAPI spec on the backend API server
- The spec is served at https://api.e-invoice.be/api/openapi.json
- Changes to the backend automatically update this endpoint
Mintlify sync: Mintlify automatically pulls the latest OpenAPI spec
- The docs.json file references the OpenAPI URL via the openapi field
- Mintlify periodically refreshes the spec to keep docs up to date
- No manual intervention needed in the docs repository
Custom schema documentation: Some schemas have custom MDX documentation:
- /api-reference/schemas/document.mdx - Extended document schema explanation
- /api-reference/schemas/line-item.mdx - Line item details and examples
- Update these files manually when schema behavior changes

OpenAPI Spec Structure Overview

The OpenAPI spec includes: Endpoints:

Document management (create, retrieve, validate, send, attachments)
Inbox/Outbox operations (received/sent documents, drafts)
Conversion & validation (PDF, UBL, JSON validation)
Peppol network operations (participant lookup, ID validation)
Account & integration (tenant info, webhooks, usage stats)

Schemas:

Document types: Invoice, Credit Note, Debit Note, Self-Billing variants
Document states: Draft, Transit, Failed, Sent, Received
Tax handling: Category codes, VAT rates, exemption reasons
Attachments: Binary file support with metadata
Line items: Quantity, pricing, tax calculation

Authentication: HTTP Bearer token authentication To update API docs, modify the OpenAPI spec on the backend - changes propagate automatically to Mintlify.

Webhook System Architecture

The platform implements webhook notifications for document events:

Event Types

document.received - Document successfully received via Peppol
document.sent - Document successfully sent
document.sent.failed - Send failure
document.received.failed - Receive failure

Security Model

Webhooks use HMAC-SHA256 signatures in X-Signature header
Format: sha256={hex_digest}
Payload is JSON-sorted and UTF-8 encoded before signing
Verification required for production implementations

Payload Structure

{
  "id": "evt_...",
  "tenant_id": "ten_...",
  "created_at": 1729468923,
  "type": "document.sent",
  "data": {
    "document_id": "doc_..."
  }
}

Deployment

Mintlify handles deployment automatically via their platform. Changes pushed to the main branch trigger automatic deployments. The site is hosted at: https://docs.e-invoice.be

API Architecture

Base URL (single host — there is no separate staging/development host):

https://api.e-invoice.be

To test without touching the Peppol network, use a sandbox company (a workspace in test mode): outbound sends are diverted to email, inbound documents are seeded via Simulate inbound, and no Peppol traffic occurs. Test-ness is fixed at company creation. See environments.mdx. Authentication: Bearer token in Authorization header

Test Mode & Sandbox Companies

Testing is controlled by test mode, which is delivered through a sandbox company - a dedicated company (created self-serve in app.e-invoice.be via “Create sandbox company”) that runs in test mode. It is determined by the company you authenticate as, not by a separate host. Each company (sandbox or regular) has its own API key; test status is set at creation and is immutable. Regular company (production):

Documents are sent via the actual Peppol network
Recipients must be registered on Peppol
Real business transactions only

Sandbox company (development & testing):

Documents are sent via email as UBL XML to the company_email address
No actual Peppol transmission occurs
company_email field is REQUIRED for email delivery
A synthetic Belgian VAT number is auto-assigned; no KBO/VIES or contact verification
No credits/billing; free to use
Everything else (validation, webhooks, API endpoints) works identically

Important: Always develop and test with a sandbox company. To go live, create a separate regular company. See environments.mdx for complete details.

Core Workflow

The e-invoice.be API follows this workflow:

Validate JSON (POST /api/validate/json) - Test invoice JSON before creating documents
- CRITICAL: Validation must happen BEFORE document creation
- Only valid JSON that can convert to UBL BIS Billing 3.0 is accepted
- Does not create any documents - safe for testing
Create Document (POST /api/documents/) - Create invoice/credit note
- Requires valid JSON (pre-validated)
- Creates document in DRAFT state
- Returns document ID
Send via Peppol (POST /api/documents/{id}/send) - Transmit to recipient
- Changes state from DRAFT to TRANSIT
- Delivers via Peppol network
- Webhook notifications on success/failure

Key Endpoint Categories

Documents:

POST /api/documents/ - Create invoice/credit note
GET /api/documents/{id} - Get document details
POST /api/documents/{id}/send - Send via Peppol
GET /api/inbox/ - List received documents
GET /api/outbox/ - List sent documents

Validation (Critical for development):

POST /api/validate/json - Validate JSON structure (use extensively!)
POST /api/validate/ubl - Validate UBL XML
GET /api/validate/peppol-id - Check if participant is registered

Participant Lookup:

GET /api/lookup - Get participant details
GET /api/lookup/participants - Search by name/identifier

Webhooks:

POST /api/webhooks/ - Create webhook
GET /api/webhooks/ - List webhooks
PUT /api/webhooks/{id} - Update webhook
DELETE /api/webhooks/{id} - Delete webhook
POST /api/webhooks/{id}/test - Test webhook

Account:

GET /api/me/ - Get account information

Important Concepts

Peppol IDs vs Company Identifiers

Company identifiers in API: Documents can contain both tax IDs and company IDs
- vendor_tax_id / customer_tax_id: VAT/tax number (e.g., BE1018265814)
- vendor_id / customer_id: Company registration number (e.g., CBE number)
Peppol ID format: scheme:identifier (e.g., 0208:0123456789)
Belgian companies use scheme 0208 with CBE number (VAT number without ‘BE’ prefix)
Example: VAT number BE0123456789 → Peppol ID 0208:0123456789
IMPORTANT: The API automatically derives Peppol IDs from company identifiers when sending documents via /api/documents/{id}/send
- This happens regardless of any endpoint IDs in UBL documents
- For Belgian companies, 0208 scheme is mandatory (Belgian government requirement)
- BEST PRACTICE: Always explicitly specify Peppol IDs using query parameters: sender_peppol_scheme, sender_peppol_id, receiver_peppol_scheme, receiver_peppol_id
- Automatic derivation works in most cases but explicit routing prevents delivery failures
Must be registered on Peppol network to receive e-invoices
Always validate with /api/validate/peppol-id before sending

Document States

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

UBL BIS Billing 3.0

European standard for e-invoicing (EN 16931)
The API converts JSON to UBL XML automatically
All invoices must comply with this standard
Use /api/validate/json to ensure compliance

Documentation Style Guidelines

When creating or updating documentation:

Use professional, concise language - avoid casual phrases
Include MDX front matter with title and description on all pages
Use Mintlify components (<Warning>, <Note>, <Tip>, <CardGroup>) for emphasis
Add “Next Steps” section with <CardGroup> navigation cards at the end of guides
Use real company examples: E-INVOICE BV (BE1018265814) as vendor, OpenPeppol VZW (BE0848934496) as customer
Include amount field in line item examples (calculated as quantity × unit_price)
Keep examples consistent across all documentation

Important Notes

This is a documentation-only repository - no backend code
The actual e-invoice.be API and webhook service are separate systems
OpenAPI spec is maintained externally and referenced by URL at https://api.e-invoice.be/api/openapi.json
Always update docs.json navigation when adding pages - Mintlify won’t auto-discover new pages
Validation is REQUIRED before document creation - the API rejects invalid invoices

​CLAUDE.md

​Project Overview

​Tech Stack

​Development Workflow

​Local Development

​Building

​Project Structure

​Configuration (docs.json)

​Content Guidelines

​File Organization

​MDX Components

​Front Matter

​API Documentation

​OpenAPI Specification

​Updating API Documentation

​OpenAPI Spec Structure Overview

​Webhook System Architecture

​Event Types

​Security Model

​Payload Structure

​Deployment

​API Architecture

​Test Mode & Sandbox Companies

​Core Workflow

​Key Endpoint Categories

​Important Concepts

​Peppol IDs vs Company Identifiers

​Document States

​UBL BIS Billing 3.0

​Documentation Style Guidelines

​Important Notes