Developer documentation

PeppolCheck.fr API and agent integration docs

Everything you need to integrate the PeppolCheck.fr public API — quickstart, authentication, endpoints, error envelope, agent discovery, OpenAPI, MCP, and the NLWeb /ask endpoint.

Quickstart

The PeppolCheck.fr API is a small, public, read-only HTTP API on top of the OpenPeppol SML, SMP, and Peppol Directory. There is no registration, no API key, and no rate-limited tier behind a paywall — the public surface is the only surface.

Resolve a participant by ID:

curl https://peppolcheck.fr/api/v1/participant/0208:0848934496

Search by name, VAT number, or registry ID:

curl 'https://peppolcheck.fr/api/v1/search?q=carrefour'

Identify your client. Set a descriptive User-Agent like MyAgent/1.0 (+https://example.com) so we can reach you if your traffic hits rate limits.

Authentication

The public API is unauthenticated. Send GETs with no Authorization header. For agent-discovery flows, see /auth.md and the OAuth protected-resource metadata.

When PeppolCheck.fr later adds authenticated endpoints (e.g. high-volume search), they will return 401 with a spec-shaped WWW-Authenticate: Bearer resource_metadata="…" challenge, and the metadata document will advertise the new flow.

API endpoints

GET /api/v1/participant/{scheme}:{value}

Resolve a Peppol participant by ID and return both the Peppol Directory record and the SMP access point. The path parameter must match \d{4}:[A-Za-z0-9._\-+]+.

{
  "participantId": "0208:0848934496",
  "directory": {
    "name": "CARREFOUR BELGIUM SA",
    "countryCode": "BE",
    "docTypes": [ ... ]
  },
  "smp": {
    "url": "https://smp.example/iso6523-actorid-upis%3A%3A0208%3A0848934496",
    "hostname": "smp.example",
    "serviceCount": 7,
    "endpoint": { ... }
  }
}

GET /api/v1/search?q={query}

Full-text search by company name, VAT number, or registry ID. q must be at least 2 characters; up to 25 results are returned.

{
  "query": "carrefour",
  "totalCount": 12,
  "results": [
    { "participantId": "0208:0848934496", "name": "CARREFOUR BELGIUM SA", "countryCode": "BE" }
  ]
}

POST /ask

NLWeb-compatible natural-language endpoint. Send { "query": "Find Carrefour on Peppol" }. Set Accept: text/event-stream to receive Server-Sent Events with NLWeb start, result, complete events.

Errors

Every error response is a JSON envelope:

{ "error": { "code": "<machine_code>", "message": "<human readable>" } }

Code	HTTP	Meaning
`invalid_participant_id`	400	Path was not a valid Peppol ID.
`missing_query`	400	`q` missing or empty.
`query_too_short`	400	`q` is shorter than 2 characters.
`not_found`	404	Participant is not on the Peppol network.
`lookup_failed`	502	Upstream OpenPeppol registry failed.
`search_failed`	502	Upstream directory search failed.

Agent integration

MCP server (Streamable HTTP): /mcp
MCP server card: /.well-known/mcp/server-card.json
A2A agent card: /.well-known/agent-card.json
agent.json discovery: /.well-known/agent.json
Markdown manual: /llms-full.txt
Agent instructions: /agents.md
OpenAPI: /openapi.json
API catalog (RFC 9727): /.well-known/api-catalog
OAuth protected-resource metadata (RFC 9728): /.well-known/oauth-protected-resource
Web Bot Auth directory: /.well-known/http-message-signatures-directory

Source code & coding-agent configs

This site is open-source. The repo on GitHub ships AI-coding-agent configs (AGENTS.md, .cursorrules) and a skills.sh-compatible SKILL.md so coding agents can edit the codebase without guessing conventions.

Repository: github.com/e-invoice-be/peppolcheck-fr
Coding-agent guide: AGENTS.md
Cursor rules: .cursorrules
skills.sh skill: SKILL.md

OpenAPI

The complete OpenAPI 3.1 schema lives at /openapi.json. Use it to generate clients, drive function-calling, or feed an agent's tool layer.

Sandbox

Because the production API is free, public, and read-only, there is no separate sandbox. Every query you make against peppolcheck.fr is the real surface; there is nothing to mutate, so there is nothing to break. Use the example participants below for testing without risk.

0208:0848934496 — Carrefour Belgium
9925:BE0413404747 — Proximus
0106:KVK33014286 — Heineken

Streaming

The /ask endpoint streams Server-Sent Events when called with Accept: text/event-stream. Lookup and search endpoints respond as a single JSON body — the round-trip is fast enough (typically under 300 ms when the upstream registries are warm) that chunked streaming would only add overhead.

Webhooks

No webhook system yet. The Peppol Directory refreshes nightly, so most agent workflows can re-poll on demand. If you need push notifications for participant changes, write to willem@e-invoice.be with your use case.