ParcelTrack API

(0 reviews)

Partial Match

###Resource URL
UAT:

https://api.uat.nzpost.co.nz/parceltrack/v4/partialmatch/{partial_reference}

Production:

https://api.nzpost.co.nz/parceltrack/v4/partialmatch/{partial_reference}

###Resource Description

Request to return related tracking references for a given partial reference.

###Resource Information

Attribute	Detail
Response Format	JSON
Requires Authentication	Yes
Rate Limited	15 calls per second. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

###Request Message Fields

Field	Description	Mand	Example
tracking_reference	Unique tracking reference for a parcel (job number for Pace)	Yes	JP100000271NZ or 123521

###Sample Request

https://api.nzpost.co.nz/parceltrack/v4/parcels?tracking_reference=EY593742046NZ&tracking_reference=FF138431175NZ&tracking_reference=FL010795711NZ&tracking_reference=FZ101183740NZ&tracking_reference=GC000875843NZ&tracking_reference=HA099246112NZ&tracking_reference=EY593742046NZ&tracking_reference=FF138431175NZ&tracking_reference=FL010795711NZ&tracking_reference=FZ101183740NZ

###Response Parameters

Field Name	Description	Mand	Example
success	Returns true if request is successful else false.	Yes	True
message_id	A unique ID for the API Call	Yes	da5ac7f0-7c18-11e5-b508-0297700fe675
status_code	code to identify is there any errors as part of response results(1-all success 2-all fails 3-mixed)	yes	1
results	An JSON object containing the scan event details of all queried parcels. See Results Object Parameters.	No	JSON Object

###Results Object Parameters

Field Name	Description	Mand	Example
tracking_reference	The queried tracking reference	Yes	JP100000271NZ
tracking_events	An JSON object containing all scan events of queried parcels. See Results - Tracking Events Object Parameter section. This may be presented when the success flag is true. This may be absent if the parcel has no associated scan events at the time of the request or the success flag is false.	N	JSON Object
errors	An JSON object containing error details. See Results - Errors Object Parameter section. This may be presented if the parcel has no associated scan events at the time of the request or the success flag is false.	N	JSON Object

###Results - Tracking Events Object Parameters

Field Name	Description	Mand	Example
date_time	Date and time the courier recorded the scan or event. This is the time you should display to your customers	Y	2016-01-29 11:00:00Z
description	Detailed description of the event	Y	Ready to send
edifact_code	EDIFACT code for the parcel delivery step	Yes	997
depot_name	Name of the depot that relates to scan	N	AKL City Fleet
run_name	Name of the run that relates to the scan	N	Auckland CBD
courier_first_name	First name of the courier performing the event	N	John
courier_full_name	Full name of the courier performing the event. This field is only returned for the internal users.	N	John Smith
location	JSON object containing the location details of an event. See Tracking Events - Location Object Parameters section.	N	JSON Object
signed_by	JSON object containing name of the signer and the string representation of binary signature data. See Tracking Events - Signed By Object Parameters section.	Yes if the item was signature required	JSON Object
seqref	CME sequence ref of the event	Y if event derived from CME	2631897613
source	Source system where the event occurred. Valid systems are: CME, Navigator, IPS, ParcelStore, PSG	N	CME
status	Brief description of the event	Y	Ready to send

###Tracking Events - Location Object Parameters

Field Name	Description	Mand	Example
latitude	Latitude of the location of the scan	Y if longitude exists	-36.8485
longitude	Longitude of the location of the scan	Y if latitude exists	174.7633

###Tracking Events - Signed By Object Parameters

Field Name	Description	Mand	Example
name	Full name of the person providing the signature.	Yes if signature required	Lee Child
signature	String representation of the binary data for the signature.	No	ec608f40-2a8b-11e5...

###Results - Errors Object Parameters

Field Name	Description	Example
code	Error code	400002
message	Error message	Invalid parameter(s)
details	Error details	No event for this ticket

###HTTP Status Codes

Note that some error messages are customised for the request, i.e. error code 400 usually will describe what is wrong with the request

