Overview
Customers can place orders via Parts.Cat.Com (PCC) and choose Pickup or Delivery as their preferred fulfillment option. Upon receipt of the order (Document), the dealer will fulfill the order.
Parts.cat.com – Order Tracking v3 is a restful API that enables the Dealer system to post fulfillment updates back to PCC and send an email notification to the customer via email. PCC will store the dealer provided updates to both notify the customer via email and show updated status on PCC. This API can be used for orders with any fulfillment type (shipping, pickup, and dropbox).
This document provides the detailed information for using the API.
Order Status & Flow
Following is the suggested flow for Order Status, Dealer system manages the Order Status, status flow and the quantity fulfilled.
Following is the list of supported status codes and the required status helps to have the order full life cycle updated to the customer.
| Status Code | Status Description | Required for Dealer to Send |
|---|---|---|
| DL | Delivered | Required |
| PS | Partially Shipped | Required |
| FS | Fully Shipped | Required |
| PU | Picked Up | Required |
| RP | Ready for Pickup | Required |
| PA | Ready for Partial Pick Up | Required |
| OH | On Hold | Recommended |
| OR | Order Released | Recommended |
| OC | Order Cancelled | Recommended |
| EX | Exception | Recommended |
Following table gives guidelines towards the optional values
- M - Required
- O - Optional or per dealer business process
- X - Not Applicable
| Field Name / Status | DL | PS | FS | PU | RP | PA | OH | OR | OC | EX |
|---|---|---|---|---|---|---|---|---|---|---|
| trackingId | O | M | M | X | X | X | X | X | O | O |
| trackingUrl | O | O | O | X | X | X | X | X | O | O |
| carrier | O | O | M | X | X | X | X | X | O | O |
| shipmentDate | O | M | M | X | X | X | X | X | O | O |
API Usage Guidelines
Parts.cat.com – Order Tracking v3 API performs the minimum validation to ensure the update from the Dealer System is for PCC Orders only and matching to the part numbers in the order.
It is the responsibility of the dealer system to maintain order data integrity by ensuring the updates sent back to PCC are accurate and appropriate. Such as
- Shipment vs Pickup vs Dropbox vs Other
- Quantity fulfilled
- Carrier information and the tracking number
- Order Status and sequence
Dealer also shall:
- Avoid duplicate notifications
- To ensure performance and availability of the platform, Caterpillar will enforce rate limiting for this API and optimize the number accordingly. In an event, the system is busy processing other requests, the system will return back with an error code 429 for the dealer system to retry. Dealers are encouraged to proactively communicate anticipated number of peak & average calls per hour by notifying Cat Support team.
Email Notifications
- Post update from dealer, by default PCC generates an email notification to all customers.
- Customers can self-manage the email notification preferences in PCC My Account under the Your Profile – Notification Preferences section. Dealers need to enable the Customer self-manage feature by submitting a ticket to the helpdesk. Helpdesk team would enable this in the DMT Tool.
Subscribing to the API
To access the API, you must first request a subscription:
- Fill out the API Subscription Request Form:
- Commercial Subscription Owner Details: Enter the dealer contact CWS ID, name, phone number, address, and your dealer codes or UCIDs. Make sure to enter all dealer codes or UCIDs that require API access.
- Team Details: Created a new team by selecting "Yes" and filling out the team name and description.
- App Details: Once a team has been created or selected then the App Details can be filled to add the Application Name and Description which will be built using the API.
- Client ID Details: Request a new client ID.
- API Product Use Case Details: Enter the details for how the API will be used.
- You will receive an email with your credentials when your subscription is approved. This process may take approximately two (2) weeks.
Notes:
- You will receive separate sets of credentials for every dealer code you entered.
- For every dealer code, you will receive two (2) separate sets of credentials for production and QA environments.
Security
The API uses the OAuth 2.0 protocol for authorization. In order to access the API, an OAuth access token is required in the request headers of each API call. A valid OAuth client ID and client secret is required to obtain an OAuth access token.
The following basic information is required to authenticate and generate the token.
| Field | Value |
|---|---|
| Grant Type | Set this to "client_credentials". |
| Token URL | Production: https://fedlogin.cat.com/as/token.oauth2 QA: https://fedloginqa.cat.com/as/token.oauth2 |
| Client ID | Your application's Client ID. Contact your credentials owner. |
| Client Secret | Your application's Client Secret. Contact your credentials owner. |
An OAuth token expires after 60 minutes. An expired token will need to be replaced with a new token.
Additional OAuth information can be found in Caterpillar OAuth 2.0 Documentation
DNS Cache TTL
What is DNS TTL?
DNS (Time to Live) is a setting that informs the DNS resolver how long the DNS entry would be valid, and any caching of the DNS entry should be within the TTL.
Why is this important?
Applications that inadvertently cache the DNS entries beyond the DNS set TTL (i.e., not honoring the TTL) risk impacting the functional capability if the DNS entry becomes invalid. And in most cases, the only fix is to restart the client applications to refresh the DNS.
CAT Commerce:
Shop.cat.com, Parts.Cat.com, and api.cat.com are examples of a few critical domains to integrate with the CAT Commerce applications. Applications that integrate to CAT Commerce are expected to honor the DNS standard and best practice to avoid system impact.
- Applications should follow the DNS caching best practice and honor the TTL provided by Cat (api.cat.com)
- DNS TTL can be verified online using portals such as https://toolbox.googleapps.com/apps/dig/
Accessing the API
Use these URLs to access the APIs:
- Production: https://api.cat.com/eCommerce/orderTracking/v3/tracking
- QA: https://api-qa.cat.com/eCommerce/orderTracking/v3/tracking
Note: Make sure to use the correct OAuth 2.0 API credentials depending on the target environment (QA or Production).
When QA environment is accessed, an additional header is required to specify which PCC QA environment to route the request to. QA environments will have different code bases. Cat Support can help determine which QA environment to use.
Information on current QA environment status: https://caterpillar.sharepoint.com/teams/PCCUATCollaborationTeam
Header: x-cat-qa-env Valid values: "qa1parts", "qa2parts", "qa3parts"
API Reference Information
For detailed information about the API input parameters, response structure, and error messages, see the API reference documentation.
Request body
| Field Name | Datatype | Length | Required | Example | Comments |
|---|---|---|---|---|---|
| dealerCode | String | 4 | Y | TD00 | Four-digit dealer code |
| documentNumber | String | 30 | Y | 00C12345 | Dealer document number |
| documentStatus | String | 2 | Y | PS | Status at document level. This field determines what status to show in PCC and what email to send to the customer. This field maps 1-1 with the shippedStatus field in V2. |
| fulfillment | Object | 1 | |||
| fulfillment:type | String | 10 | Y | delivery | Valid values: "delivery", "pickup", "dropbox" |
| fulfillment:status | String | 2 | N | FS | Status at fulfillment level. This status will be used in the future on parts.cat.com, any values being passed will not be processed. |
| fulfillment:parts | Object Array | 500 | |||
| fulfillment:parts:partNumber | String | 8 | Y | 1R-1808 | Part number. The hyphen is optional; both 1R-1808 and 1R1808 are valid inputs. |
| fulfillment:parts:quantity | Integer | 5 | Y | 1 | Quantity |
| fulfillment:parts:status | String | 2 | N | PS | Status at item level. This status will be used in the future on parts.cat.com, any values being passed will not be processed. |
| fulfillment:shipmentInformation | Object | 1 | |||
| fulfillment:shipmentInformation:carrier | String | 20 | Required to show order tracking link in PCC | FedEx | Name of carrier |
| fulfillment:shipmentInformation:shipmentDate | String | 10 | Required to show order tracking link in PCC | 2022-10-11 | Shipped date |
| fulfillment:shipmentInformation:shipmentMethod | String | 20 | Required to show order tracking link in PCC | Ground | Shipping method |
| fulfillment:shipmentInformation:trackingId | String | 40 | Required to show order tracking link in PCC | 1Z78912345 | Shipment tracking number |
| fulfillment:shipmentInformation:trackingUrl | String | 254 | N | https://www.fedex.com/apps/fedextrack/?action=track&trackingnumber=1Z78912345 | Fully qualified carrier tracking URL with tracking number |
| fulfillment:customFields | Object | 1 | N | "field1": "Test data" | This field will be used in the future on parts.cat.com, any values being passed will not be processed. |
Fields for future use
V3 service includes fields reserved for future use (not in use on PCC today):
- fulfillment:status
- Status at fulfillment level. This status will be used in the future on parts.cat.com, any values being passed will not be processed.
- fulfillment:parts:status
- Status at item level. This status will be used in the future on parts.cat.com, any values being passed will not be processed.
- fulfillment:customFields
- This field will be used in the future on parts.cat.com, any values being passed will not be processed.
Parts.cat.com – Order Tracking v3 API
Shipment tracking information will be send to PCC using POST /orderTracking/v3/tracking endpoint. Use the storeId query parameter with the value 21801.
curl -v -X POST
"https://api.cat.com/eCommerce/orderTracking/v3/tracking?storeId=21801"-H "Authorization: Bearer {access token}"-H "Content-Type: application/json"-data: "{"dealerCode": "TD00","documentNumber": "00C170765","documentStatus": "PU","fulfillment": {"type": "pickup","status": "PU","parts": [{"partNumber": "1R-1808","quantity": 1,"status": "PU"},{"partNumber": "1A-1135","quantity": 1,"status": "PU"}]}}"
Request
Below are the supported case sensitive request field definitions in the API:
Fulfillment type delivery:
{
"dealerCode": "TD00",
"documentNumber": "00C112685",
"documentStatus": "PS",
"fulfillment": {
"type": "delivery",
"status": "",
"parts": [{
"partNumber": "1R-1801",
"quantity": 6,
"status": ""
},
{
"partNumber": "1R-1808",
"quantity": 4,
"status": ""
},
{
"partNumber": "1A-1135",
"quantity": 10,
"status": ""
}
],
"shipmentInformation": {
"carrier": "Fedex",
"shipmentDate": "2021-04-30",
"shipmentMethod": "BEST WAY",
"trackingId": "555",
"trackingUrl": "http://www.fedex.com/tracking5"
},
"customFields": {
"field1": "Test data",
"field2": "Test data"
}
}
}
Fulfillment type pickup or dropbox:
{
"dealerCode": "TD00",
"documentNumber": "00C112685",
"documentStatus": "PU",
"fulfillment": {
"type": "pickup",
"status": "",
"parts": [{
"partNumber": "1R-1801",
"quantity": 6,
"status": ""
},
{
"partNumber": "1R-1808",
"quantity": 4,
"status": ""
},
{
"partNumber": "1A-1135",
"quantity": 10,
"status": ""
}
],
"customFields": {
"field1": "Test data",
"field2": "Test data"
}
}
}
Response
Success: 204 (No Content) Error: 400 (Bad Request)
Error response codes
If 400 Bad Request response is received, body will contain an error code. Possible error codes:
| Code | Error Description | Notes |
|---|---|---|
| 110 | MISSING_DEALER_CODE | Dealer code is missing in the request |
| 120 | MISSING_DOCUMENT_NUMBER | Document number is missing in the request |
| 130 | MISSING_TRACKING_ID | Tracking ID is missing in the request |
| 140 | MISSING_TRACKING_URL_CARRIER | Carrier is missing in the request |
| 150 | MISSING_PARTS | Parts are missing in the request |
| 160 | MISSING_SHIP_DATE | Ship date is missing in the request |
| 165 | INVALID_SHIP_DATE | Ship date is not valid |
| 170 | INVALID_DEALER_CODE | Dealer code is not valid |
| 180 | MISSING_DOCUMENT_STATUS | Document status is missing in the request |
| 185 | INVALID_DOCUMENT_STATUS | Document status is not valid |
| 190 | INVALID_DOCUMENT_NUMBER | Document number is not valid |
| 195 | MISSING_FULFILLMENT_DETAILS | Fulfillment object is missing in the request |
| 200 | INVALID_FULFILLMENT_STATUS | Fulfillment status is not valid |
| 205 | INVALID_PART_STATUS | Part level status is not valid |
| 250 | INVALID_PARTS_LIST | Parts object is not valid |
| 403 | AUTHENTICATION_ERROR |
Testing Procedures
Dealer functional and non-functional test planning, test requirements and test schedules are to be coordinated and approved by the Caterpillar support team.
Dealers shall ensure by working with the service department personnel within the dealer team to gather the performance load requirements and include it as part of dealer testing plan.
Recommended testing scenarios:
- Partial shipments
- Full shipments
- Partial Pickup
- Pickup
- Order Cancellation
- Order Released
Test validation for each scenario:
- Notification email gets sent to the customer
- Updated Order status shown on PCC Order History. Dealers can use one of the PCC QA environments for testing needs.
Placing Test PCC Order:
Follow these steps to gain access to the QA environments from the internet:
- Visit https://{qa-domain}/wcs-static/getMyCookie.html
- Answer the question. A session cookie will be created to allow access to the environment.
- This session cookie is used to provide access to PCC QA environment from the internet (off Cat network).
Testing the Shipment Tracking API:
- For the browser-based testing or plug ins, a session cookie is sufficient.
- For the server-side testing, a dealer VPN (Virtual Private Network) connection may be required. Reach out to the Cat Support team for further assistance.
Changes from V2 to V3
Authentication Changes
OAuth 2.0 token is used for authentication with V3 service. "shipmentTrackUserName" and "shipmentTrackPassword" fields are no longer used. More details are available in "Security" section of this document.
V2 to V3 JSON request structure mapping
| V2 Field | V3 Field |
|---|---|
| trackingId | shipmentInformation:trackingId |
| trackingURL | shipmentInformation:trackingUrl |
| shipCarrier | shipmentInformation:carrier |
| shipDate | shipmentInformation:shipmentDate |
| shipMethod | shipmentInformation:shipmentMethod |
| parts (String[]) | parts (Object[]) |
| onlyShippedStatusFlag | Field removed. PCC will show the tracking information if it is provided in the "shipmentInformation" object. |
| shippedStatus | documentStatus |
| shipmentTrackUserName | Field Removed. OAuth 2.0 token is used for authentication. More details are available in "Security" section of this document. |
| shipmentTrackPassword | Field Removed. OAuth 2.0 token is used for authentication. More details are available in "Security" section of this document. |
| dealerCustomerCheck | Field Removed |
New V3 JSON request fields
- fulfillment:type
- Valid values: "delivery", "pickup", "dropbox"
- fulfillment:status
- Status at fulfillment level. This status will be used in the future on parts.cat.com, any values being passed will not be processed.
- fulfillment:parts:status
- Status at item level. This status will be used in the future on parts.cat.com, any values being passed will not be processed.
- customFields
- This field will be used in the future on parts.cat.com, any values being passed will not be processed.
Migration from V2 service to V3 service
- This document only applies to V3 service
- With the launch of V3 service, V2 is considered deprecated
- V2 service will continue to to be functional for a period of time and that DICE document is still valid
- Cat Support team will communicate planned retirement for V2 service when it is known
- Users of V2 service are encouraged to migrate to V3 as soon as possible
- V3 offers security enhancements along with fulfillment and line item status fields to be used in the future on Parts.Cat.Com
- Dealers need to apply for V3 access using the method noted above in "Subscribing to the API" section, even if they already have access to V2 service
- All data previously sent to the V2 service will still be accessible in PCC, data does not need to be resent
- Request body payload is updated in V3, see "V2 to V3 JSON request structure mapping" section
Links
Glossary
PCC (Parts.Cat.com)
Customer application for convenient parts ordering from dealers that provides parts pricing and availability as well as replacement and reman parts from the dealer’s management system. To maximize update and ensure correct parts are chosen, it provides 24/7 customer access to SIS (Service Information System) parts books, Planned Maintenance Checklist, Related Parts, and General Parts Information. Includes optional access to Core Tracking, order status e-mails, credit card payments, multiple shipping methods, hose Assembly information, etc.
Change History
| Date | Author | Description of Change |
|---|---|---|
| 09-28-2022 | Vidya Gowda | New document |
| 10-11-2022 | Steve Sefton | Document clean up |
