Skip to content

API Specification

Jump to bottom
Philip Helger edited this page Mar 29, 2026 · 26 revisions

API Specification

Overview

The AP exposes REST APIs for outbound document submission, status queries, and inbound reporting. All APIs are provided via Spring Boot.

Outbound APIs

POST — Submit Document (raw business document + metadata)

Path: /api/outbound/submit/{senderID}/{receiverID}/{docTypeID}/{processID}/{c1CountryCode}

Submits a raw business document for outbound transmission. The AP creates the SBDH envelope.

Path parameters (required):

  • senderID — Peppol Participant ID of the sender
  • receiverID — Peppol Participant ID of the receiver
  • docTypeID — Peppol Document Type Identifier
  • processID — Peppol Process Identifier
  • countryC1 — Country code of the sender (C1)

Query parameters (optional):

  • sbdhInstanceID — Custom SBDH Instance Identifier. When omitted, a random UUID-based identifier is generated.
  • mlsTo — Alternative Peppol participant ID to receive MLS responses
  • sbdhStandard — SBDH Standard override for non-XML payloads (e.g., urn:peppol:doctype:pdf+xml for PDF). When omitted, auto-derived from the document type identifier.
  • sbdhTypeVersion — SBDH TypeVersion override (e.g., 0). When omitted, auto-derived from the document type identifier.
  • sbdhType — SBDH Type override (e.g., factur-x). When omitted, auto-derived from the document type identifier.
  • payloadMimeType — MIME type for binary payloads (e.g., application/pdf). When set, the payload is treated as binary content and wrapped in <BinaryContent> instead of XML. When omitted, the payload is treated as XML.

Request body: The raw business document (e.g., UBL Invoice XML) or binary payload (e.g., PDF bytes when payloadMimeType is set)

Response:

  • status — queued or not_queued
  • sbdhInstanceID — The SBDH Instance Identifier assigned to this transaction (returned regardless of status, so the Sender Backend can use it for tracking)

Error cases:

  • Invalid or missing parameters
  • Document validation failure (if verification is enabled)
  • AP is shutting down (not accepting new messages)

POST — Submit Document (from S3 reference)

Path: /api/outbound/submit-s3

Since v0.1.1.

Submits a document for outbound transmission by referencing an S3 object instead of inlining the payload. The Sender Backend uploads the document to S3 first, then calls this endpoint with the S3 reference and Peppol metadata. The AP fetches the document from S3 and processes it through the normal outbound pipeline.

Requires outbound.s3.enabled=true in configuration.

Request body (JSON):

  • senderID (required) — Peppol Participant ID of the sender
  • receiverID (required) — Peppol Participant ID of the receiver
  • docTypeID (required) — Peppol Document Type Identifier
  • processID (required) — Peppol Process Identifier
  • c1CountryCode (required) — Country code of the sender (C1)
  • s3Key (required) — The S3 object key of the uploaded document
  • s3Bucket (optional) — The S3 bucket where the document was uploaded. Defaults to the configured outbound.s3.bucket.
  • sbdhInstanceID (optional) — Custom SBDH Instance Identifier. When omitted, a random UUID-based identifier is generated.
  • mlsTo (optional) — Alternative Peppol participant ID to receive MLS responses
  • sbdhStandard (optional) — SBDH Standard override for non-XML payloads
  • sbdhTypeVersion (optional) — SBDH TypeVersion override
  • sbdhType (optional) — SBDH Type override
  • payloadMimeType (optional) — MIME type for binary payloads (e.g., application/pdf)

Response: Same as the raw document submission — the Phase4PeppolSendingReport as JSON on success.

Error cases:

  • Outbound S3 submission is disabled (outbound.s3.enabled=false)
  • Missing required fields
  • S3 bucket/key not accessible or document not found
  • Invalid Peppol identifiers

POST — Submit Document (pre-built SBD)

Path: /api/outbound/submit-sbd

Submits a complete Standard Business Document (with SBDH already present).

Parameters (path or query):

  • mlsTo (optional) — Alternative Peppol participant ID to receive MLS responses

Request body: The complete SBD (SBDH + business document)

Response: Same as above (status + sbdhInstanceID)

All metadata (sender ID, receiver ID, document type, process, C1 country code) is extracted from the SBDH.

GET — Query Outbound Transaction Status

Path: /api/outbound/status/{sbdhInstanceID}

Returns the current status of a specific outbound transaction.

Parameters:

  • sbdhInstanceID — The SBDH Instance Identifier

