Save Access IDs

Once authorised, a client can save Access IDs to be used at sites via the TWeb Public API. Access IDs in T-WEB refer to any physical medium used to authorise a pump. This can include:

• An account card, also known as a local card, white card and member number card.
• A Hex iButton. This type of iButton has a preconfigured hexadecimal number that cannot be changed.
• A Programmable iButton. The data on these iButtons can be updated.
• An OTI Passive Tag on the fuel inlet.
• A VID - an active RFID Vehicle ID Tag.
• An EFTPOS card. Note that EFTPOS Access IDs cannot be stored in T-WEB.

Access IDs are saved in a JSON list. The process of saving Access IDs may involve two requests to the Public API:

1. A request to obtain all Access ID Type Keys used when saving Access IDs (this is optional)
2. Requests to save Access IDs

The client need only make one request to obtain all Access ID Types (Step 1) at the start of the session since this data does not change frequently. Once the client receives the list of Access ID Types, then it can use them to save a maximum of 10 Access IDs per request (Step 2).

Step 1 - Requesting Access ID Types

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

The endpoint only accepts HTTP POST requests. 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

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

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" https://publicapi.tweb.com.au/v1/GetAccessIDTypes

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" https://publicapi.tweb.com.au/v1/GetAccessIDTypes

Step 1 - Response

The response from the Access ID Types endpoint has the following JSON format:

{
    "Data": {
        "Meta": {
            "Title": "Public API: Get all Access ID Types",
            "Endpoint": "/v1/GetAccessIDTypes",
            "SubmittedFilters": {},
            "Hash": "7D0D60131DD9F7C9ECCCD8286C559AD8DA487412"
        },
        "Items": [
            {
                "Key": 99,
                "Description": "ACME Account Cards",
                "Prefix": 7777,
                "MapCode": 21
            },
            {
                "Key": 51,
                "Description": "ACME Hex iButtons",
                "Prefix": 0,
                "MapCode": 151
            }
        ]
    },
    "Error": {
        "Code": 0,
        "Status": "OK"
    }
}

The Access ID Type 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 a Transactions Batch Number are:

Step 2 - Saving Access IDs

Once the client has the Access ID Type Keys, these can be used to save Access IDs. 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
accessIDs

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

accessIDs is a mandatory POST parameter with the following JSON format:

[
    {
        "Number": "7777000034752",
        "Type": {
            "Key": 99
        },
        "Name": "Fred's card",
        "Status_": 0,
        "Account": {
            "Number": "00009999"
        },
        "PIN": 1234,
        "SubAccountNumber": "80wYFiF5cX",
        "Grades": [{
            "Number": 1,
            "Status_": 0
        }, {
            "Number": 2,
            "Status_": 0
        }],
        "OdometerPrompt": true,
        "Department": {
            "Name": "Landscape"
        },
        "CostCentre": {
            "Code": "Concrete"
        },
        "Phone": "+77 00 1895 12 34534",
        "Mobile": "1234 765 234",
        "Fax": "+44 1234 345 567",
        "Email": "bob@bob.bob",
        "Street1": "3-45 September Rd",
        "Street2": "",
        "City": "Liverpool",
        "State": "Merseyside",
        "PostCode": "L6 4DG",
        "Country": "United Kingdom",
        "Notes": "Blah",
        "LiveDate": "2020-12-29T23:59:59",
        "Expires": "2022-12-29T23:59:59",
        "UserIDPrompt": true
    },
    ...
]

I.e. a list of Access ID objects. A maximum of 10 objects is permitted in the list.

Table 1 desribes these fields:

Table 1

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

targetID

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

Step 2 - Response

The response after submitting an Access ID has the following JSON format:

{
    "Error": {
        "Code": 4502,
        "Status": "Invalid Access ID Details",
        "Field": "[1].Type.Key"
    },
    "Data": {
        "Meta": {
            "Title": "Public API: Save Access ID",
            "Endpoint": "/v1/SaveAccessIDs",
            "Hash": "34F788074917B802E6D9A133EF1B2F7A6FEC7F94"
        },
        "Items": [{
            "Number": "7777000034752",
            "Type": {
                "Key": 99
            },
            "Error": {
                "Code": 0,
                "Status": "OK"
            },
            "UserAction": 1
        }, {
            "Number": "7777000094256",
            "Type": {
                "Key": 99
            },
            "Error": {
                "Code": 4502,
                "Status": "Invalid Access ID Details",
                "Field": "Type.Key"
            },
            "UserAction": 0
        }]
    }
}

As with other endpoints, the Error object has a Code and a Status property. It also has a Field property that describes which field was at fault using a JavaScript style reference. So for example, if the first Access ID submitted in the list has an error in the account number field then Error.Field will have value [0].Account.Number. Or if the PIN in the 7th Access ID in the list has an error then Error.Field will have value [6].PIN. I.e. the list item index is addressed with square brackets starting from 0 and the property of the Access ID object with the error follows. The T-WEB Public API exits at the first error it encounters, so even if a submission has multiple errors, only the first will appear in the response.

Each submitted Access ID that was successfully processed is returned in the response under the Data.Items list. The first Access ID to be submitted that could not be successfully processed is also returned in the list. Each returned Access ID can be uniquely identified by its Number and Type.Key field. The UserAction field has the following definitions:

The Error JSON property is included in all responses from the TWeb Public API - both for the overall response and for each of the Access IDs submitted. The overall response Error property The possible responses when submitting an Access ID are: