From 45f72c3ae5c5bf8082fd1b62637abd6141109294 Mon Sep 17 00:00:00 2001 From: Justintime50 <39606064+Justintime50@users.noreply.github.com> Date: Thu, 6 Nov 2025 10:23:45 -0700 Subject: [PATCH] feat: add retrieveBatch tracker function --- CHANGELOG.md | 1 + .../com/easypost/service/TrackerService.java | 16 ++ .../cassettes/tracker/retrieve_batch.json | 186 ++++++++++++++++++ src/test/java/com/easypost/TrackerTest.java | 21 ++ 4 files changed, 224 insertions(+) create mode 100644 src/test/cassettes/tracker/retrieve_batch.json diff --git a/CHANGELOG.md b/CHANGELOG.md index 531483458..cb72770da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## Next Release - Adds support for `UspsShipAccount` +- Adds `tracker.retrieveBatch` function ## v8.2.0 (2025-06-18) diff --git a/src/main/java/com/easypost/service/TrackerService.java b/src/main/java/com/easypost/service/TrackerService.java index 74bf69c11..edafe481c 100644 --- a/src/main/java/com/easypost/service/TrackerService.java +++ b/src/main/java/com/easypost/service/TrackerService.java @@ -100,4 +100,20 @@ public TrackerCollection apply(Map parameters) { } }, collection.getTrackers(), pageSize); } + + /** + * Retrieve a batch of Tracker objects. + * + * @param params Map of parameters used to filter the list of Trackers. + * @return TrackerCollection object. + * @throws EasyPostException when the request fails. + */ + public TrackerCollection retrieveBatch(final Map params) throws EasyPostException { + String endpoint = "trackers/batch"; + + TrackerCollection trackerCollection = + Requestor.request(RequestMethod.POST, endpoint, params, TrackerCollection.class, client); + + return trackerCollection; + } } diff --git a/src/test/cassettes/tracker/retrieve_batch.json b/src/test/cassettes/tracker/retrieve_batch.json new file mode 100644 index 000000000..8f6518de1 --- /dev/null +++ b/src/test/cassettes/tracker/retrieve_batch.json @@ -0,0 +1,186 @@ +[ + { + "recordedAt": 1762449778, + "request": { + "body": "{\n \"tracker\": {\n \"carrier\": \"USPS\",\n \"tracking_code\": \"EZ1000000001\"\n }\n}", + "method": "POST", + "headers": { + "Accept-Charset": [ + "UTF-8" + ], + "User-Agent": [ + "REDACTED" + ], + "Content-Type": [ + "application/json" + ] + }, + "uri": "https://api.easypost.com/v2/trackers" + }, + "response": { + "body": "{\n \"fees\": [\n {\n \"amount\": \"0.02000\",\n \"refunded\": false,\n \"type\": \"TrackerFee\",\n \"charged\": false,\n \"object\": \"Fee\"\n }\n ],\n \"carrier_detail\": {\n \"est_delivery_date_local\": null,\n \"origin_location\": \"HOUSTON TX, 77001\",\n \"destination_tracking_location\": null,\n \"guaranteed_delivery_date\": null,\n \"est_delivery_time_local\": null,\n \"service\": \"First-Class Package Service\",\n \"container_type\": null,\n \"initial_delivery_attempt\": null,\n \"origin_tracking_location\": {\n \"zip\": \"77063\",\n \"country\": null,\n \"city\": \"HOUSTON\",\n \"state\": \"TX\",\n \"object\": \"TrackingLocation\"\n },\n \"destination_location\": \"CHARLESTON SC, 29401\",\n \"alternate_identifier\": null,\n \"object\": \"CarrierDetail\"\n },\n \"created_at\": \"2025-11-06T17:22:58Z\",\n \"weight\": null,\n \"tracking_details\": [\n {\n \"tracking_location\": {\n \"zip\": null,\n \"country\": null,\n \"city\": null,\n \"state\": null,\n \"object\": \"TrackingLocation\"\n },\n \"est_delivery_date\": null,\n \"datetime\": \"2025-10-06T17:22:58Z\",\n \"description\": null,\n \"source\": \"USPS\",\n \"message\": \"Pre-Shipment Info Sent to USPS\",\n \"object\": \"TrackingDetail\",\n \"status\": \"pre_transit\",\n \"status_detail\": \"status_update\",\n \"carrier_code\": null\n },\n {\n \"tracking_location\": {\n \"zip\": \"77063\",\n \"country\": null,\n \"city\": \"HOUSTON\",\n \"state\": \"TX\",\n \"object\": \"TrackingLocation\"\n },\n \"est_delivery_date\": null,\n \"datetime\": \"2025-10-07T05:59:58Z\",\n \"description\": null,\n \"source\": \"USPS\",\n \"message\": \"Shipping Label Created\",\n \"object\": \"TrackingDetail\",\n \"status\": \"pre_transit\",\n \"status_detail\": \"status_update\",\n \"carrier_code\": null\n }\n ],\n \"shipment_id\": null,\n \"tracking_code\": \"EZ1000000001\",\n \"status_detail\": \"status_update\",\n \"mode\": \"test\",\n \"finalized\": true,\n \"public_url\": \"https://track.easypost.com/djE6dHJrXzJlNWJmZTAyZTE3MTRjODU5MDdiYTdhYTU2ODI1NDI3\",\n \"est_delivery_date\": \"2025-11-06T17:22:58Z\",\n \"carrier\": \"USPS\",\n \"delivery_evidence\": [],\n \"is_return\": false,\n \"updated_at\": \"2025-11-06T17:22:58Z\",\n \"signed_by\": null,\n \"id\": \"trk_2e5bfe02e1714c85907ba7aa56825427\",\n \"object\": \"Tracker\",\n \"status\": \"pre_transit\"\n}", + "httpVersion": null, + "headers": { + "null": [ + "HTTP/1.1 201 Created" + ], + "content-length": [ + "1797" + ], + "expires": [ + "0" + ], + "x-node": [ + "bigweb32nuq" + ], + "x-frame-options": [ + "SAMEORIGIN" + ], + "x-download-options": [ + "noopen" + ], + "x-permitted-cross-domain-policies": [ + "none" + ], + "x-backend": [ + "easypost" + ], + "pragma": [ + "no-cache" + ], + "strict-transport-security": [ + "max-age\u003d31536000; includeSubDomains; preload" + ], + "x-canary": [ + "direct" + ], + "x-xss-protection": [ + "1; mode\u003dblock" + ], + "x-content-type-options": [ + "nosniff" + ], + "x-ep-request-uuid": [ + "a777ff39690cd972e2aac1950102100a" + ], + "x-proxied": [ + "intlb6nuq c0061e0a2e", + "extlb1nuq cbbd141214" + ], + "referrer-policy": [ + "strict-origin-when-cross-origin" + ], + "x-runtime": [ + "0.172763" + ], + "location": [ + "/api/v2/trackers/trk_2e5bfe02e1714c85907ba7aa56825427" + ], + "content-type": [ + "application/json; charset\u003dutf-8" + ], + "x-version-label": [ + "easypost-202511061639-9e7dc69a6b-master" + ], + "cache-control": [ + "private, no-cache, no-store" + ] + }, + "status": { + "code": 201, + "message": "Created" + }, + "uri": "https://api.easypost.com/v2/trackers" + }, + "duration": 287 + }, + { + "recordedAt": 1762449778, + "request": { + "body": "{\n \"tracking_codes\": [\n \"EZ1000000001\"\n ]\n}", + "method": "POST", + "headers": { + "Accept-Charset": [ + "UTF-8" + ], + "User-Agent": [ + "REDACTED" + ], + "Content-Type": [ + "application/json" + ] + }, + "uri": "https://api.easypost.com/v2/trackers/batch" + }, + "response": { + "body": "{\n \"trackers\": [\n {\n \"fees\": [\n {\n \"amount\": \"0.02000\",\n \"refunded\": false,\n \"type\": \"TrackerFee\",\n \"charged\": true,\n \"object\": \"Fee\"\n }\n ],\n \"carrier_detail\": {\n \"est_delivery_date_local\": null,\n \"origin_location\": \"HOUSTON TX, 77001\",\n \"destination_tracking_location\": null,\n \"guaranteed_delivery_date\": null,\n \"est_delivery_time_local\": null,\n \"service\": \"First-Class Package Service\",\n \"container_type\": null,\n \"initial_delivery_attempt\": null,\n \"origin_tracking_location\": {\n \"zip\": \"77063\",\n \"country\": null,\n \"city\": \"HOUSTON\",\n \"state\": \"TX\",\n \"object\": \"TrackingLocation\"\n },\n \"destination_location\": \"CHARLESTON SC, 29401\",\n \"alternate_identifier\": null,\n \"object\": \"CarrierDetail\"\n },\n \"created_at\": \"2025-11-06T17:22:58Z\",\n \"weight\": null,\n \"tracking_details\": [\n {\n \"tracking_location\": {\n \"zip\": null,\n \"country\": null,\n \"city\": null,\n \"state\": null,\n \"object\": \"TrackingLocation\"\n },\n \"est_delivery_date\": null,\n \"datetime\": \"2025-10-06T17:22:58Z\",\n \"description\": \"\",\n \"source\": \"USPS\",\n \"message\": \"Pre-Shipment Info Sent to USPS\",\n \"object\": \"TrackingDetail\",\n \"status\": \"pre_transit\",\n \"status_detail\": \"status_update\",\n \"carrier_code\": \"\"\n },\n {\n \"tracking_location\": {\n \"zip\": \"77063\",\n \"country\": null,\n \"city\": \"HOUSTON\",\n \"state\": \"TX\",\n \"object\": \"TrackingLocation\"\n },\n \"est_delivery_date\": null,\n \"datetime\": \"2025-10-07T05:59:58Z\",\n \"description\": \"\",\n \"source\": \"USPS\",\n \"message\": \"Shipping Label Created\",\n \"object\": \"TrackingDetail\",\n \"status\": \"pre_transit\",\n \"status_detail\": \"status_update\",\n \"carrier_code\": \"\"\n }\n ],\n \"shipment_id\": null,\n \"tracking_code\": \"EZ1000000001\",\n \"status_detail\": \"status_update\",\n \"mode\": \"test\",\n \"public_url\": \"https://track.easypost.com/djE6dHJrXzJlNWJmZTAyZTE3MTRjODU5MDdiYTdhYTU2ODI1NDI3\",\n \"est_delivery_date\": \"2025-11-06T17:22:58Z\",\n \"carrier\": \"USPS\",\n \"delivery_evidence\": [],\n \"updated_at\": \"2025-11-06T17:22:58Z\",\n \"signed_by\": null,\n \"id\": \"trk_2e5bfe02e1714c85907ba7aa56825427\",\n \"object\": \"Tracker\",\n \"status\": \"pre_transit\"\n }\n ],\n \"has_more\": false\n}", + "httpVersion": null, + "headers": { + "null": [ + "HTTP/1.1 200 OK" + ], + "content-length": [ + "1785" + ], + "expires": [ + "0" + ], + "x-node": [ + "bigweb55nuq" + ], + "x-frame-options": [ + "SAMEORIGIN" + ], + "x-download-options": [ + "noopen" + ], + "x-permitted-cross-domain-policies": [ + "none" + ], + "x-backend": [ + "easypost" + ], + "pragma": [ + "no-cache" + ], + "strict-transport-security": [ + "max-age\u003d31536000; includeSubDomains; preload" + ], + "x-xss-protection": [ + "1; mode\u003dblock" + ], + "x-content-type-options": [ + "nosniff" + ], + "x-ep-request-uuid": [ + "a777ff3b690cd972e2aac19701021096" + ], + "x-proxied": [ + "intlb5nuq c0061e0a2e", + "extlb1nuq cbbd141214" + ], + "referrer-policy": [ + "strict-origin-when-cross-origin" + ], + "x-runtime": [ + "0.062892" + ], + "content-type": [ + "application/json; charset\u003dutf-8" + ], + "x-version-label": [ + "easypost-202511061639-9e7dc69a6b-master" + ], + "cache-control": [ + "private, no-cache, no-store" + ] + }, + "status": { + "code": 200, + "message": "OK" + }, + "uri": "https://api.easypost.com/v2/trackers/batch" + }, + "duration": 178 + } +] \ No newline at end of file diff --git a/src/test/java/com/easypost/TrackerTest.java b/src/test/java/com/easypost/TrackerTest.java index 4b686315d..99baa8fda 100644 --- a/src/test/java/com/easypost/TrackerTest.java +++ b/src/test/java/com/easypost/TrackerTest.java @@ -207,4 +207,25 @@ public Map getNextPageParams() throws EndOfPaginationError { assertEquals(trackingCode, nextPageParams.get("tracking_code")); assertEquals(carrier, nextPageParams.get("carrier")); } + + /** + * Test retrieving a batch of trackers. + * + * @throws EasyPostException when the request fails. + */ + @Test + public void testRetrieveBatch() throws EasyPostException { + vcr.setUpTest("retrieve_batch"); + + Tracker tracker = createBasicTracker(); + + Map params = new HashMap<>(); + params.put("tracking_codes", ImmutableList.of(tracker.getTrackingCode())); + + TrackerCollection trackers = vcr.client.tracker.retrieveBatch(params); + + List trackersList = trackers.getTrackers(); + + assertTrue(trackersList.stream().allMatch(singleTracker -> singleTracker != null)); + } }