Skip to content

API Specification

Jump to bottom
Philip Helger edited this page Feb 24, 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)

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)

Request body: The raw business document (e.g., UBL Invoice XML)

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).

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
  • status — Current transaction status (pending, 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)
  • errorDetails — Summary error from the last failed attempt (null on success)
  • attempts — List of sending attempts, each with:
    • as4MessageID
    • receiptMessageID
    • httpStatusCode
    • attemptDT
    • attemptStatus
    • errorDetails

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
  • senderID
  • receiverID
  • docTypeID
  • processID
  • status
  • attemptCount
  • createdDT
  • errorDetails

This includes transactions with status: pending, sending, failed (awaiting retry). It excludes 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
  • as4MessageID — The AS4 Message ID from the inbound message
  • senderID
  • receiverID
  • docTypeID
  • processID
  • status — Current transaction status (received, forwarding, forwarded, forward_failed, permanently_failed)
  • isDuplicate — Whether this was a duplicate
  • 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
  • c4CountryCode — C4 country code (null if not yet reported)
  • errorDetails — Summary error from the last failed forwarding attempt
  • forwardingAttempts — List of forwarding attempts, each with:
    • attemptDT
    • attemptStatus
    • errorDetails

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:

  • as4MessageID
  • incomingID
  • sbdhInstanceID
  • senderID
  • receiverID
  • docTypeID
  • processID
  • status
  • attemptCount
  • receivedDT
  • reportingStatus
  • errorDetails

This includes transactions with status: received, forwarding, forward_failed (awaiting retry). It excludes 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.

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

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

Clone this wiki locally