Inventory Deliveries Download

Once authorised, a client can download inventory deliveries belonging to any of its sites via the TWeb Public API. Inventory deliveries are returned in a JSON list. The process of downloading inventory deliveries may involve three requests to the Public API:

1. A request to obtain a batch number for the download
2. Requests to obtain the inventory deliveries for the batch
3. Requests to tag inventory deliveries as received (this is optional)

When the client makes a request to obtain the batch number (Step 1) it also submits filters to specify which inventory deliveries are to be included in the batch. Once the client receives the batch number, then it can use this number to make multiple requests to obtain inventory deliveries for the batch (Step 2). Each request is limited to a maximum of 100 records and the client must specify the start and end indexes for the inventory deliveries to be downloaded. After each set of inventory deliveries have been received and correctly stored (Step 2), the client may wish to tag the inventory deliveries as received (Step 3). The tag status of an inventory delivery can be used as a filter during Step 1. This is useful if a client simply wants to download any inventory deliveries it has not previously received.

Step 1 - Requesting an Inventory Deliveries Batch Number

The endpoint depends on the server used by your company to login to TWeb:

The endpoint only accepts HTTP POST requests. The following POST parameters must be included with the request:

accessToken

Note that the Access Token may be submitted as a POST parameter or as a HTTP Cookie.

The following POST parameters may optionally be submitted with the request:

targetID
filterStartDatetime
filterEndDatetime
filterTaggedDeliveries
filterSiteNumber
filterTankNumber

For details regarding the Target ID, please refer to the following article: https://help.tweb.com.au/TWebPublicAPI/en/Authorisation/Execute#heading_request

filterStartDatetime is an optional POST parameter. This parameter specifies the lower time-limit (inclusive) for inventory deliveries included in the batch. For example, if set to 11:59PM on 31 Jan 2018 then only inventory deliveries occurring on and after this date and time will be included in the batch. The filterStartDatetime has the following validation rule specifications:

filterEndDatetime is an optional POST parameter. This parameter specifies the upper time-limit (inclusive) for inventory deliveries included in the batch. For example, if set to 11:59PM on 31 Jan 2018 then only inventory deliveries occurring before and on this date and time will be included in the batch. The filterEndDatetime has the following validation rule specifications:

filterTaggedDeliveries is an optional POST parameter. This parameter specifies whether to return inventory deliveries that have previously been downloaded via the Public API or not. It has the following validation rule specifications:

filterSiteNumber is an optional POST parameter. This parameter specifies the site where inventory deliveries occurred. Site Numbers are allocated to all sites by TT. A list is available via TWeb. This filter has the following validation rule specifications:

filterTankNumber is an optional POST parameter. This parameter specifies the tank number where inventory deliveries occurred. This filter has the following validation rule specifications:

Request Examples

A request for the Batch Number that includes the Access Token from the file where it was stored during authorisation:

curl -b cookiejar.txt -skX POST -d "targetID=abc123&filterStartDatetime=2018-01-31 23:59:00&filterEndDatetime=2018-03-01 00:00:00&filterTaggedDeliveries=UntaggedOnly&filterSiteNumber=123456" https://publicapi.tweb.com.au/v1/DeliveriesBatchNumber

A request for the Batch Number that includes the Access Token as a POST parameter in the body:

curl -skX POST -d "accessToken=0123456789ABCDEF0123456789ABCDEF01234567&targetID=abc123&filterStartDatetime=2018-01-31 23:59:00&filterEndDatetime=2018-03-01 00:00:00&filterTaggedDeliveries=UntaggedOnly&filterSiteNumber=123456" https://publicapi.tweb.com.au/v1/DeliveriesBatchNumber

Step 1 - Response

The response from the Batch Number endpoint has the following JSON format:

{
    "Data": {
        "Items": [
            {
                "NewBatchNumber": 123
            }
        ],
        "Meta": {
            "Endpoint": "/v1/DeliveriesBatchNumber",
            "SubmittedFilters": {
                "filterEndDatetime: "2018-03-01 00:00:00",
                "filterSiteNumber": "123456",
                "filterStartDatetime": "2018-01-31 23:59:00",
                "filterTaggedDeliveries": "UntaggedOnly"
            },
            "TargetID": "abc123",
            "Title": "Public API: Deliveries Batch Number",
            "TotalRecords": 1000
        }
    },
    "Error": {
        "Code": 0,
        "Status": "OK"
    }
}

The batch number is an integer and is available in the Data.Items[0].NewBatchNumber JSON property.

The total number of inventory deliveries for the given filters is also an integer and is available in the Data.Meta.TotalRecords JSON property.

The Error JSON property is included in all responses from the TWeb Public API. The possible responses when requesting an Inventory Deliveries Batch Number are:

Step 2 - Requesting a Page of Inventory Deliveries