Response:

  • sbdhInstanceID — Echo of the identifier
  • transactionType — business_document or mls_response
  • senderID — Peppol Participant ID of the sender
  • receiverID — Peppol Participant ID of the receiver
  • docTypeID — Peppol Document Type Identifier
  • processID — Peppol Process Identifier
  • sourceType — How the document was submitted: payload_only (AP creates SBDH) or prebuilt_sbd (SBDH already present)
  • documentSize — Size of the document in bytes
  • documentHash — SHA-256 hash of the document payload
  • c1CountryCode — Country of the sender (C1)
  • status — Current transaction status (pending, rejected, sending, sent, failed, permanently_failed)
  • attemptCount — Total number of sending attempts so far
  • createdDT — When the transaction was created
  • completedDT — When successfully completed (null if not yet)
  • reportingStatus — Whether reporting has been triggered (pending, reported)
  • nextRetryDT — Planned date/time of the next sending retry (null unless status is failed)
  • errorDetails — Summary error from the last failed attempt (null on success)
  • mlsTo — MLS_TO override if set (null otherwise; only for business_document)
  • mlsStatus — MLS response reception status: pending, received_ap, received_ab, received_re, not_applicable (only for business_document)
  • mlsReceivedDT — When the MLS response was received (null if not yet; only for business_document)
  • mlsId — The MLS message ID from the received MLS (null if not yet; only for business_document)
  • attempts — List of sending attempts, each with:
    • as4MessageID — AS4 Message ID used for this attempt
    • as4Timestamp — AS4 MessageInfo/Timestamp from this attempt (UTC). MLS Milestone M1 for business documents; M2 for MLS responses.
    • receiptMessageID — AS4 Message ID from the synchronous receipt (null on failure)
    • httpStatusCode — HTTP status code from the AS4 response (null on failure)
    • attemptDT — Date/time of this sending attempt
    • attemptStatus — Outcome of this attempt (success, failed)
    • errorDetails — Error message or reason for failure (null on success)

GET — List Outbound Transactions In Transmission

Path: /api/outbound/in-transmission

Returns all outbound transactions that are not yet in a final state.

Response: List of outbound transactions with summary fields:

  • sbdhInstanceID — Peppol SBDH Instance Identifier
  • transactionType — business_document or mls_response
  • senderID — Peppol Participant ID of the sender
  • receiverID — Peppol Participant ID of the receiver
  • docTypeID — Peppol Document Type Identifier
  • processID — Peppol Process Identifier
  • status — Current transaction status
  • attemptCount — Total number of sending attempts so far
  • createdDT — When the transaction was created
  • errorDetails — Summary error from the last failed attempt (null on success)
  • mlsStatus — MLS response reception status (only for business_document)

This includes transactions with status: pending, sending, failed (awaiting retry). It excludes rejected, sent, and permanently_failed.

Inbound APIs

POST — Report Inbound Message for Peppol Reporting

Path: /api/inbound/report

Triggers the creation of a Peppol Reporting record for a previously received inbound message. Called by the Receiver Backend after it has successfully processed the document.

Query parameters (required):

  • sbdhInstanceID — The SBDH Instance Identifier of the inbound message
  • c4CountryCode — Country code of the final receiver (C4)

Response:

  • status — ok or error
  • errorDetails — Error description if the SBDH Instance ID was not found or reporting was already triggered

Behavior:

  1. Looks up the inbound_transaction by SBDH Instance ID.
  2. Stores the C4 country code on the transaction.
  3. Creates the reporting record using the stored SBDH data + C4 country code.
  4. Updates reporting_status to reported.

GET — Query Inbound Transaction Status

Path: /api/inbound/status/{sbdhInstanceID}

Returns the current status of a specific inbound transaction.

Parameters:

  • sbdhInstanceID — The SBDH Instance Identifier

