Skip to content
Transdirect Developer Centre

Moving from v4

If your integration calls https://www.transdirect.com.au/api (paths such as /api/bookings/v4/...), move it to the v5 API at https://api.transdirect.com.au/api/v5. This page is the checklist.

Your existing API key works on v5 unchanged: it is the same key for the same account. The old documentation on Apiary and GitBook has been retired, and this site is now the reference.

Checklist

Section titled “Checklist”

  1. Change the base URL to https://api.transdirect.com.au and put /api/v5 in front of every path, using the mapping below.

  2. Send the key in the api-key header. v5 does not accept HTTP Basic authentication (email and password). If you used Basic auth, create a key as described in authentication.

  3. Split create-and-pay into quote, then confirm. POST /api/v5/bookings/v4 returns 400 with code create_and_pay_not_supported for a non-null payment_method, a truthy collection_point_id, or a non-null misspelt payment field such as paymentMethod or card_id. Send the courier, pickup date, pickup time and payment method to POST /api/v5/bookings/{id}/confirm instead. See booking lifecycle.

  4. Switch on status_code. On a v5 booking, status is a display label (“Pending Payment”) and status_code is the stable code (pending_payment).

  5. Update error handling for the v5 bodies. A missing or wrong key is 401 {"error":"missing_api_key"} or 401 {"error":"invalid_api_key"}, not a message and code. See errors.

  6. Update rate-limit handling. v5 allows 600 requests a minute per key and sends only retry-after on a 429. There are no X-RateLimit-* headers. See rate limits.

  7. Run the whole flow in demo mode before you switch production traffic. See testing with demo mode.

Path mapping

Section titled “Path mapping”

Replace https://www.transdirect.com.au/api with https://api.transdirect.com.au/api/v5 and adjust the path as shown. Where v4 had both /bookings/... and /bookings/v4/..., both map to the same v5 path.

Quotes and bookings

Section titled “Quotes and bookings”
v4v5
POST /api/bookings/v4 or POST /api/quotesPOST /api/v5/quotes
POST /api/quotes/pickup-availabilityPOST /api/v5/quotes/pickup-availability
GET /api/bookings/v4GET /api/v5/bookings
GET /api/bookings/v4/{id}GET /api/v5/bookings/{id}
PUT or PATCH /api/bookings/v4/{id}PUT or PATCH /api/v5/bookings/{id}
DELETE /api/bookings/v4/{id}DELETE /api/v5/bookings/{id}
POST /api/bookings/v4/{id}/confirmPOST /api/v5/bookings/{id}/confirm
GET /api/bookings/{id}/contextGET /api/v5/bookings/{id}/context
GET /api/bookings/v4/{id}/senderGET /api/v5/bookings/{id}/sender
GET /api/bookings/v4/{id}/receiverGET /api/v5/bookings/{id}/receiver
GET or POST /api/bookings/v4/{id}/custom_declarationGET or POST /api/v5/bookings/{id}/custom_declaration
GET, POST /api/bookings/v4/{id}/itemsGET, POST /api/v5/bookings/{id}/items
GET, PUT, DELETE /api/bookings/v4/{id}/items/{item_id}GET, PUT, DELETE /api/v5/bookings/{id}/items/{item_id}

Labels and documents

Section titled “Labels and documents”
v4v5
GET or HEAD /api/bookings/v4/{id}/labelGET or HEAD /api/v5/bookings/{id}/label
GET or HEAD /api/bookings/v4/{id}/a6labelGET or HEAD /api/v5/bookings/{id}/a6label
GET /api/bookings/v4/{id}/manifestGET /api/v5/bookings/{id}/manifest
GET /api/bookings/v4/{id}/invoiceGET /api/v5/bookings/{id}/invoice
GET /api/bookings/v4/{id}/public_urlGET /api/v5/bookings/{id}/public_url
GET /api/bookings/{id}/tntregeneralabel, /tgeregeneralabel, /northlineregeneralabelGET /api/v5/bookings/{id}/tntregeneralabel, /tgeregeneralabel, /northlineregeneralabel
POST /api/bookings/labels/batchPOST /api/v5/bookings/labels/batch
POST /api/bookings/manifests/batchPOST /api/v5/bookings/manifests/batch

