Docket Creation API

Created by Mark Shepherd-Smith, Modified on Tue, 06 Jun 2023 at 02:03 PM by Lachlan Robbie

Introduction

Docketbook supports the programmatic creation and routing of dockets between suppliers, contractors and customers in the construction industry. Dockets can be created from calls made to REST API end points and routed to the appropriate person or project, either internal or external to the Docketbook environment.

Dockets are routed to the correct location based on either Dockebook Project ID, Docketbook Company ID + PO Number or email address / mobile phone number.

Routing dockets via Docketbook brings the benefits of remote device signing of dockets (contactless signing), independent verification of docket delivery and on-platform issue resolution.

This document provides guidance around the technical expectations of those interacting with the third-party docket creation API. The intent of this API is to strike a balance between capturing the dockets of our mutual customers in an efficient way whilst ensuring that authenticity needs are met.

Functional Overview

While the focus of this document is technical in nature, this section is intended to provide a high-level functional overview of the process described herein.

Docket Creation

Dockets are created by the ingestion of JSON or XML formatted data to an authenticated API end point. Dockets consist of a set of required information including Customer, Date, Line Item Descriptions, quantities and units of measure. In addition, dockets may contain custom information such as water quantities or lot numbers. These can be defined in the Docket Template and populated using the appropriate tags in the data payload.

Docket Routing

Dockets can be routed to parties both ‘on Docketbook’ and off-platform. For Docketbook customers, the payload must contain either the Organisation Group ID referring to the receiving project, or the Organisation ID of the receiving company and a Purchase Order number to route the docket to on the customer side.

For off-platform routing, each docket must contain either a recipient email address or mobile phone number. This will deliver the docket as a linked PDF to the recipient email or text message. The recipient will also have access to their docket history by creating an account on Docketbook.

Verification of Receipt

Docketbook supports contactless signing of dockets for dockets received both on an off platform. Signed PDFs are available to both parties (either on platform or via API call).

Further, Docketbook supports a cross-company Accept/Reject process. For customers on platform, the user can accept, or more importantly, reject a docket and the issue resolution process can address docket issues prior to invoicing.

Finally, each docket is supported by an audit log, which records when, and by whom, dockets were sent, signed and accepted/rejected.

Data Exchange

General Information

This API consists of a series of HTTPS REST based endpoints that accept different data formats depending on the preference of the integrating partner. Partners will be identified by way of shared secrets that are included in the headers of requests sent to the API. Future development may see the use of access keys that are used to sign the request. It is expected that partners secure their key material appropriately and in the event of a breach, Docketbook will work with the partner to cycle the affected keys.

Acceptable Formats

JSON

The default format expected will be JSON. The below example sets out a single docket sent by the integration partner for routing to a customer.

{
    "customerContact": {
        // Friendly display name - as the customer would expect to see
        "displayName": "ACME Customer",
        // Optional and can be omitted.
        "physicalAddress": {
            streetNum: "32",
            streetName: "Building Street",
            suburb: "Town",
            state: "Queensland",
            postCode: "4000",
            country: "Australia",
        },
        // Can be AU phone numbers in international format, email addresses
        // or @on.docketbook.io addresses for direct routing.
        "addresses": [
            "+61755555555",
            "customer@on.docketbook.io",
        ]
    },
    "date": "2020/02/01",
    // The identification string for this docket from the supplier side.
    "docketNumber": "DKT-231",
    // Optional and will default to Import Bot if not supplied.
    "operator": "John Smith",
    // Optional
    "customerRefNo": "CUST-PO-1",
    // Optional
    "supplierRefNo": "SUPP-ORDER-1",
    "items": [{
        "resourceName": "My Product",
        "resourceId": "PROD-0-001",
        // Uses the abbreviation of the UOM to match against the UOM configured
        // in Docketbook
        "unitOfMeasure": "T",
        // Both a string and numeric value is accepted. A string can be used
        // if decimal quantities are handled
        "quantity": 23,
        // Optional and will default to time of ingestion. ISO8601 timestamp
        // format. Recommend the inclusion of the time zone.
        "timestamp": "2020-05-20T02:30:35+00:00",
    }],
    // fieldID is available as part of the Docket Template definition.
    "customFieldValues": [{
        "fieldId": "cd8c63e0-ab30-4673-9554-f976e52c2fee",
        "value": "Lot 7"
    }]
}

A full request payload would look like:

{
    "organisationId": "cd8c63e0-ab30-4673-9554-f976e52c2fee",
    "organisationGroupId": "cd8c63e0-ab30-4673-9554-f976e52c2fee",
    "dockets": [...]
}

XML

The XML format mimics the JSON format defined above, which would look like the following

