Send a Transaction

This tutorial explains how to send a document to the participant you created in the Create a Participant tutorial (or any other participant already created in your organisation). Thus performing a full transaction cycle, sending from C2 and receiving on C3.

If you prefer importing this tutorial into Postman or Insomnia, download the har archive file and import into your preferred tool.

Prerequisites

You must have created a participant to send and receive the transaction. If you not already have one visit the Create a Participant tutorial.

Step 1. Send a Transaction

We will send a transaction with a Peppol BIS Billing UBL Invoice V3 document from our chosen participant to the same participant, thus verifying that we can both send and receive a transaction.

To start with we need an invoice wrapped in a Standard Business Document (SBD). Below is a template SBD we are going to use. Copy this one and modify the yellow marked sections with our participant identifier (as defined in the Create a Participant tutorial) corresponding to your participant and a random UID for Document Instance Identifier.

With the SBD adjusted with the correct sender and receiver data we are ready to send it away! To do this we will use the /orgs/:orgId/transactions?ap=OUR_AP_ID endpoint and specify in the ap query parameter which access point to use as the sending (C2) access point.

In our case we will use Arratech's test AP, which id we already retrieved in the earlier Create a Participant tutorial. If you forgot it, just use the /orgs/:orgId/aps/alltouse endpoint to retrieve it again.

With the AP id sorted out, add it to the query parameter and send the document:

curl -X POST https://api.arratech.com/orgs/YOUR_ORGS_ID/transactions?ap=YOUR_AP_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/xml" \
  -d 'YOUR SBD XML DOCUMENT'

The call will return a transaction id for the sending process that is initiated by the call above. Note this id as you will use it in the next step for polling the status of your transaction.

Note that embedding the SBD inline an http post request is only viable for small documents, the API contains other methods for sending larger documents.

Step 2. Check the Sender (C2) Status

The transaction id from Step 7 is the id for your sent/outgoing transaction from the C2 corner. To check the status we use the /orgs/:orgId/transactions/transactionId endpoint:

curl -X GET https://api.arratech.com/orgs/YOUR_ORGS_ID/transactions/YOUR_TRANSACTION_ID \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The returned transaction contains a number of properties, one interesting is the transactionStatus. After a few seconds it will show COMPLETED meaning that the transaction is successfully sent.

More detailed information about the transaction is found in the /artefacts endpoints for this transaction, for example document validation results. This will be further elaborated in another tutorial.

Step 3. Receive the Transaction

The transaction will be received on the C3 corner and we will use the /orgs/:orgId/transactions/from_network endpoint to pull the received transaction.

curl -X GET https://api.arratech.com/orgs/YOUR_ORGS_ID/transactions/from_network \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

In the returned list you should now be able to find the received transaction, with a docInstanceId property value which matches the Document Instance Identifier you added in the first step.

Step 4. Retrieve the Document

With the transaction at hand we can now download the same business document we already sent. This we do with the /orgs/:orgId/transactions/:transactionId/business_document endpoint

curl -X GET https://api.arratech.com/orgs/YOUR_ORGS_ID/transactions/TRANSACTION_ID/business_document \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Congratulations! You have now both sent and received a document thus completed the full transaction cycle.