Transactions

A transaction describes a single exchange of business document(s) between the first and fourth corners in the eDelivery network. Each transaction has a direction, which in Arratech's nomenclature is either to network or from network. To network implies a sent document transaction from the user's point of view, i.e. C1 to C4, while from network implies a received document, C4 to C1.

Artefacts

Each transaction has a set of artefacts tied to it. One of the artefacts represents the business document and the other one describes various steps of the transaction process. The following artefact types are available:

• BUSINESS_DOCUMENT: The sent/received document.
• VALIDATION_RESULT: The validation result for the incoming/outgoing document.
• TRANSACTION_RECEIPT: The receipt for the transaction.

Document Retention

Arratech by default stores each transaction and its related documents and artefacts for 90 days. A limited set of transaction data is persisted for a longer time for accountability purposes.

Transaction Status and Failure Handling

Transaction lifecycle

Every transaction has a transactionStatus field that reflects where it is in the delivery process:

• UNPROCESSED — received but not yet picked up for processing.
• PROCESSING — being sent through the Peppol network.
• COMPLETED — successfully delivered.
• FAILED — delivery failed; check serviceError for details.

For inbound transactions (FROM_NETWORK), FAILED means the document arrived but could not be processed.

Polling vs webhooks

Do not poll in a tight loop. Subscribe to the transaction.received webhook for inbound documents. For outbound transactions, polling GET /orgs/:orgId/transactions/:transactionId is acceptable — use a reasonable interval, for example every 30 seconds for up to 10 minutes.

Reading a failure

When transactionStatus === 'FAILED', the serviceError object is populated:

• code — TXE-1xxx code identifying the specific failure.
• message — a human-readable explanation suitable to show directly to your customer.
• category — the type of failure.

TXE error categories:

Retry guidance

Use the Action field from the TXE code table to decide how to respond:

• RETRY — safe to retry; use exponential backoff.
• FIX_AND_RETRY — customer needs to correct something before retrying.
• CONTACT — escalate to support.
• DO_NOT_RETRY — security concern; stop and alert.

See Transaction Processing Error Codes for the full code list and Action values.

Arratech eDelivery Transactions Overview

Transaction Direction

• Transaction: A single exchange of business document(s) between corner 1 (C1) and corner 4 (C4) in the eDelivery network.
• Directions:
  • TO_NETWORK: Outbound from your system (C1 → C4). You are sending a document into the Peppol network.
  • FROM_NETWORK: Inbound to your system (C4 → C1). You are receiving a document from the Peppol network.

Transaction Artefacts

Each transaction has associated artefacts:

• BUSINESS_DOCUMENT
  • The actual sent/received business document.
  • For outbound, this is the SBD (Standard Business Document) you upload.
• VALIDATION_RESULT
  • The result of validating the incoming/outgoing document against Peppol rules.
• TRANSACTION_RECEIPT
  • A receipt confirming the transaction processing outcome.

Document Retention

• Full transaction data and artefacts are stored for 90 days by default.
• A limited subset of transaction data is retained longer for accountability/audit purposes.

---

Standard Business Document (SBD)

When sending a transaction you upload an SBD (Standard Business Document):

• Body: Contains your Peppol UBL payload (e.g. UBL Invoice).
• Header (SBDH): GS1 Standard Business Document Header containing routing metadata:
  • Sender Peppol ID
  • Receiver Peppol ID
  • Document type identifier
  • Process identifier

The Peppol network uses the SBDH for routing without parsing the UBL payload.

Most Peppol toolkits can generate the SBD wrapper. For full specification, see the Peppol AS4 documentation (SBD/SBDH spec).

Sending a transaction

There are two ways to upload a business document:

Direct upload (small/medium documents)

Use POST /orgs/:orgId/transactions and send the XML content directly in the request body. Include the ap query parameter to select which Access Point to use. This is the simplest approach and works for most documents.

Presigned URL (large documents)

Two-step process:

1. GET /orgs/:orgId/transactions/upload_url — returns a presigned S3 URL (valid 30 minutes) and a transactionId.
2. PUT {uploadUrl} — upload the raw XML to that URL. No Authorization header is needed; the presigned URL handles authentication.

The spec does not define a maximum size for the direct upload path. If you are sending large documents (several MB or more), use the presigned URL method to avoid timeout or size limit issues.

Validating a document before sending

Use POST /validator/validate to validate a document against Peppol rules before uploading it. The endpoint accepts raw XML (Content-Type: application/xml).

The optional ruleset query parameter selects which version of the Peppol validation rules to apply:

• current (default) — the official Peppol ruleset in production
• latest — the most recent ruleset, which may include pre-release updates
• legacy — the previously active ruleset, kept for backward compatibility

The response (ValidationResult) includes:

• status — OK or FAILED
• runtime — validation time in milliseconds
• sections[] — each section has a configuration identifier and an assertions[] array. Each assertion has an identifier, a flag (SUCCESS, WARNING, ERROR, FATAL, etc.), and a human-readable text.

Fix any FATAL or ERROR assertions before sending. WARNING flags may pass delivery depending on ruleset strictness.

Lowest role: user