Once the client has the Inventory Deliveries Batch Number, this can be used to download inventory delivery data. The endpoint used for this depends on the server used by your company to login to TWeb:

The endpoint only accepts HTTP POST requests. The following POST parameters must be included with the request:

accessToken
batchNumber
startRecord
endRecord

And the following POST parameters may optionally be submitted with the request:

targetID

Note that the Access Token may be submitted as a POST parameter or as a HTTP Cookie.

The Start Record specifies the record number to begin inventory delivery downloads at. Note that the count begins at 1, not 0, and is inclusive. For example, if set to 1 then inventory delivery record 1 in the batch will be returned as the first record in the result set. The Start Record has the following validation rule specifications:

The End Record specifies the record number to begin inventory delivery downloads at. Note that the count begins at 1, not 0, and is inclusive. For example, if set to 1 then inventory delivery record 1 in the batch will be returned as the last record in the result set. The End Record has the following validation rule specifications:

Furthermore, the Start Record and End Record must satisfy the following condition: (endRecord - startRecord) < 100. Because the start and end records are inclusive, 100 inventory deliveries can be downloaded by setting startRecord=1 and endRecord=100 (not 99 inventory deliveries!).

Request Examples

A request for Inventory Delivery data that includes the Access Token from the file where it was stored during authorisation:

curl -b cookiejar.txt -skX POST -d "targetID=abc123&batchNumber=123&startRecord=1&endRecord=1" https://publicapi.tweb.com.au/v1/Deliveries

A request for Inventory Delivery data that includes the Access Token as a POST parameter in the body:

curl -skX POST -d "targetID=abc123&accessToken=0123456789ABCDEF0123456789ABCDEF01234567&batchNumber=123&startRecord=1&endRecord=1" https://publicapi.tweb.com.au/v1/Deliveries

Step 2 - Response

The response from the Deliveries endpoint has the following JSON format:

{
    "Data": {
        "Items": [
            {
                "TankNumber": 1,
                "Type": 0,
                "Grade": {
                    "GradeNum": 2,
                    "Name": "Unleaded"
                },
                "AmbientQuantity": 1000,
                "AmbientUnitPrice": 1,
                "AmbientAmount": 1000,
                "AmbientTemperature": 0,
                "L15Quantity": 0,
                "L15UnitPrice": 0,
                "L15Amount": 0,
                "DateTime": "2018-03-01T00:00:00",
                "Reference": "",
                "Notes": "",
                "SiteNumber": "123456",
                "RowNumber": 1
            }
        ],
        "Meta": {
            "Endpoint": "/v1/Deliveries",
            "SubmittedFilters": {
                "batchNumber": 123,
                "endRecord": 1,
                "startRecord": 1
            },
            "TargetID": "abc123",
            "Title": "Public API: Download Deliveries"
        }
    },
    "Error": {
        "Code": 0,
        "Status": "OK"
    }
}

The inventory delivery data is returned as a list of objects in Data.Items. Each of the properties of that object are described in the following table:

The Error JSON property is included in all responses from the TWeb Public API. The possible responses when requesting Inventory Delivery data are:

Step 3 - Tagging Inventory Deliveries

Once the client has the Inventory Deliveries Batch Number, this can be used to tag inventory deliveries as received. The endpoint used for this depends on the server used by your company to login to TWeb:

The endpoint only accepts HTTP POST requests. The following POST parameters must be included with the request:

accessToken
batchNumber
startRecord
endRecord

And the following POST parameters may optionally be submitted with the request:

targetID

These POST paramters are identical to those from Step 2, and the same validation rules apply.

Request Examples

A request for Inventory Delivery data that includes the Access Token from the file where it was stored during authorisation:

curl -b cookiejar.txt -skX POST -d "targetID=abc123&batchNumber=123&startRecord=1&endRecord=1" https://publicapi.tweb.com.au/v1/TagDeliveries

A request for Inventory Delivery data that includes the Access Token as a POST parameter in the body:

curl -skX POST -d "targetID=abc123&accessToken=0123456789ABCDEF0123456789ABCDEF01234567&batchNumber=123&startRecord=1&endRecord=1" https://publicapi.tweb.com.au/v1/TagDeliveries

Step 3 - Response

The response from the Inventory Deliveries endpoint has the following JSON format:

{
    "Error": {
        "Code": 0,
        "Status": "OK"
    },
    "Data": {
        "Meta": {
            "TargetID": "abc123",
            "Title": "Public API: Tag Deliveries",
            "Endpoint": "/v1/TagDeliveries",
            "SubmittedFilters": {
                "batchNumber": 123,
                "startRecord": 1,
                "endRecord": 1
            }
        },
        "Items": []
    }
}

The Error JSON property indicates whether the inventory delivery tagging was successful or not. The possible responses when requesting Inventory Delivery data are the same as in Step 2, with one additional possible Error response: