Transactions Download

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

1. A request to obtain a batch number for the download
2. Requests to obtain the transactions for the batch
3. Requests to tag transactions 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 transactions 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 transactions 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 transactions to be downloaded. After each set of transactions have been received and correctly stored (Step 2), the client may wish to tag the transactions as received (Step 3). The tag status of a transaction can be used as a filter during Step 1. This is useful if a client simply wants to download any transactions it has not previously received.

Step 1 - Requesting a Transactions 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
filterTaggedTransactions
filterSiteNumber

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 transactions included in the batch. For example, if set to 11:59PM on 31 Jan 2018 then only transactions 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 transactions included in the batch. For example, if set to 11:59PM on 31 Jan 2018 then only transactions occurring before and on this date and time will be included in the batch. The filterEndDatetime has the following validation rule specifications:

filterTaggedTransactions is an optional POST parameter. This parameter specifies whether to return transactions 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 transactions occurred. Site Numbers are allocated to all sites by TT. A list is available via TWeb. 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&filterTaggedTransactions=UntaggedOnly&filterSiteNumber=123456" https://publicapi.tweb.com.au/v1/TransactionsBatchNumber

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&filterTaggedTransactions=UntaggedOnly&filterSiteNumber=123456" https://publicapi.tweb.com.au/v1/TransactionsBatchNumber

Step 1 - Response

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

{
    "Data": {
        "Items": [
            {
                "NewBatchNumber": 123
            }
        ],
        "Meta": {
            "Endpoint": "/v1/TransactionsBatchNumber",
            "SubmittedFilters": {
                "filterEndDatetime": "2018-03-01 00:00:00",
                "filterSiteNumber": "123456",
                "filterStartDatetime": "2018-01-31 23:59:00",
                "filterTaggedTransactions": "UntaggedOnly"
            },
            "TargetID": "abc123",
            "Title": "Public API: Transactions 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 transactions 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 a Transactions Batch Number are:

Step 2 - Requesting a Page of Transactions

Public API Version:  1.3 1.2 1.1 1

Once the client has the Transactions Batch Number, this can be used to download transaction 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 transaction downloads at. Note that the count begins at 1, not 0, and is inclusive. For example, if set to 1 then transaction 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 transaction downloads at. Note that the count begins at 1, not 0, and is inclusive. For example, if set to 1 then transaction 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 transactions can be downloaded by setting startRecord=1 and endRecord=100 (not 99 transactions!).

Request Examples

A request for Transaction 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/Transactions

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

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

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

A request for Transaction 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/Transactions

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

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

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

Step 2 - Response

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

{
    "Data": {
        "Items": [
            {
                "ActivityCard": {
                   "Number": "0000000000007890",
                   "AccountNumber: "99778",                   
                }
                "Amount": 500.0,
                "CardAccessID": {
                   "Number": "0000000000001234",
                   "AccountNumber": "88123",
                   "MapCode": 123
                },
                "CustomerReferenceNumber": "",
                "DateTime": "2018-03-01T00:00:00",
                "CostCentre": "ZzYyXx98765",
                "Discount": 0,
                "Grade": {
                    "Number": 2,
                    "Name": "Unleaded"
                },
                "Hose": 1,
                "Odometer": 0,
                "PLU": "",
                "PromotionCode": "",
                "Pump": 1,
                "Quantity": 500.0,
                "Reference": 0,
                "SKU": "",
                "Site": {
                    "Number": 123456,
                    "LocationCode": "XYZ"
                },
                "Vehicle": {
                    "Registration": "ABC123",
                    "AssetNumber": "AA998877",
                    "FleetNumber": "FF112233",
                    "Name": "TT_ABC123"
                },
                "Surcharge": 0,
                "TotalEngineHours": 0.0,
                "UnderLoadHours": 0.0,
                "UnitPrice": 1.0,
                "UserID": "",
                "RowNumber": 1
            }
        ],
        "Meta": {
            "Endpoint": "/v1.21.3/Transactions",
            "SubmittedFilters": {
                "batchNumber": 123,
                "endRecord": 1,
                "startRecord": 1
            },
            "TargetID": "abc123",
            "Title": "Public API: Download Transactions"
        }
    },
    "Error": {
        "Code": 0,
        "Status": "OK"
    }
}

{
    "Data": {
        "Items": [
            {
                "ActivityCardNumber": "",
                "Amount": 500.0,
                "CardNumber": "0000000000001234",
                "CustomerReferenceNumber": "",
                "DateTime": "2018-03-01T00:00:00",
                "CostCentre": "ZzYyXx98765",
                "Discount": 0,
                "Grade": {
                    "Number": 2,
                    "Name": "Unleaded"
                },
                "Hose": 1,
                "MapCode": 0,
                "Odometer": 0,
                "PLU": "",
                "PromotionCode": "",
                "Pump": 1,
                "Quantity": 500.0,
                "Reference": 0,
                "SKU": "",
                "Site": {
                    "Number": 123456,
                    "LocationCode": "XYZ"
                },
                "Vehicle": {
                    "Registration": "ABC123",
                    "AssetNumber": "AA998877",
                    "FleetNumber": "FF112233"
                },
                "Surcharge": 0,
                "TotalEngineHours": 0.0,
                "UnderLoadHours": 0.0,
                "UnitPrice": 1.0,
                "UserID": "",
                "RowNumber": 1
            }
        ],
        "Meta": {
            "Endpoint": "/v1.1/Transactions",
            "SubmittedFilters": {
                "batchNumber": 123,
                "endRecord": 1,
                "startRecord": 1
            },
            "TargetID": "abc123",
            "Title": "Public API: Download Transactions"
        }
    },
    "Error": {
        "Code": 0,
        "Status": "OK"
    }
}

{
    "Data": {
        "Items": [
            {
                "ActivityCardNumber": "",
                "Amount": 500.0,
                "CardNumber": "0000000000001234",
                "CustomerReferenceNumber": "",
                "DateTime": "2018-03-01T00:00:00",
                "Discount": 0,
                "Grade": {
                    "GradeNum": 2,
                    "Name": "Unleaded"
                },
                "Hose": 1,
                "MapCode": 0,
                "Odometer": 0,
                "PLU": "",
                "PromotionCode": "",
                "Pump": 1,
                "Quantity": 500.0,
                "Reference": 0,
                "SKU": "",
                "SiteNumber": 123456,
                "Surcharge": 0,
                "TotalEngineHours": 0.0,
                "UnderLoadHours": 0.0,
                "UnitPrice": 1.0,
                "UserID": "",
                "RowNumber": 1
            }
        ],
        "Meta": {
            "Endpoint": "/v1/Transactions",
            "SubmittedFilters": {
                "batchNumber": 123,
                "endRecord": 1,
                "startRecord": 1
            },
            "TargetID": "abc123",
            "Title": "Public API: Download Transactions"
        }
    },
    "Error": {
        "Code": 0,
        "Status": "OK"
    }
}

The transaction 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 Transaction data are:

Step 3 - Tagging Transactions

Once the client has the Transactions Batch Number, this can be used to tag transactions 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 Transaction 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/TagTransactions

A request for Transaction 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/TagTransactions

Step 3 - Response

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

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

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