How to pick the typical transactions?
Before coding the API test script, we need to pick some typical transactions from TradeMe.
And these transactions we’ve picked better to cover different types of requests, such as the get, post, delete.
And part of these transactions should correlate with each other at the business level.
API - Retrieve general categories
-
Business scope selection: Get all subcategories.
-
API Function: Retrieves all or part of the Trade Me category tree.
-
Front-end page
home page > View all categories
-
Key request fields
-
Key response fields - A category tree.
Name String or null The name of the category. Number String or null A unique identifier for the category e.g. “0004-0369-6076-”. We plan to change this to a numeric identifier (e.g. “6076”) so you should ensure you can cope with both formats. Path String or null The full URL path of this category e.g. “/Home-living/Beds-bedroom-furniture/Bedside-tables”. Subcategories Collection of or null The list of subcategories belonging to this category. … … … More refer to: Retrieve general categories
-
Example request
GET https://api.tmsandbox.co.nz/v1/Categories.JSON?depth=1
-
Example response
{
"Name": "Root",
"Number": "",
"Path": "",
"Subcategories": [
{
"Name": "Trade Me Motors",
"Number": "0001-",
"Path": "/Trade-Me-Motors",
"HasClassifieds": true,
"AreaOfBusiness": 3,
"CanHaveSecondCategory": true,
"CanBeSecondCategory": true,
"IsLeaf": false
},
{
"Name": "Trade Me Property",
"Number": "0350-",
"Path": "/Trade-Me-Property",
"HasClassifieds": true,
"AreaOfBusiness": 2,
"IsLeaf": false
},
...
],
"AreaOfBusiness": 0,
"IsLeaf": false
}
API - Retrieve your watchlist
-
Business scope selection
Chained combination transactions
Retrieve your watchlist(I’m here) -> Remove a listing from your watchlist -> Retrieve closing soon listings -> Add a listing to your watchlist
Query items in the watch list.
-
API Function: Retrieves a list of items on the authenticated user’s watchlist.
-
Front-end page
Login > Watchlist > View Watchlist
-
Key request fields
-
Key response fields - the Watchlist for the authenticated user.
TotalCount Integer The total number of results in the collection. Can be larger than the number of returned results. Page Integer The index of the current page of results (starts at 1). PageSize Integer The number of results in the current page. List Collection of or null A list of the results in the current page. ListingId Long Integer The ID of the listing. BidCount Integer The number of bids on the item. … … … … More refer to: Retrieve your watchlist
-
Example request
GET https://api.tmsandbox.co.nz/v1/MyTradeMe/Watchlist/All.JSON
-
Example response
{
"TotalCount": 1,
"Page": 1,
"PageSize": 1,
"List": [
{
"ListingId": 2149294406,
"Title": "11x Assorted T-Handle Hex Allen Keys",
"Category": "5964-5999-6004-9825-",
"StartPrice": 1.0000,
"StartDate": "\/Date(1626749989730)\/",
"EndDate": "\/Date(1626922789730)\/",
"ListingLength": null,
"AsAt": "\/Date(1626855531548)\/",
"CategoryPath": "\/Building-renovation\/Tools\/Hand-tools\/Sets-kits",
"PictureHref": "https:\/\/images.tmsandbox.co.nz\/photoserver\/thumb\/8152697.jpg",
"PhotoId": 8152697,
"RegionId": 16,
"Region": "Canterbury",
"Suburb": "Christchurch City",
"Note": "",
"NoteDate": "\/Date(0)\/",
"CategoryName": "Sets & kits",
"Attributes": [
],
"Subtitle": "SKYLARC’S WINDFLOW TECHNOLOGY ONLINE AUCTION",
"MinimumNextBidAmount": 1.0000,
"IsOnWatchList": true,
"PriceDisplay": "$1.00",
"AdditionalData": {
"BulletPoints": [
],
"Tags": [
]
},
"IsDealer": false,
"IsLeading": false,
"IsOutbid": false,
"IsInCart": false,
"MemberBidShippingOption": 0
}
],
"FoundCategories": [
{
"Count": 1,
"Category": "5964-",
"Name": "Building & renovation",
"CategoryId": 5964
}
]
}
API - Remove a listing from your watchlist
-
Business scope selection
Chained combination transactions
Retrieve your watchlist -> Remove a listing from your watchlist(I’m here) -> Retrieve closing soon listings -> Add a listing to your watchlist
Fetch all ‘ListingId’ from the response of upstream transaction ‘Retrieve your watchlist ’ as the request fields.
Pre_repquest ‘Remove a listing from your watchlist ’ removes all ListingId but leave the last one from the whatchlist.
Removes the last ListingId from the whatchlist.
-
API Function: Removes a listing from the authenticated user’s watchlist.
-
Front-end page
Login > Watchlist > View Watchlist > Delete > Confirm to delete
-
Key request fields
-
Key response fields - Details on whether the operation succeeded.
Attempting to remove an auction that doesn’t exist or is not on the watchlist will not produce an error.
| Success | Boolean | Indicates whether the operation was successful. |
| Description | String or null | The description of the error, if the operation failed. |
More refer to: Remove a listing from your watchlist
-
Example request
DELETE https://api.tmsandbox.co.nz/v1/MyTradeMe/WatchList/0000000000.JSON
-
Example response
{
"Success": true,
"Description": "Success"
}
API - Retrieve closing soon listings
-
Business scope selection
Chained combination transactions
Retrieve your watchlist -> Remove a listing from your watchlist -> Retrieve closing soon listings(I’m here) -> Add a listing to your watchlist
Get all the items at 1st page of the closing soon listings.
-
API Function: retrieves the items closing soon for the whole country or for a single region.
-
Front-end page
Login > View all Closing soon in all regions
-
Key request fields
More refer to: Retrieve closing soon listings
-
Key response fields
TotalCount Integer The total number of results in the collection. Can be larger than the number of returned results. TotalCountTruncated Boolean True if the total count of results exceeded the allowed maximum and was truncated. Page Integer The index of the current page of results (starts at 1). PageSize Integer The number of results in the current page. List Collection of or null A list of the results in the current page. ListingId Long Integer The ID of the listing. … … … … More refer to: Retrieve closing soon listings
-
Example request
GET https://api.tmsandbox.co.nz/v1/Listings/closing.JSON?rows=1000
-
Example response
{
"TotalCount": 250,
"Page": 1,
"PageSize": 250,
"List": [
{
"ListingId": 2149292446,
"Title": "fox drawing",
"Category": "0339-5487-",
"StartPrice": 0,
"BuyNowPrice": 1.0000,
"StartDate": "/Date(1626323575513)/",
"EndDate": "/Date(1626928375513)/",
"ListingLength": null,
"AsAt": "/Date(1626926636817)/",
"CategoryPath": "/Art/Digital-art",
"Region": "Canterbury",
"Suburb": "Christchurch City",
"HasBuyNow": true,
"NoteDate": "/Date(0)/",
"ReserveState": 3,
"IsBuyNowOnly": true,
"PriceDisplay": "$1.00 per item",
"PromotionId": 1,
"AdditionalData": {
"BulletPoints": [],
"Tags": []
},
"MemberId": 4007247
},
...
]
}
API - Add a listing to your watchlist
-
Business selection
Chained combination transactions
Retrieve your watchlist -> Remove a listing from your watchlist -> Retrieve closing soon listings -> Add a listing to your watchlist(I’m here)
Fetch a random item on the closing soon listings from upstream transaction ‘Retrieve closing soon listings ’, and add this item to the watchlist.
-
API Function: Adds a listing to the authenticated user’s watchlist.
-
Front-end page
Login > View all Closing soon in all regions > Add a listing to your watchlist
-
Key request fields
More refer to: Add a listing to your watchlist
-
Key response fields - Details on whether the operation succeeded.
Success Boolean Indicates whether the operation was successful. Description String or null The description of the error, if the operation failed. -
Example request
POST https://api.tmsandbox.co.nz/v1/MyTradeMe/WatchList/2149292722.JSON
-
Example response
{
"Success": true,
"Description": "Success"
}
API - Retrieve your won items
-
Business selection
Chained combination transactions
Retrieve your won items(I’m here) -> Remove a purchase from your won items list -> General search -> Retrieve the details of a single listing -> Buy an auction using Buy Now
-
API Function: Retrieves a list of purchases for the authenticated user.
Multiple-quantity auctions can be purchased multiple times.
-
Front-end page
Login > My Trade Me > Won
-
Key request fields
-
Key response fields - A list of items the authenticated user has purchased.
TotalCount Integer The total number of results in the collection. Can be larger than the number of returned results. Page Integer The index of the current page of results (starts at 1). PageSize Integer The number of results in the current page. List Collection of or null A list of the results in the current page. ListingId Long Integer The ID of the listing. … … … … PurchaseId Integer A unique ID that identifies the sale. … … … … More refer to: Retrieve your won items
-
Example request
GET https://api.tmsandbox.co.nz/v1/MyTradeMe/Won/All.JSON
-
Example response
{
"TotalCount": 1,
"Page": 1,
"PageSize": 1,
"List": [
{
"ListingId": 2149289946,
"Title": "Tankard 72",
"Category": "0341-6534-",
"StartPrice": 10.0000,
"StartDate": "/Date(1625598488240)/",
"EndDate": "/Date(1625650049187)/",
"ListingLength": null,
"AsAt": "/Date(1626932384524)/",
"CategoryPath": "/Crafts/Transfers",
"PictureHref": "https://images.tmsandbox.co.nz/photoserver/thumb/4548749.jpg",
"PhotoId": 4548749,
"Seller": {
"MemberId": 4000433,
"Nickname": "junk1b",
"DateAddressVerified": "/Date(1380798000000)/",
"DateJoined": "/Date(1343044800000)/",
"Email": "junk1b@abcde.com",
"UniqueNegative": 5,
"UniquePositive": 16,
"FeedbackCount": 11,
"IsAddressVerified": true
},
"BidCount": 1,
"IsReserveMet": true,
"Note": "",
"NoteDate": "/Date(0)/",
"CategoryName": "Transfers",
"ReserveState": 3,
"Subtitle": "J1B F4d1111",
"Quantity": 1,
"StatusDate": "/Date(0)/",
"AuctionAttribute": "260`TV|3495193540674667286`0",
"BuyerFeedbackPlaced": 0,
"SellerFeedbackPlaced": 0,
"DeliveryId": 0,
"FpoDecisionViaMobile": false,
"HasPaidByCreditCard": false,
"InvoiceId": 0,
"OfferId": 0,
"PaymentInfo": "NZ Bank Deposit",
"Price": 20.0000,
"SelectedShipping": "Buyer to pick-up",
"ShippingPrice": 0,
"ShippingType": 2,
"SoldDate": "/Date(1625650049187)/",
"SoldType": "BUYNOW",
"PaymentInstructions": "",
"PurchaseId": 26180,
"ReferenceNumber": "P26180",
"SubtotalPrice": 20.0000,
"TotalShippingPrice": 0,
"TotalSalePrice": 20.0000,
"TrackedParcels": [],
"TaxSubTotal": 0.00,
"HasPaidByDeferredPayment": false
}
]
}
API - Remove a purchase from your won items list
-
Business selection
Chained combination transactions
Retrieve your won items -> Remove a purchase from your won items list(I’m here) -> General search -> Retrieve the details of a single listing -> Buy an auction using Buy Now
Choose API - ‘Retrieve your won items’ as pre-request to get all won items that want to be removed
Remove all won items on the won items list
-
API Function: Hides a listing from the won items list.
-
Front-end page
Login > My Trade Me > Won > Delete > Confirm to delete
-
Key request fields
-
Key response fields - Details on whether the operation was successful.
Note that this operation will only report failure if the purchase still exists in the won items list after the operation completes. In all other cases, this API will report success (for example it will report success if the purchase ID is invalid or the purchase has already been removed).
| Success | Boolean | Indicates whether the operation was successful. |
| Description | String or null | The description of the error, if the operation failed. |
-
Example request
DELETE https://api.tmsandbox.co.nz/v1/MyTradeMe/Won/26180.JSON
-
Example response
{
"Success": true,
"Description": "Success"
}
API - General search
-
Business scope selection
Chained combination transactions
Retrieve your won items -> Remove a purchase from your won items list -> General search(I’m here) -> Retrieve the details of a single listing -> Buy an auction using Buy Now
Searching 500 items by search function and only pick the items that has the ‘HasBuyNow’ feature and the BuyNowPrice <= $20 from the response for downstream transaction ‘Retrieve the details of a single listing’ to use.
-
API Function: Allows you to search for listings on Trade Me by category, by keywords or a combination of these two.
The result set can be filtered by a variety of properties, including availability of Buy Now, Pay Now, item condition or seller.
-
Front-end page
Login > search a category
-
Key request fields
| page | Integer (optional) | The page number of the set of results to return, starting from 1. Defaults to 1. |
| … | … | … |
| rows | Integer (optional) | The number of results per page; also the maximum number of results to return. The maximum is 25 for unauthenticated requests and 500 for authenticated requests. Defaults to 25 (unauthenticated) or 50 (authenticated). |
| … | … | … |
More refer to: General search
-
Key response fields - The search results.
| TotalCount | Integer | The total number of results in the collection. Can be larger than the number of returned results. | |
| TotalCountTruncated | Boolean | True if the total count of results exceeded the allowed maximum and was truncated. | |
| Page | Integer | The index of the current page of results (starts at 1). | |
| PageSize | Integer | The number of results in the current page. | |
| List | Collection of or null | A list of the results in the current page. | |
| ListingId | Long Integer | The ID of the listing. | |
| BuyNowPrice | Number | The Buy Now price. | |
| HasBuyNow | Boolean | Indicates whether the item has Buy Now. | |
| … | … | … | … |
More refer to: General search
-
Example request
GET https://api.tmsandbox.co.nz/v1/Search/General.JSON?buy=All&rows=500&page=4
-
Example response
{
"TotalCount": 16479,
"Page": 4,
"PageSize": 500,
"List": [
...
{
"ListingId": 2149294614,
"Title": "Cobra Glassware",
"Category": "0341-0881-4739-",
"StartPrice": 11.0000,
"BuyNowPrice": 33.0000,
...
"HasBuyNow": true,
...
},
...
]
}
API - Retrieve the details of a single listing
-
Business scope selection
Chained combination transactions
Retrieve your won items -> Remove a purchase from your won items list -> General search -> Retrieve the details of a single listing(I’m here) -> Buy an auction using Buy Now
Fetch a random item that has the ‘Buy Now’ feature from upstream transaction ‘Remove a purchase from your won items list ’ to display.
Fetch a random ‘ShippingId’ from the response for downstream transaction ‘Buy an auction using Buy Now’ to use.
-
API Function: Retrieves the details of a single listing.
-
Front-end page
Login > search a category > filter buy now item and go to the item details page
-
Key request fields
-
Key response fields - The details of the listing.
| ListingId | Long Integer | The ID of the listing. | |
| … | … | … | |
| ShippingOptions | Collection of or null | A list of shipping options. | |
| Method | String or null | The name of the delivery method (e.g. “NZ Courier”, “Rural Delivery”). Only applicable if ShippingType is Custom. | |
| ShippingId | Long Integer | The ID of the shipping option (used when bidding or for Buy Now). Not required when listing an item. | |
| … | … | … | … |
More refer to: Retrieve the details of a single listing
-
Example request
GET https://api.tmsandbox.co.nz/v1/Listings/2149295093.JSON
-
Example response
{
"ListingId": 2149295093,
...
"AllowsPickups": 3,
"ShippingOptions": [
{
"Type": 4,
"Price": 4.99,
"Method": "nationwide non-rural",
"ShippingId": 4
},
{
"Type": 4,
"Price": 9.99,
"Method": "rural",
"ShippingId": 5
},
{
"Type": 4,
"Price": 0,
"Method": "test free shipping",
"ShippingId": 6
}
],
...
}
API - Buy an auction using Buy Now
-
Business selection
Chained combination transactions
Retrieve your won items -> Remove a purchase from your won items list -> General search -> Retrieve the details of a single listing -> Buy an auction using Buy Now(I’m here)
Fetch ‘ListingId’ from the response of upstream transaction ‘General search ’ as one of the request fields.
Fetch ‘ShippingId’ from the response of upstream transaction ‘Retrieve the details of a single listing’ as one of the request fields.
-
API Function: Buys an item using Buy Now.
-
Front-end page - Item details page
Login > search a category > filter buynow item and go to item details page > Click Buy Now > Choose shipping way and confirm purchase
-
Front-end page - Confirm purchase page
-
Front-end page - Purchase details page
-
Front-end page - Won list page (purchased item shown on this page)
-
Key request fields
-
Key response fields - The details of the Buy Now request.
| Success | Boolean | Indicates whether the operation was successful. | |
| Description | String or null | The description of the error, if the operation failed. | |
| StatusCode | Enumeration | The status of the Buy Now request. | |
| Success | 0 | The bid was a success. | |
| … | … | … | … |
| PurchaseId | Long Integer | The ID of the purchase that was just made. | |
| … | … | … | … |
More refer to: Buy an auction using Buy Now
-
Example request
POST https://api.tmsandbox.co.nz/v1/Bidding/BuyNow.JSON
-
Example response
{
"Success": true,
"Description": "Seller's email owen4@snipesoft.net.nz",
"StatusCode": 0,
"PurchaseId": 26231
}