Code	Message
200	Success
400	Bad request
401	Unauthorized
403	Forbidden
409	Invalid request
500	System unavailable

###Error Codes

Code	Message
200001	Partial results returned, not all system(s) have responded
200002	All sources responded, data may be incomplete
400001	Parameter(s) missing
400002	Invalid parameter(s)
400003	Non mutually exclusive parameters detected
401001	Unauthorised access, please contact administrator
500001	General Exception
500002	System(s) offline

###Sample Response

Sample of queried partial tracking reference in a request are valid:



{
  "message_id": "f0d59c57-ef4f-49db-aa59-129c2f1e2a12",
  "success": true,
  "status_code":1,
  "results": [
    {
      "tracking_reference": "3616060010051511AKL005AS",
      "tracking_events": [
        {
          "date_time": "2015-03-23T17:04:08Z",
          "status": "Ready for pickup",
          "description": "CourierPost were advised that your item is ready to be picked up.",
          "source": "CME",
          "seqref": "2631897613",
          "edifact_code": "13",
          "depot_name": "Auckland Central Fleet",
          "run_name": "Auckland CBD",
          "courier_first_name": "Joe",
          "courier_full_name": "Joe Bloggs",
          "location": {
            "latitude": -36.9406304,
            "longitude": 174.8775616
          },
          "signed_by": {
            "name": "Lee Child",
            "signature": "/3Ie/zFJMkYyRDNBMz8zPTQ7NDg0NjkXORk6HDoeOyI7JDsmPCg8Kj0tPS89Mj40PjY/OT87QD1AP0FDQkZDSERKOkM4QjVBMD8wPTE7Mzk1Nzc0OTM6MTwwPS5AK0EpRCVGIkcgSB5JHEoZShdLFUsTSxFJE0gVSBhIG0geSCJJJUkoSSpKLEouSzFLM0w1TDdRRVJHU0pVSFVGVkRXQlhAWT5bPF05XzdgNWEzYzBkLWYrZilmJmUkYyNhJWAnXypfLF8uYDFhM2I2YzhmOmg7ajxtPG87cTtzOnY4dzZ5NHkxei96LXoreil6J3olfCd/KYEqgyyFLYcuiS+LMI0xjzKSM5QzlTCVLpUslSqVKJUmlSOVIZUflR2UH5MhkiORJZAnjyqOLI0uizGLM4k2iTiIO4c9hj8="
          }
        }
      ]
    },
    {
      "tracking_reference": "3616060010051512AKL005AS",
      "tracking_events": [
        {
          "date_time": "2015-03-23T17:04:08Z",
          "status": "Ready for pickup",
          "description": "CourierPost were advised that your item is ready to be picked up.",
          "source": "CME",
          "seqref": "2631897613",
          "edifact_code": "13",
          "depot_name": "Auckland Central Fleet",
          "run_name": "Auckland CBD",
          "courier_first_name": "Joe",
          "courier_full_name": "Joe Bloggs",
          "location": {
            "latitude": -36.9406304,
            "longitude": 174.8775616
          },
          "signed_by": {
            "name": "Lee Child",
            "signature": "/3Ie/zFJMkYyRDNBMz8zPTQ7NDg0NjkXORk6HDoeOyI7JDsmPCg8Kj0tPS89Mj40PjY/OT87QD1AP0FDQkZDSERKOkM4QjVBMD8wPTE7Mzk1Nzc0OTM6MTwwPS5AK0EpRCVGIkcgSB5JHEoZShdLFUsTSxFJE0gVSBhIG0geSCJJJUkoSSpKLEouSzFLM0w1TDdRRVJHU0pVSFVGVkRXQlhAWT5bPF05XzdgNWEzYzBkLWYrZilmJmUkYyNhJWAnXypfLF8uYDFhM2I2YzhmOmg7ajxtPG87cTtzOnY4dzZ5NHkxei96LXoreil6J3olfCd/KYEqgyyFLYcuiS+LMI0xjzKSM5QzlTCVLpUslSqVKJUmlSOVIZUflR2UH5MhkiORJZAnjyqOLI0uizGLM4k2iTiIO4c9hj8="
          }
        }
      ]
    },
        {
      "tracking_reference": "3616060010051513AKL005AS",
      "tracking_events": [
        {
          "date_time": "2015-03-23T17:04:08Z",
          "status": "Ready for pickup",
          "description": "CourierPost were advised that your item is ready to be picked up.",
          "source": "CME",
          "seqref": "2631897613",
          "edifact_code": "13",
          "depot_name": "Auckland Central Fleet",
          "run_name": "Auckland CBD",
          "courier_first_name": "Joe",
          "courier_full_name": "Joe Bloggs",
          "location": {
            "latitude": -36.9406304,
            "longitude": 174.8775616
          },
          "signed_by": {
            "name": "Lee Child",
            "signature": "/3Ie/zFJMkYyRDNBMz8zPTQ7NDg0NjkXORk6HDoeOyI7JDsmPCg8Kj0tPS89Mj40PjY/OT87QD1AP0FDQkZDSERKOkM4QjVBMD8wPTE7Mzk1Nzc0OTM6MTwwPS5AK0EpRCVGIkcgSB5JHEoZShdLFUsTSxFJE0gVSBhIG0geSCJJJUkoSSpKLEouSzFLM0w1TDdRRVJHU0pVSFVGVkRXQlhAWT5bPF05XzdgNWEzYzBkLWYrZilmJmUkYyNhJWAnXypfLF8uYDFhM2I2YzhmOmg7ajxtPG87cTtzOnY4dzZ5NHkxei96LXoreil6J3olfCd/KYEqgyyFLYcuiS+LMI0xjzKSM5QzlTCVLpUslSqVKJUmlSOVIZUflR2UH5MhkiORJZAnjyqOLI0uizGLM4k2iTiIO4c9hj8="
          }
        }
      ]
    }
  ]
}

