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 process document

post

This part of the API is in Beta status. For details please check the api-release-life-cycle documentation.

Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
processIdstringRequired
Body

ExternalDocumentForCreation

prioritynumberOptional
sectionstring · enumRequired

Section

Possible values:
typestring · enumRequired

DocumentType

Possible values:
Responses
post
/api/processes/{processId}/documents
POST /api/processes/{processId}/documents HTTP/1.1
Host: your-tenant-name.api.fulfillmenttools.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1076

{
  "file": {
    "content": "JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg==",
    "name": "example.pdf"
  },
  "priority": 1,
  "section": "ORDER",
  "type": "PDF"
}
{
  "id": "text",
  "name": "text",
  "path": "text",
  "priority": 1,
  "section": "ORDER",
  "type": "PDF",
  "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

PreviousHandover JobsNextConfigurations

Last updated

Was this helpful?