API example: onboarding a partner

This page walks through adding a new AS2 partner with the REST API, from nothing to a test message. It does with curl what the AS2 example does in the web UI. How requests and errors work is in REST API basics.

Before you start

This example sends files to a new partner, ACME. It assumes these already exist:

• An organization mycompany with ID 1 and an AS2 profile, with its own certificate and private key. See organization AS2 profile.
• An AS2 sender instance named sender_main.
• A file poller instance named outbox, with the path pattern {to}/{filename}.
• An API token of a service account.
• ACME’s public certificate in the file acme.crt, and their AS2 ID and URL.

Set two shell variables, so the commands stay short:

API=http://localhost:8080/api/v1
AUTH="Authorization: Bearer $ACCESS_TOKEN"

Step 1: Add the partner

curl -X POST -H "$AUTH" -H "Content-Type: application/json" $API/partners \
  -d '{"name": "acme", "display_name": "ACME Corporation"}'

The answer is 201 with the stored partner. Note its id:

{"data":{"id":1,"name":"acme","display_name":"ACME Corporation",...},"error":null}

A partner named acme that already exists is 409 CONFLICT.

Step 2: Upload the partner’s certificate

The upload is a form, so it uses multipart/form-data and needs the X-Requested-With header:

curl -X POST -H "$AUTH" -H "X-Requested-With: XMLHttpRequest" \
  -F "description=ACME" -F "[email protected]" $API/certificates

The answer is 201 with the certificate. Note its id:

{"data":{"id":2,"description":"ACME","common_name":"ACME",...},"error":null}

If the certificate is already stored, the answer is 409 CERTIFICATE_EXISTS. Use the ID in details.existing_id instead.

Step 3: Create the partner’s AS2 profile

The profile belongs to the partner by business_partner_id. Give at least the partner’s AS2 ID, their URL and their certificate:

curl -X POST -H "$AUTH" -H "Content-Type: application/json" $API/as2/remote-profiles \
  -d '{"business_partner_id": 1, "as2id": "ACME", "endpoint": "https://as2.acme.example/as2", "partner_certificate_id": 2}'

Every field you leave out gets the secure default of the web form. Messages are compressed, signed and encrypted, and MicroB2B asks for a signed receipt (MDN) right away. To change a default, add its field to the body. The fields are explained in partner AS2 profile.

If a check fails, the answer is 400 INVALID_INPUT, with the reason per field in details.

Step 4: Check the connection

Ask the sender to try ACME’s URL. This does not send a message:

curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  $API/as2/remote-profiles/1/check-connection -d '{"sender": "sender_main"}'

The answer is 200 with ok and the result of each step: certificates, resolve, connect, tls and http. When ok is false, problem says what failed first. If the sender is not running, the answer is 503 SENDER_NOT_RUNNING. See testing a partner.

Step 5: Add a route

Send the files that the outbox poller picks up for acme to the AS2 sender:

curl -X POST -H "$AUTH" -H "Content-Type: application/json" $API/routes \
  -d '{"source_plugin": "outbox", "from": "*", "to": "acme", "target_plugin": "sender_main"}'

A route that covers this one already exists if you route outbox to sender_main from Any to Any. Then this request is refused with 400 INVALID_INPUT on to, and you can skip this step. See routes.

Step 6: Send a test message

Send a small text file that MicroB2B makes up:

curl -X POST -H "$AUTH" -H "Content-Type: application/json" \
  $API/as2/remote-profiles/1/test-message -d '{"sender": "sender_main", "organization": "mycompany"}'

The answer is 201 with the new message’s message_id, status and file_name. You may leave out sender and organization when the partner’s routes name only one, or only one exists.

Step 7: Follow the message

Read the message to see its status, deliveries and history:

curl -H "$AUTH" $API/messages/$MESSAGE_ID

A message that ACME received and confirmed has the status Delivered. List all messages to ACME, or the ones that failed:

curl -H "$AUTH" "$API/messages?to=acme"
curl -H "$AUTH" "$API/messages?to=acme&status=Error"

To watch changes as they happen, open the event stream:

curl -N -H "$AUTH" $API/events

What each status means is in messages.

Sending real files

From now on, a file you place in the acme folder under the outbox poller’s base directory goes to ACME. To send one file through the API instead, send it by hand:

curl -X POST -H "$AUTH" -H "X-Requested-With: XMLHttpRequest" \
  -F "from=mycompany" -F "to=acme" -F "[email protected]" $API/messages

Without a target, MicroB2B uses the one target that the routes from mycompany to acme name.