<?xml version="1.0" encoding="UTF-8"?>
<root>
   <customFieldValues>
      <element>
         <fieldId>cd8c63e0-ab30-4673-9554-f976e52c2fee</fieldId>
         <value>Lot 7</value>
      </element>
   </customFieldValues>
   <customerContact>
      <addresses>
         <element>+61755555555</element>
         <element>customer@on.docketbook.io</element>
      </addresses>
      <displayName>ACME Customer</displayName>
      <physicalAddress>
         <country>Australia</country>
         <postCode>4000</postCode>
         <state>Queensland</state>
         <streetName>Building Street</streetName>
         <streetNum>32</streetNum>
         <suburb>Town</suburb>
      </physicalAddress>
   </customerContact>
   <customerRefNo>CUST-PO-1</customerRefNo>
   <date>2020/02/01</date>
   <docketNumber>DKT-231</docketNumber>
   <items>
      <element>
         <quantity>23</quantity>
         <resourceId>PROD-0-001</resourceId>
         <resourceName>My Product</resourceName>
         <timestamp>2020-05-20T02:30:35+00:00</timestamp>
         <unitOfMeasure>T</unitOfMeasure>
      </element>
   </items>
   <operator>John Smith</operator>
   <supplierRefNo>SUPP-ORDER-1</supplierRefNo>
</root>

Receiver Discovery Process

There are N methods by which customer matching takes place, each with its own advantages/tradeoffs. It is up to the partner to decide which method best suits their needs based on the experience they want for the mutual customer and how their internal systems make data available for export. The different options depend on how explicit the partner wants to be about docket routing.

Note that use of the overarching “organisation” or “organisationGroup” fields should be targeted at customers known to be on-platform and be customer specific.

Customer Organisation Group

A customer organisation group would be generally analogous to an organisation unit, functional division or project. It is identified either via a UUID or via a pseudo email address, both of which are Docketbook assigned.

In the email address case, it can be included in the “addresses” element of each docket entry.

{
    "customerContact": {
        // Friendly display name - as the customer would expect to see
        "displayName": "ACME Customer",
        // Can be AU phone numbers in international format, email addresses
        // or @on.docketbook.io addresses for direct routing.
        "addresses": [
            "+61755555555",
            "customer@on.docketbook.io",
        ]
    }
}

Alternatively the UUID can be supplied in the overarching request payload like so

{
"organisationGroupId": "cd8c63e0-ab30-4673-9554-f976e52c2fee",
"dockets": []
}

In the case of both a top level UUID and docket specific contact being specified, the union is taken.

The benefit of this method is that customer dockets are delivered to the most relevant place for processing. This avoids the overhead on the customer side in terms of locating the correct destination for a docket that enters a common receiving point. The downside is that additional data tracking is required on the integration partner side, namely the Organisation Group UUID and/or email addresses need to be stored and included in requests.

Request per Customer Organisation

If the partner is not able to easily track organisation groups, another option is to use the unique identifiers for the receiving organisation. This is also a UUID assigned by Docketbook during creation and its use would look like

{
"organisationId": "cd8c63e0-ab30-4673-9554-f976e52c2fee",
"dockets": []
}

Each organisation on Docketbook also contains a default organisation group, which comes with its own UUID/pseudo email address. As such, it is also possible to use that email address as part of the customer contact “addresses” field to achieve the same organisation level routing.

Request per Partner

In the event of sending dockets to customers that are not on-platform, the first two options are not available or there is a preference for just using the “addresses” field in the customer contact, a simple request can be used that looks like:

{
"dockets": []
}

In this instance, each docket must individually specify the correct destinations in the “addresses” field of the customerContact.

Extraction and Routing Process

Ingestion

To avoid each partner having to implement retry behavior and have potentially long running requests, dockets submitted to the endpoint will be queued for processing rather than being handled interactively. As such, the endpoint will return a payload like so

// Successful request - HTTP Status Code 200
{
    "submissionId": "cd8c63e0-ab30-4673-9554-f976e52c2fee",
    "queuedDockets": [{
        "docketNumber": "DKT-231",
        "processingId": "7c4d248b-abce-44a6-9916-3b511895b9ab"
    }]
}
// Failed request - HTTP Status Code is not 200
{
    "error": "<help text>"
}

Should a docket fail to process, an error will be raised and stored. A list of failures can be queried like so

// <endpoint>/failures?since=<timestamp>
[{
    "docketNumber": "DKT-231",
    "processingId": "7c4d248b-abce-44a6-9916-3b511895b9ab",
    "submissionId": "cd8c63e0-ab30-4673-9554-f976e52c2fee",
    "transient": true,
    "error": "Temporary issue"
}]

If desired, an email for each non-transient failure can be configured at the partner’s request.

Customer Side Matching

Docketbook supports the concept of orders, which serve as a way to group dockets together in the context of an overarching collection of work, such as a purchase order. As such, it is useful for customers that any dockets ingested for them be matched to orders where possible.

In the event that a customerRefNo is not supplied on the submitted docket, no matching takes place and currently no further processing is done to find the correct destination for a docket. This is not a problem if an organisation group is discoverable for the docket, however if an organisation is used then the docket will be received into a common point, requiring the customer to route it themselves.

If a customerRefNo is supplied, Docketbook will search the destination organisation group (or entire organisation if that is all that is provided) for an order that contains a matching customerRefNo. If one is found, the docket will be routed to that organisation group and associated with that order.