Sample of queried tracking reference in a request are valid:



{
   "message_id":"f0d59c57-ef4f-49db-aa59-129c2f1e2a12",
   "success":true,
   "status_code": 1,
   "results":[
      {
         "tracking_reference":"CL092594238NZ",
         "tracking_events":[
            {
               "date_time":"2015-03-23T17:04:08Z",
               "status":"Ready for pickup",
               "description":"CourierPost were advised that your item is ready to be picked up.",
               "source":"CME",
               "seqref":"2631897613",
               "edifact_code":"13",
               "depot_name":"Auckland Central Fleet",
               "run_name":"Auckland CBD",
               "courier_first_name":"Joe",
               "courier_full_name":"Joe Bloggs",
               "location":{
                  "latitude":-36.9406304,
                  "longitude":174.8775616
               },
               "signed_by":{
                  "name":"Lee Child",
                  "signature":"/3Ie/zFJMkYyRDNBMz8zPTQ7NDg0NjkXORk6HDoeOyI7JDsmPCg8Kj0tPS89Mj40PjY/OT87QD1AP0FDQkZDSERKOkM4QjVBMD8wPTE7Mzk1Nzc0OTM6MTwwPS5AK0EpRCVGIkcgSB5JHEoZShdLFUsTSxFJE0gVSBhIG0geSCJJJUkoSSpKLEouSzFLM0w1TDdRRVJHU0pVSFVGVkRXQlhAWT5bPF05XzdgNWEzYzBkLWYrZilmJmUkYyNhJWAnXypfLF8uYDFhM2I2YzhmOmg7ajxtPG87cTtzOnY4dzZ5NHkxei96LXoreil6J3olfCd/KYEqgyyFLYcuiS+LMI0xjzKSM5QzlTCVLpUslSqVKJUmlSOVIZUflR2UH5MhkiORJZAnjyqOLI0uizGLM4k2iTiIO4c9hj8="
               }
            }
         ]
      }
   ]
}

Sample of queried partial tracking reference in a request are invalid:



{
  "success": true,
  "message_id": "123456789",
  "status_code":2
  "results": [
    {
      "tracking_reference": "84411121780532",
      "errors": [
        {
          "code": "400002",
          "message": "Invalid parameter(s)",
          "details": "No events for this ticket"
        }
      ]
    }]}

Partial Match

Reviews