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
├── 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
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

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

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

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 URLs:

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

Authentication: Bearer token in Authorization header

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 Tax IDs

Tax IDs in API: Use full VAT number format (e.g., BE1018265814 for Belgian companies)
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
The API automatically converts tax IDs to Peppol ID format when transmitting
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

Getting started

Core guides

Alternative formats

Integration

Partners

​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

​Webhook System Architecture

​Event Types

​Security Model

​Payload Structure

​Deployment

​API Architecture

​Core Workflow

​Key Endpoint Categories

​Important Concepts

​Peppol IDs vs Tax IDs

​Document States

​UBL BIS Billing 3.0

​Documentation Style Guidelines

​Important Notes