ParcelTrack API

(0 reviews)

Subscription POST

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parceltrack/3.0/subscription/webhook/
Production:
https://api.nzpost.co.nz/parceltrack/3.0/subscription/webhook/

Resource Description

Creates a subscription with provided tracking reference or TPID and webhook url.

Resource Information

AttributeDetail
Response FormatJSON
Requires AuthenticationYes
Rate Limited15 calls per second across all merchants using the API. If rate limit is exceeded, calls will be queued. Calls unprocessed for over 60 seconds will time out.

Request Parameters

Field NameDescriptionMandExample
account_numberTPID for merchantYes91327067
tracking_referenceUnique identifier for the parcelNoJS21317298172NZ
notification_endpointThe webhook URL to receive the notificationsYeshttp://www.acme.co.nz/webhooks/tracking

Sample Request - Subscription object is tracking reference


{
  "tracking_reference":"JS21317298172NZ",
  "notification_endpoint":"http://www.acme.co.nz/webhooks/tracking"
}

Sample Request - Subscription object is TPID


{
  "account_number":"91327067",
  "notification_endpoint":"http://www.acme.co.nz/webhooks/tracking"
}

Business Rules

The following business rules are applied on each /subscription/webhook request:

NameDescription
BR001A subscription must contain either a tracking reference or a TPID
BR002ParcelTrack subscription information can only be delivered via webhook

Response Parameters

The following lists the fields in the response message.

Field NameDescriptionMandExample
successReturns true if request is successful else falseYesTrue
message_idA unique identifier for the API CallYes0d41ffa0-0976-11e5-8fa8-02850e3bb9fb
subscription_guidA unique identifier for the subscriptionYes32ffd9bd-8ea5-4167-85d8-a20d4a5e7a31
errorsIf the subscription creation is unsuccessful, an error code and message is providedYes if API call is unsuccessfulSee section Error Object Parameters

Error Response Elements

Field NameDescriptionMandExample
successReturns if request is successfulYesTrue
errorsError object with error detailsY if success =falseSee Error Object Parameters below
message_idThe unique message identifierYesec608f40-2a8b-11e5-a9c0-025c481d35ef

Error Object Parameters

Field NameDescriptionExample
codeError code where first 3 digits are http status code, last three digits identify error type400002
messageDescription of error codeInvalid Parameter(s)
detailsDescription of specific errorThe parameter tracking_reference cannot be empty

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

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

Error Codes

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

Sample Response

Sample: Success


{
   "success": true,
   "subscription_guid": "32ffd9bd-8ea5-4167-85d8-a20d4a5e7a31",
   "message_id": "28eed9bd-8ea5-4167-85d8-a20d4a5e7a42"
}

Sample: Failure


{
   "success": false,
   "errors": [   {
      "code": "400002",
      "message": "Invalid parameter(s)",
     "details": "The parameter tracking_reference cannot be empty"
   }],
   "message_id": "28eed9bd-8ea5-4167-85d8-a20d4a5e7a42"
}

Reviews