API Specification

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)

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

Parameters (path or query):

• 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)
• mlsTo (optional) — Alternative Peppol participant ID to receive MLS responses
• sbdhStandard (optional) — 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 (optional) — SBDH TypeVersion override (e.g., 0). When omitted, auto-derived from the document type identifier.
• sbdhType (optional) — SBDH Type override (e.g., factur-x). When omitted, auto-derived from the document type identifier.
• payloadMimeType (optional) — 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 (pre-built 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

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

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

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.

Parameters (path or query):

• sbdhInstanceID — The SBDH Instance Identifier of the inbound message
• countryC4 — 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

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

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.

---

Notes

• URL paths and exact parameter encoding (path vs query) will be defined during implementation.
• Authentication/authorization mechanism for the APIs is TBD (e.g., API token via X-Token header as in the standalone project).
• All responses are JSON.