Proof Of Delivery Service

This web service allows you to generate a document representing the details of an order for a provided order/invoice number.

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:

Wikipedia: Representational State Transfer

REST Architecture Style

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:

Wikipedia: HTTP Basic Authentication

HTTP Authentication: Basic and Digest Access Authentication

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.

  2. 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:

    • 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.

    • 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.

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

Invoice Number

invoice

This number is sometimes referred to as the Invoice Number, Document Number, or Order Number. The value provided for this will be used to locate the order/delivery/return data within the TrackAbout database to generate the report.

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 provided Invoice Number could not be matched to order and delivery/return data, the report will not be run and a validation error will be returned instead.

Report Output

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

  • 'Sold By' address of the order

  • 'Ship From' address of the order

  • 'Bill To' address of the order

  • 'Ship To' address of the order

  • Document Number of the order (the same as the Invoice Number provided as a parameter)

  • Customer Number of the customer that placed the order

  • Date on which the order was entered

  • Date on which the order was shipped

  • Shipment method used for the order

  • Name of the person who placed the order

  • Name of the person who entered the order

  • Payment terms of the order

  • PO Number of the order

  • Line items representing the original products ordered and actual quantities shipped / returned:

    • Line Number of the order as it was originally submitted to TrackAbout

    • Product Code of the item that was ordered/shipped/returned

    • Product Description of the item that was ordered/shipped/returned

    • Total quantity of the item that was originally ordered

    • Total quantity of the item that was actually shipped

    • Total quantity of the item that was actually returned

    • Signer's Name

    • Signer's Signature

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/ProofOfDelivery.asmx

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

Test Environment

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

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

Full Example URL for Invoice Number = ABC123

https://www.trackabout.com/ws/ProofOfDelivery.asmx?invoice=ABC123

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.