Tracking

Section titled “Tracking”
v4v5
GET /api/bookings/trackstatus/{id}GET /api/v5/tracking/{reference} (no key needed)
GET /api/bookings/track/{id} or /api/bookings/v4/track/{id}GET /api/v5/bookings/track/{id}

Account, configuration and reference data

Section titled “Account, configuration and reference data”
v4v5
GET /api/memberGET /api/v5/member
GET /api/members/payment-methodsGET /api/v5/members/payment-methods
GET /api/bookings/v4/api_detailsGET /api/v5/bookings/v4/api_details
POST /api/bookings/v4/set_api_settingsPOST /api/v5/bookings/v4/set_api_settings
POST /api/bookings/v4/test_api_key_settingsPOST /api/v5/bookings/v4/test_api_key_settings
GET /api/bookings/syncGET /api/v5/bookings/sync
GET /api/couriersGET /api/v5/couriers
GET /api/locations, /api/locations/page/{page}GET /api/v5/locations, /api/v5/locations/page/{page}
GET /api/locations/searchGET /api/v5/locations/search
GET /api/locations/postcode/{postCode}GET /api/v5/locations/postcode/{postCode}
GET /api/locations/statesGET /api/v5/locations/states
POST /api/locations/validate-routePOST /api/v5/locations/validate-route
GET, POST /api/ordersGET, POST /api/v5/orders
POST /api/orders/create-simplePOST /api/v5/orders/create-simple
GET, PUT /api/orders/{id}GET, PUT /api/v5/orders/{id}

Response bodies are not always identical to v4, so check each endpoint’s reference page as you move it. The API key configuration endpoints keep v4 in their v5 path; those are their only paths. Collection points have their own page: collection points.

Behaviour that changes

Section titled “Behaviour that changes”
AreaOn v5
Authenticationapi-key header only. No Basic auth. X-API-Key, api_key and Authorization: Bearer are not read.
Creating a bookingEvery quote creates a draft booking and returns its id. Booking and paying always happen in a second call, POST /api/v5/bookings/{id}/confirm.
Quote responsequotes is keyed by courier id; that key is the courier you confirm with. Ignore the label URL in the quote response, which points at the old host, and use GET /api/v5/bookings/{id}/label.
Booking responsestatus is a display label and status_code is the code to use. label is a v5 path. quotes and quote_errors are only on the quote response, not on GET /api/v5/bookings/{id}.
PaymentSend payment_method (an id from GET /api/v5/members/payment-methods, or "demo") on confirm. Leaving it out bills a credit account, which most accounts do not have, so the confirm returns 403 NO_PAYMENT_METHOD. Raw card details are rejected.
Confirm bodypickup_date and pickup-date are both accepted, as are pickup_time and pickup-time.
Booking listLeaves out unconfirmed quotes, returns at most 100 bookings, and returns 404 with an empty body when there are none.
ErrorsSeveral JSON shapes, all described in errors. An unknown path under /api/v5 returns 404 {"error":"legacy_public_route_not_mounted"}.
Rate limits600 requests a minute per key, retry-after on 429, no X-RateLimit-* headers.
WebhooksNone. Poll labels and tracking.

Cancelling a booking

Section titled “Cancelling a booking”

Use POST /api/v5/bookings/{id}/cancel with a required reason for eligible account-credit and demo bookings. The response distinguishes an immediate cancellation from a request submitted to support. Card and PayPal bookings return 422; use the members area or contact support for those. Delete unconfirmed drafts with DELETE /api/v5/bookings/{id}.

Not available on v5

Section titled “Not available on v5”
  • Creating member accounts (POST /api/members). New accounts sign up at members.transdirect.com.au/sign-up.
  • Choosing a collection point on create (collection_point_id). The v5 quote and confirm bodies do not accept it.
  • /transvirtualregeneralabel and /zetaregeneralabel. v5 has only the TNT, TGE and Northline regenerate-label routes listed above.

Next steps

Section titled “Next steps”