fulfillmenttools
API documentationIncident ManagementFeedback
Developer Docs
Developer Docs
  • Developer docs
  • Getting Started
    • Quickstart
    • Integration tutorial
      • Adding facilities
      • Adding listings to facilities
      • Configuring stocks
      • Carrier configuration
      • Placing orders
      • Checkout options
      • Distributed Order Management System (Routing)
      • Local fulfillment configuration
    • Free trial
  • Technical Basics
    • Access to fulfillmenttools
    • Feature status
    • Available regions
    • Backup policies
  • Connecting to fulfillmenttools
    • Client SDKs
    • commercetools connect
    • OpenID connect
      • Configure Microsoft Entra ID / Azure Active Directory
      • Configure Keycloak
  • API
    • Core concepts
      • Authentication & authorization
      • API Versioning & lifecycle
      • Assign user to jobs
      • Localization
      • Resource timestamps
      • Custom attributes
      • Article attributes
      • Recordable attributes
      • Data update guarantees
      • Rate limits & scaling
      • Retries
      • Performance on test vs. production systems
      • Load testing
    • API calls
      • Postman
      • cURL
      • GraphQL Explorer
    • GraphQL API
    • RESTful API
      • Pagination interface
      • RapiDoc
      • OpenAPI 3.0 Spec
    • Eventing
      • Structure of an event
      • Available events
        • Event flows
      • Eventing example
      • Event export
  • Integration Guides
    • Address formats for specific carriers
    • Basics
      • Article categories
      • Audits
      • Custom services & bundled line items
      • Facilities
      • Facility groups
      • GDPR configuration
      • Listings
      • Orders
        • Order types
        • Order status
      • Remote configuration
      • Receipts
      • Search
      • Subscribe to events
      • Sticker
      • Stocks
      • Storage locations
      • Tags
      • Users
    • Channel inventory
    • Facility discounts
    • Inbound process
    • Outbound stocks
    • Purchase order
    • Receipt
    • Routing strategy
    • Show sticker to clients
    • Stow jobs
  • More Integration Guides
    • Carrier management
      • Introduction to carrier configuration
      • Required data when operating carriers
      • Adding & connecting carriers to facilities
      • Custom carrier
    • Configurations for order fulfillment
      • Picking configuration
      • Packing configuration
      • Handover configuration
      • Printing and document configuration
      • Packing container types
      • Parcel tag configuration
      • Headless order fulfillment
      • Short-pick reasons
      • External documents in order fulfillment
      • Service jobs
      • Load units
      • Running sequence
    • DOMS - distributed order management system (routing)
    • External actions
    • Interfacility transfer
    • Notifications
    • Availability & promising
    • Returns
Powered by GitBook
On this page
  • Adding an external document
  • Assigning documents to sections
  • Adding placeholder documents
  • Updating the document
  • Reference
Edit on GitHub
  1. More Integration Guides
  2. Configurations for order fulfillment

External documents in order fulfillment

Last updated 5 months ago

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

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

Place an

Full specification of the endpoint in our

Eventing tutorial
Order
fulfillmenttools API