> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e-invoice.be/llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

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

```bash theme={null}
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:

```bash theme={null}
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:

```mdx theme={null}
<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:

```yaml theme={null}
---
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

```json theme={null}
{
  "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:

1. **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

2. **Create Document** (`POST /api/documents/`) - Create invoice/credit note
   * Requires valid JSON (pre-validated)
   * Creates document in DRAFT state
   * Returns document ID

3. **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