Response:

  • sbdhInstanceID — Echo of the identifier
  • incomingID — The phase4 Incoming ID
  • c2SeatID — Peppol Seat ID of the sending AP (C2)
  • c3SeatID — Peppol Seat ID of the receiving AP (C3)
  • signingCertCN — Subject CN of the signing certificate
  • as4MessageID — The AS4 Message ID from the inbound message
  • as4Timestamp — AS4 MessageInfo/Timestamp from the incoming AS4 message (UTC). MLS Milestone M1 for business documents; M2 for MLS messages.
  • senderID — Peppol Participant ID of the sender
  • receiverID — Peppol Participant ID of the receiver
  • docTypeID — Peppol Document Type Identifier
  • processID — Peppol Process Identifier
  • documentSize — Size of the received SBD in bytes
  • documentHash — SHA-256 hash of the received SBD payload
  • c4CountryCode — C4 country code (null if not yet reported)
  • isDuplicateAS4 — Duplicate detected on AS4 Message ID level
  • isDuplicateSBDH — Duplicate detected on SBDH Instance Identifier level
  • status — Current transaction status (received, rejected, forwarding, forwarded, forward_failed, permanently_failed)
  • attemptCount — Total number of forwarding attempts
  • receivedDT — When the message was received
  • completedDT — When successfully completed (null if not yet)
  • reportingStatus — Whether reporting has been triggered (pending, reported)
  • nextRetryDT — Planned date/time of the next forwarding retry (null unless status is forward_failed)
  • errorDetails — Summary error from the last failed forwarding attempt
  • mlsTo — MLS_TO target participant ID (from SBDH extension, null if not set)
  • mlsType — MLS sending strategy (FAILURE_ONLY or ALWAYS_SEND)
  • mlsResponseCode — MLS response code sent or to be sent (RE, AP, AB, null if not yet determined)
  • mlsOutboundTransactionID — ID of the outbound transaction representing the MLS sending (null if not yet created)
  • forwardingAttempts — List of forwarding attempts, each with:
    • attemptDT — Date/time of this forwarding attempt
    • attemptStatus — Outcome of this attempt (success, failed)
    • errorCode — Machine-readable error code classifying the failure (null on success)
    • errorDetails — Error message or reason for failure (null on success)

GET — List Inbound Transactions In Processing

Path: /api/inbound/in-processing

Returns all inbound transactions that are not yet in a final state.

Response: List of inbound transactions with summary fields:

  • sbdhInstanceID — Peppol SBDH Instance Identifier
  • as4MessageID — The AS4 Message ID from the inbound message
  • incomingID — The phase4 Incoming ID
  • senderID — Peppol Participant ID of the sender
  • receiverID — Peppol Participant ID of the receiver
  • docTypeID — Peppol Document Type Identifier
  • processID — Peppol Process Identifier
  • status — Current transaction status
  • attemptCount — Total number of forwarding attempts
  • receivedDT — When the message was received
  • reportingStatus — Whether reporting has been triggered (pending, reported)
  • errorDetails — Summary error from the last failed forwarding attempt (null on success)
  • mlsType — MLS sending strategy (FAILURE_ONLY or ALWAYS_SEND)
  • mlsResponseCode — MLS response code sent or to be sent (RE, AP, AB, null if not yet determined)

This includes transactions with status: received, forwarding, forward_failed (awaiting retry). It excludes rejected, forwarded, and permanently_failed.

GET — List Inbound Transactions Missing C4 Country Code (since v0.1.3)

Path: /api/inbound/missing-c4-country-code

Returns all forwarded inbound transactions for which the C4 country code has not yet been determined. Only includes transactions in status forwarded where reporting is still pending.

Response: List of inbound transactions (same fields as the inbound status response). Check the c4CountryCode field — it will be null for all returned entries.

Useful for monitoring whether all forwarded transactions have received a C4 country code (either via automatic determination or the async reporting API).

GET — Check Specific Transaction for Missing C4 Country Code (since v0.1.3)

Path: /api/inbound/missing-c4-country-code/{sbdhInstanceID}

Checks whether a specific inbound transaction is still missing a C4 country code.

Parameters:

  • sbdhInstanceID — The SBDH Instance Identifier

Response:

  • 200 OK — The C4 country code is still missing. Returns the full inbound transaction details (same fields as the inbound status response).
  • 204 No Content — The transaction exists and the C4 country code is already set (not missing).
  • 404 Not Found — No transaction with this SBDH Instance ID exists.

MLS APIs

GET — List Inbound Transactions Missing MLS Response

Path: /api/mls/missing

Returns all inbound business document transactions for which no MLS response has been sent yet (mls_response_code IS NULL). Excludes incoming MLS messages themselves.

Response: List of inbound transactions (same fields as the inbound status response).

Useful for monitoring whether all received business documents have been properly acknowledged via MLS.

GET — MLS-1 SLA Report (Receiving Side)

Path: /api/mls/sla/mls1

Returns the MLS-1 SLA report measuring M2 - M1: the time between receiving the original business document at this AP (M1) and successfully sending the MLS response back to C2 (M2). Per Peppol Network Policy, 99.5% must be within 20 minutes.

