Transactions

The corners, in plain words. Peppol names the parties in every exchange:
C1 – the sender: the business that sends the document (you, when you send).
C2 – the sender's access point: Arratech when you send; your counterparty's provider when they send to you.
C3 – the receiver's access point: Arratech when you receive; your counterparty's provider when you send to them.
C4 – the receiver: the business that gets the document (you, when you receive).
C5 – the tax authority's access point: receives tax data where a country requires it.
A document always travels C1 → C2 → C3 → C4. Its delivery status goes back from C3 to C2.

Which field in a transaction is which corner:

Transactions, directions and artefacts

A transaction is a single exchange of business documents between the first and fourth corners of the eDelivery network. Each transaction has a direction. TO_NETWORK means you send the document and are C1. FROM_NETWORK means you receive it and are C4.

Each transaction has artefacts, which are the document itself and records of the steps it went through:

• BUSINESS_DOCUMENT: the sent or received document. For outbound transactions this is the SBD you upload.
• VALIDATION_RESULT: the result of validating the document against Peppol rules.
• TRANSACTION_RECEIPT: a receipt confirming the outcome of the transaction.

Document retention

Arratech stores each transaction and its artefacts for 90 days by default. A limited set of transaction data is kept longer for accountability and audit.

Status and failure handling

Transaction lifecycle

A transaction moves from waiting, through processing, to a final state: completed or failed. The transactionStatus field shows where it is, and the full list of statuses and what each means is in the API reference. Some outbound documents are deliberately not delivered on the network. Read the status description in the reference before you treat any final status as the same as "delivered".

Polling vs webhooks

Do not poll in a tight loop. Subscribe to the transaction.received webhook for inbound documents. For outbound transactions, polling the transaction is acceptable. Use a reasonable interval, for example every 30 seconds for up to 10 minutes.

Reading a failure

When a transaction has failed, its serviceError holds a TXE-1xxx code, a message you can show directly to your customer, and a category. Each code also has an Action that tells you what to do: retry with exponential backoff, fix the input and retry, contact support, or stop and alert (a security concern). The full list of codes and categories is in the Transaction Processing Error Codes section of the API reference.

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. Send the XML in the request body and choose the access point with the ap query parameter. This is the simplest option and works for most documents.
• Presigned URL. For large documents (several MB or more), first ask for a presigned upload URL, then upload the raw XML to that URL. The URL already carries its own authorisation, so no Authorization header is needed. Use this to avoid timeouts and size limits.

Validating a document before sending

You can validate a document against the Peppol rules before you upload it, and you can choose which version of the rules to apply. Fix any FATAL or ERROR assertions before sending. WARNING flags may still pass delivery, depending on how strict the ruleset is.

Webhooks

Webhooks push notifications to you when events happen in Arratech's solution. You register a callback URL on a server you control, and Arratech calls it each time a matching event occurs.

Your callback handler must respond with a 2xx status for a successful delivery. The response body is not evaluated. If your processing takes time, return the response straight away and handle the payload asynchronously. If your handler is unavailable, Arratech retries the delivery. If you still miss an event, for example after a long outage, you can list the events you missed afterwards. Events are kept for a limited time. The set of events grows over time. The current list, delivery rules and how to verify signatures are in the Webhooks and Webhook Events sections of the API reference.

In the API reference

• Transactions
• Validator
• Webhooks
• Webhook Events
• Transaction Processing Error Codes