Add External Documents

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.

A typical use case is to attach a branded invoice document, which is generated outside of the fulfillmenttools platform. Such a document could be uploaded to the process at a specific point in time to be printed and added to the parcel operationally.

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"
}

3. Add the invoice document to the process:

Create a new document on this process

POST/api/processes/{processId}/documents

Path parameters

processId*string

Body

application/json

type*DocumentType (enum)

PDFPNGJPGGIFJPEG

section*Section (enum)

ORDERPACKJOBPICKJOBHANDOVERJOBPARCEL

fileNamedFile (object)

prioritynumber

Response

201400

The document was successfully created

Body

application/json

createdstring (date-time)

The date this entity was created at the platform. This value is generated by the service.

lastModifiedstring (date-time)

The date this entity was modified last. This value is generated by the service.

version*integer (int64)

The version of the document to be used in optimistic locking mechanisms.

Request

JavaScriptCurl

const response = await fetch('/api/processes/{processId}/documents', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "type": "PDF",
      "section": "ORDER"
    }),
});
const data = await response.json();

Response

{
  "type": "PDF",
  "section": "ORDER",
  "name": "text",
  "path": "text",
  "id": "text",
  "priority": 0
}

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",
    ...
}

3. 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"
  }'

4. 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