External documents in order fulfillment

You can add external documents to the process entity so that these documents can be selected for printing in the mobile app or they can be used by other clients to upload or change documents during processing.

If you want to view added external documents in one of our clients, please also check the print / document configuration.

Adding an external document

In this example we are going to add a PDF document to the process using the POST /api/processes/<processId>/documents endpoint. Specifically, we want to add it to the PACKJOB section because in this example, labels and documents should be displayed and printed during Packing.

1. Subscribe to PACK_JOB_CREATED webhook events as described in the Eventing tutorial

2. Retrieve processId from PACK_JOB_CREATED event

{
  "event": "PACK_JOB_CREATED",
  "payload": {
    "id": "24e5d640-4c9b-4643-97fb-6358b2326f37",
    "processId": "a1dfcb9c-ece7-485f-94a9-6620f436e3b2",
    "version": 1,
    "status": "OPEN",
    ...
  },
  "eventId": "7032617849516161"
}

1. Add the invoice document to the process:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/processes/<processId>/documents' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "type": "PDF",
    "section": "PACKJOB",
    "file": {
      "name": "invoice.pdf",
      "content": "JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg=="
    }
  }'

Currently you can only upload files of type PDF.

Assigning documents to sections

Using the section field in the request object, you can assign the document to a specific section. This way you can control in which part of the app the document is displayed, e.g. in the Picking, Packing, or Handover section.

Currently, the following sections are supported: PACKJOB, PICKJOB, HANDOVERJOB

Adding placeholder documents

You can add an (empty) placeholder document early in the process, so when a user opens the printing section and the document is not available yet, at least an information is shown in the "External documents" section.

1. Place an Order

2. Retrieve processId from response

{
    "id": "e476750a-58ea-43ef-9926-97fc8059ff80",
    "status": "OPEN",
    "processId": "0e6ff279-18ec-4eda-b0a8-b775102f1372",
    "created": "2023-02-21T15:42:38.008Z",
    ...
}

1. Add empty document placeholder to the process:

curl -sSL -X POST 'https://your.api.fulfillmenttools.com/api/processes/<processId>/documents' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "type": "PDF",
    "section": "PACKJOB"
  }'

1. Retrieve the document id from the response so you can update it in a second step:

{
    "section": "PACKJOB",
    "type": "PDF",
    "id": "0fa44ab7-ec30-4e19-8e9f-469ab7140ba5",
    "version": 1
}

Adding placeholder documents is optional but recommended, since it improves the usability of the process for picking staff.

Updating the document

Once the final document is available, you can add it to the process entity in a similar fashion, but this time you have to use PUT to modify the document:

curl -sSL -X PUT 'https://your.api.fulfillmenttools.com/api/processes/<processId>/documents/<documentId>' \
  --header 'Authorization: Bearer <TOKEN>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
      "version": 1,
      "file": {
          "name": "invoice.pdf",
          "content": "<base64-encoded file content>"
      }
  }'

Reference

• Full specification of the endpoint in our fulfillmenttools API