Response:

  • totalCount — Total number of MLS responses measured
  • withinSlaCount — Number of responses within the 20-minute threshold
  • compliancePercent — Actual compliance percentage
  • targetPercent — Required target (99.5)
  • thresholdSeconds — SLA threshold in seconds (1200)
  • meetingSla — Whether the target is met (true / false)
  • entries — List of individual measurements, each with:
    • sbdhInstanceID — SBDH Instance Identifier of the original business document
    • m1 — M1 timestamp (AS4 timestamp of the received business document)
    • m2OrM3 — M2 timestamp (AS4 timestamp of the successful MLS response sending attempt)
    • durationSeconds — Duration in seconds (M2 - M1)
    • withinSla — Whether this entry is within the threshold

GET — MLS-2 SLA Report (Sending Side)

Path: /api/mls/sla/mls2

Returns the MLS-2 SLA report measuring M3 - M1: the time between successfully sending a business document from this AP (M1) and receiving the MLS response from C3 (M3). Per Peppol Network Policy, 99.5% must be within 25 minutes.

Response: Same structure as MLS-1 report, but with thresholdSeconds = 1500 (25 minutes) and m2OrM3 representing M3 (the MLS reception timestamp).

Peppol Reporting APIs

GET — Create TSR (Transaction Statistics Report)

Path: /api/reporting/create-tsr/{year}/{month}

Creates a TSR (Transaction Statistics Report) for the provided year/month. Returns the report as XML.

Path parameters (required):

  • year — The year (e.g., 2026)
  • month — The month (e.g., 3)

Response: TSR XML document (application/xml)

Note: Requires a Peppol Reporting backend to be configured.

GET — Create EUSR (End User Statistics Report)

Path: /api/reporting/create-eusr/{year}/{month}

Creates an EUSR (End User Statistics Report) for the provided year/month. Returns the report as XML.

Path parameters (required):

  • year — The year (e.g., 2026)
  • month — The month (e.g., 3)

Response: EUSR XML document (application/xml)

Note: Requires a Peppol Reporting backend to be configured.

GET — Create, Validate, Store and Send Reports

Path: /api/reporting/do-peppol-reporting/{year}/{month}

Creates, validates, stores and sends both TSR and EUSR reports for the provided year/month in one call.

Path parameters (required):

  • year — The year (e.g., 2026)
  • month — The month (e.g., 3)

Response: XML result (application/xml)

Note: Requires a Peppol Reporting backend to be configured.

Management APIs

GET — Status

Path: /management/status

Returns non-sensitive configuration values, version information, and runtime metadata as a JSON object. Intended for health probes, dashboards, and operational tooling.

Authentication: None — the management path is not protected by the API token. Restrict access at the reverse proxy level if needed.

Response: application/json

Example response (abbreviated):

{
  "build.version": "0.1.2",
  "build.timestamp": "2026-03-27T14:30:00Z",
  "startup.datetime": "2026-03-27T14:31:05+00:00",
  "status.datetime": "2026-03-27T15:00:00+00:00",
  "version.java": "21.0.2",
  "version.phase4": "4.4.1",
  "version.peppol-commons": "12.4.0",
  "peppol.stage": "test",
  "peppol.owner.seatid": "POP000001",
  "peppol.owner.countrycode": "AT",
  "peppol.identifier.mode": "strict",
  "peppol.sending.enabled": true,
  "peppol.receiving.enabled": true,
  "forwarding.mode": "http_post_sync",
  "storage.mode": "filesystem",
  "mls.sending.enabled": true,
  "mls.type": "ALWAYS_SEND",
  "verification.inbound.enabled": false,
  "verification.outbound.enabled": false,
  "peppol.reporting.schedule.enabled": true,
  "proxy.http.configured": false,
  "proxy.http.username.configured": false,
  "duplicate.detection.as4.mode": "reject",
  "duplicate.detection.sbdh.mode": "reject"
}

When the status endpoint is disabled via management.status.enabled=false, the response is:

{
  "status.enabled": false
}

Notes

  • All /api/* endpoints require the X-Token header matching the configured phase4.api.requiredtoken value. If the token is not configured, API authentication is disabled.
  • The /management/* endpoints do not require API token authentication.
  • All responses are JSON.

It is appreciated if you star the GitHub project if you like it.

Donation link: https://paypal.me/PhilipHelger

Clone this wiki locally