Add External Documents

This page is outdated. Please go to our new documentation under https://docs.fulfillmenttools.com/documentation.

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.

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:

Create a new document on this process

post

Path parameters

processIdstringRequired

Body

typestring · enumRequiredPossible values:

sectionstring · enumRequiredPossible values:

prioritynumberOptional

Responses

201

The document was successfully created

application/json

400

Invalid input. See response for details

application/json

post

HTTPcURLJavaScriptPython

POST /api/processes/{processId}/documents HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 1076

{
  "type": "PDF",
  "section": "ORDER",
  "file": {
    "content": "JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg==",
    "name": "example.pdf"
  },
  "priority": 1
}

{
  "type": "PDF",
  "section": "ORDER",
  "name": "text",
  "path": "text",
  "id": "text",
  "priority": 1,
  "created": "2020-02-03T08:45:51.525Z",
  "lastModified": "2020-02-03T09:45:51.525Z",
  "version": 42
}

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