Customer Transaction History Service

This web service allows you to generate a report outlining all assets that were delivered or returned within a given date range for a given customer. Deliveries and returns are matched up on the same line representing a round trip for the asset.

Service Protocol: REST

This web service uses a REST or RESTful style protocol. This is an HTTP resource-oriented architecture that uses standard HTTP actions (e.g. GET, POST, DELETE) to manipulate resources exposed as URLs. Standard HTTP Status Codes are used for success and error codes.

More information on REST can be found at the following resources:

Service Authentication

The HTTP request must have Basic Authentication credentials included. We strongly recommend that all web service requests be made over SSL (HTTPS).

More information on HTTP Basic Authentication can be found at the following resources:

TrackAbout will provide you with a dedicated user account to use when making web service requests.

Troubleshooting Service Authentication/Authorization Issues

When calling a web service, TrackAbout will return a "403 Access Denied" error if there are any issues authenticating the request. These errors can occur under one or more of the following circumstances:

  1. The authentication header is missing or not formatted correctly. To correct this, review the links on HTTP Basic Authentication above and ensure that the application you are using to call the web service is building the authorization header correctly.

    • Login to the TrackAbout website for the environment against which you are trying to invoke the web service and go to the "Internal Users" page. Verify that the username you are using exists.

    • If the username does not yet exist in the environment that you are trying to use, contact TrackAbout support to have a new web service user created for that environment.

    • If the username does exist in that environment, verify that it has 'Web Service' (or something similar) listed in its Roles. The TrackAbout support team can assist in verifying whether or not the user in question has the needed web service permissions.

    Report Parameters

    The parameters for the report are provided via query string values. See the #Usage section below for more information on creating the query string. All parameters must have a valid value provided or the web service will return an error code.

    Friendly Name Query String Name Description
    Customer ID custId The ID of the customer for which the report should be run.
    Include Departments? inclDept True or False value indicating whether departments of the provided customer should also be included in the report.
    Start Date startDate Beginning date of the date range that should be included in the report.
    End Date endDate Ending date of the date range that should be included in the report.
    Sort Column sortCol

    Numeric value indicating how the resulting data should be sorted. Valid values include:

    1 - Sort by Product Code

    2 - Sort by Serial Number

    3 - Sort by Bar code

    4 - Sort by Ship Date

    5 - Sort by Return Date

    Validations and Restrictions

    The following validations are applicable to the parameters provided to this report. If one or more of these validations fail, the web service will return an HTTP error code with a message indicating why validation failed.

    • If the username exists in that environment and the it has the needed web service permissions, then it's likely that the password being provided is not correct. You can use the Internal Users page to edit the user in question and set a new password for it.

      NOTE

      If you change the password for a web service user, you could end up causing issues for other automated processes you're using to make web service calls using that same user. If you're storing the credentials for that user in any external applications that make automated calls into TrackAbout web services you'll need to update the password that those applications are using accordingly.

    • The provided start and end date values must represent valid dates and a valid date range. For example, the end date must come after the start date.

    • The provided date range can cover a maximum of three years.

    • The provided customer ID must exist within the TrackAbout database.

    • The provided sort column number must fall within the allowed values indicated above.

    Report Output

    The resulting report data will be rendered into a PDF document that will be returned to the caller. The following columns are included in the report:

    • Product Code

    • Product Description

    • Barcode

    • Serial Number

    • Ship Date

    • Expiration Date

    • Return Date

    • Invoice Number

    • Purchase Order Number

    • Line Number (sequentially generated line number per record to identify lines and ensure report is complete)

    Usage

    • Allowed HTTP Actions: GET

    • Input: All parameters are provided in the query string. When creating the query string, use the query string key values specified in the Report Parameters section above for the corresponding parameter.

    NOTE

    Be sure to properly URL Encode each parameter value. More information on URL Encoding: Wikipedia: URL Encoding

    Production Environment

    • Web Service URL: https://www.trackabout.com/ws/CustomerTransactionReport.asmx

    • Service WADL: https://www.trackabout.com/ws/CustomerTransactionReport.asmx?meta

    Test Environment

    • Web Service URL: https://test.trackabout.com/ws/CustomerTransactionReport.asmx

    • Service WADL: https://test.trackabout.com/ws/CustomerTransactionReport.asmx?meta

    A note about date/time values: In order to accommodate customers in different locations, all date and time values stored in TrackAbout are stored as Coordinated Universal Time values (UTC). This means that we typically have to perform a time zone conversion of the provided date and time values to be consistent with how the data is stored. To make this easier, we only accept a few very specific date and time formats:

    • UTC Time — yyyy-MM-ddTHH:mm:ssZ

    Example: 2009-03-04T08:23:12Z would be evaluated as March 4, 2009 at 8:23:12 AM. The 'Z' on the end denotes a 'zero' UTC offset, meaning the provided value has already been adjusted to UTC time. When a value like this is received by this web service no time zone conversion is performed.

    • Local Time with UTC Offset — yyyy-MM-ddTHH:mm:sszzz

    Example: 2009-05-02T13:34:45-05:00 would initially be evaluated as a local time of May 2, 2009 at 1:34:45 PM. The '-05:00' at the end of the string would signal that the provided time has a negative 5 hour offset from UTC time, meaning that 5 hours would be added to the provided local time in order to convert it to UTC.

    • Local Time with no Offset — yyyy-MM-ddTHH:mm:ss

    Example: 2009-11-10T09:45:00 would be evaluated as November 10, 2009 at 9:45:00 AM. Since the provided time wasn't denoted as UTC and no offset was provided, the web service will use the time zone at the location known as "headquarters" for your company when doing the time conversion.

    Below is a Full Example URL which contains the following parameters:

    • Customer ID = ABC123

    • Include Departments = false

    • Start Date = 2009-01-01 12:00:00 AM UTC time

    • End Date = 20009-12-31 12:00:00 AM UTC time

    • Sort Column = 1 (Product Code):

    Full Example URL:
    https://www.trackabout.com/ws/CustomerTransactionReport.asmx?custId=ABC123&startDate=2009-01-01T00%3a00%3a00Z&endDate=2009-12-31T00%3a00%3a00Z&inclDept=False&sortCol=1

    • Output: The resulting report data will be rendered into a PDF file and be returned as binary data in the HTTP response. A 'Content-Disposition' HTTP header will be added with the value 'attachment; filename=<generatedFileName>' where <generatedFileName> will be a unique file name with a sequence number generated from the current system time appended to it.

    The username and/or password specified in the authentication header is incorrect or the user does not have the permissions needed invoke web services. If you have both a production and test instance of TrackAbout it's important to remember that they each have a distinct set of users and login credentials; a username and password that works in the production environment will not necessarily work in the client test environment and vice-versa. To verify and/or correct this: