Difference between revisions of "Api.heavytruckparts.net"
(→Part Inquiry: Added comments field to parameters) |
(→Listing Sales Documents: Add the supported filters for /sale/list) |
||
(24 intermediate revisions by the same user not shown) | |||
Line 24: | Line 24: | ||
So how is a request made? Assuming that you have a valid API User and know how to make the request, providing that user and password via Basic authentication, API requests are just HTTP GET requests: | So how is a request made? Assuming that you have a valid API User and know how to make the request, providing that user and password via Basic authentication, API requests are just HTTP GET requests: | ||
<nowiki>https://api.heavytruckparts.net/inventory/search/<part type>/<make or manufacturer>/<model>?<filter options></nowiki> | <nowiki>https://api.heavytruckparts.net/inventory/search/<part type>/<make or manufacturer>/<model>?<filter options></nowiki> | ||
The request should be URI | The request should be URI encoded: | ||
<nowiki>https://api.heavytruckparts.net/inventory/search/Engine%20Assembly/CUMMINS/ISX?year_range=2013,2015&zipcode=68503&distance=100</nowiki> | <nowiki>https://api.heavytruckparts.net/inventory/search/Engine%20Assembly/CUMMINS/ISX?year_range=2013,2015&zipcode=68503&distance=100</nowiki> | ||
The requirement for URI encoding includes all elements, including the make or manufacturer and model. If you don't URI encode these elements, unencoded spaces, slashes, or other characters will cause incorrect, invalid, or empty results. | |||
*Part Type: The part type is specified on the URL as the first part. This may be a string or numeric value; it will be mapped to the appropriate value for HTP.Net based on your API user. This is a many-to-many mapping: You may have a part type that maps to many HTP.Net part types, or many part types that map to a single HTP.Net part type. | *Part Type: The part type is specified on the URL as the first part. This may be a string or numeric value; it will be mapped to the appropriate value for HTP.Net based on your API user. This is a many-to-many mapping: You may have a part type that maps to many HTP.Net part types, or many part types that map to a single HTP.Net part type. | ||
Line 36: | Line 37: | ||
**keywords: a space-separated list of keywords to perform a keyword search with. The keyword search looks for ALL keywords, but can be structured via pipe (|) operators for OR behavior. For example, keywords=(first set of search terms)|(second set of search terms) | **keywords: a space-separated list of keywords to perform a keyword search with. The keyword search looks for ALL keywords, but can be structured via pipe (|) operators for OR behavior. For example, keywords=(first set of search terms)|(second set of search terms) | ||
**category: an item category to limit the results by. This is usually something like "NEW", "USED", or "CORE", but a full availability list for Categories can be requested (see Availability Lists below) | **category: an item category to limit the results by. This is usually something like "NEW", "USED", or "CORE", but a full availability list for Categories can be requested (see Availability Lists below) | ||
**:By specifying the category option as an array, more than one category can be selected. E.g. category[]=NEW&category[]=USED | |||
**store: a comma-separated list of store id values to restrict the results to. An empty list provides the default filter of "all stores." Use of this parameter requires knowing the store id value, assigned in ITrack, of the store or stores search results should be filtered to. | **store: a comma-separated list of store id values to restrict the results to. An empty list provides the default filter of "all stores." Use of this parameter requires knowing the store id value, assigned in ITrack, of the store or stores search results should be filtered to. | ||
**userid: the end-user id, representing a person using the website or webapp which relies on the API. Pricing and other values in the results can be customized based on this value. | **userid: the end-user id, representing a person using the website or webapp which relies on the API. Pricing and other values in the results can be customized based on this value. | ||
**page_number: the results are separated into separate "pages" results. This value indicates which "page" in the results should be returned. | **page_number: the results are separated into separate "pages" results. This value indicates which "page" in the results should be returned. | ||
**result_size: the number of results to be returned "per page." This value can be an integer count of results (the default is 25) or the word "all." Please note that specifying "all" or a large number can result in very poor search performance. Additionally, depending on the user configuration, the search may have specific requirements before this parameter takes effect: For non-vendor specific searches and/or large values of result_size, the API may require a part type, make, model, and enduserid to be specified. "Body" or "Vehicle" parts may require a year or year range to specified. If these values are not specified in the search, the API may ignore the result_size parameter and present the default 25 result page size. Please contact ISoft Data Systems if you have questions regarding result_size support and strict search requirements for page sizing for your specific API user requests. | **result_size: the number of results to be returned "per page." This value can be an integer count of results (the default is 25) or the word "all." Please note that specifying "all" or a large number can result in very poor search performance. Additionally, depending on the user configuration, the search may have specific requirements before this parameter takes effect: For non-vendor specific searches and/or large values of result_size, the API may require a part type, make, model, and enduserid to be specified. "Body" or "Vehicle" parts may require a year or year range to specified. If these values are not specified in the search, the API may ignore the result_size parameter and present the default 25 result page size. Please contact ISoft Data Systems if you have questions regarding result_size support and strict search requirements for page sizing for your specific API user requests. | ||
**sort_column: the column in the results that the results should be sorted by. The default is "price," unless a zip code is specified, and then the default is "distance." Allowable values are "part_name", "make_model", "year", "oem_number", "vendor_sku", "description", "price", "coreprice", "condition", "type", "distance", "vendor", and " | **sort_column: the column in the results that the results should be sorted by. The default is "price," unless a zip code is specified, and then the default is "distance." Allowable values are "part_name", "make_model", "year", "oem_number", "vendor_sku", "description", "price", "coreprice", "condition", "type", "distance", "vendor", "date_added", and "date_updated". | ||
**sort_order: the "direction" the sort_column should be sorted on. The default is "ascending". Allowable values are "ascending" and "descending" (or the abbreviations "asc" and "desc"). | **sort_order: the "direction" the sort_column should be sorted on. The default is "ascending". Allowable values are "ascending" and "descending" (or the abbreviations "asc" and "desc"). | ||
**show_suggested: an optional parameter which can be set to "1" or "true" to show suggested part types for a search. This only produces results for searches which do not have a part type set. This requests the API include links to more specific searches in the current search to "drill down" the search results. This may be turned on for an apiuser to affect all of their valid searches (without needing to be specified in the query string for the searches). | **show_suggested: an optional parameter which can be set to "1" or "true" to show suggested part types for a search. This only produces results for searches which do not have a part type set. This requests the API include links to more specific searches in the current search to "drill down" the search results. This may be turned on for an apiuser to affect all of their valid searches (without needing to be specified in the query string for the searches). | ||
**require_images: an optional parameter which can be set to "1" or "true" to limit the search results to only items which have images associated with them. | |||
**vendor: a comma-separated list of vendor id values to restrict the results to. An empty list provides the default filter of "all vendors configured for my API user." Use of this parameter requires knowing the vendor id values assigned by ISoft. These can also be found in the search results' vendor objects under "vendor_id". | **vendor: a comma-separated list of vendor id values to restrict the results to. An empty list provides the default filter of "all vendors configured for my API user." Use of this parameter requires knowing the vendor id values assigned by ISoft. These can also be found in the search results' vendor objects under "vendor_id". | ||
**filter: an optional parameter which can be used to apply one or more Q&A filters to the results. These filter options are separated by semicolons, the option is separated from allowed values by a colon, and allowed values are separated by commas. E.g. "filter=optionA:valueA;optionB:valueB1,valueB2" Please note that these are case-insensitive but otherwise require exact matches. The filter option string should be URL encoded, and, due to framework limitations, filter options are not permitted to have question marks in them. | |||
The exact search format can be customized for individual API users. In general, the search parts are "optional" but require a place holder (though in most cases, if some search parts are not used, a keyword search filter is encouraged to help narrow down search results). Due to the nature of URLs, something must be entered for each search component to form a valid URL. In a standard search URI, providing the "magic" character asterisk (*) for a search component will cause that search component to be ignored for the purposes of the search. For example, | The exact search format can be customized for individual API users. In general, the search parts are "optional" but require a place holder (though in most cases, if some search parts are not used, a keyword search filter is encouraged to help narrow down search results). Due to the nature of URLs, something must be entered for each search component to form a valid URL. In a standard search URI, providing the "magic" character asterisk (*) for a search component will cause that search component to be ignored for the purposes of the search. For example, | ||
Line 79: | Line 83: | ||
coreprice:"the core return price on the item, if any", | coreprice:"the core return price on the item, if any", | ||
condition:"the item's condition, as described by the vendor", | condition:"the item's condition, as described by the vendor", | ||
status: "the item's current status, e.g. 'Available', 'On Hold', or 'Sold'", | |||
date_entered: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was entered by the vendor", | |||
date_last_modified: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was last modified by the vendor", | |||
details_uri:"a URL to request for further information on this item", | details_uri:"a URL to request for further information on this item", | ||
images:["an array of URLs for images associated with this item"], | images:["an array of URLs for images associated with this item"], | ||
Line 112: | Line 119: | ||
coreprice:"the core return price on the item, if any", | coreprice:"the core return price on the item, if any", | ||
condition:"the item's condition, as described by the vendor", | condition:"the item's condition, as described by the vendor", | ||
status: "the item's current status, e.g. 'Available', 'On Hold', or 'Sold'", | |||
date_entered: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was entered by the vendor", | |||
date_last_modified: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was last modified by the vendor", | |||
details_uri:"a URL to request for further information on this item", | details_uri:"a URL to request for further information on this item", | ||
images:["an array of URLs for images associated with this item"], | images:["an array of URLs for images associated with this item"], | ||
Line 123: | Line 133: | ||
} | } | ||
Your API user can be configured to include inventory Q&A options directly in the search results. If you want Q&A to be included in your search results, please contact ISoft Data Systems and ask to have user option 'include_qa_in_search_results' set. If that option is enabled for your user, then the results will include a "qa" object with the "Q&A" fields for each item: | Your API user can be configured to include inventory Q&A options directly in the search results. If you want Q&A to be included in your search results, please contact ISoft Data Systems and ask to have user option 'include_qa_in_search_results' set. When Q&A are included in searches, Videos associated with the item, if any, will also be included in the results. If that option is enabled for your user, then the results will include a "qa" object with the "Q&A" fields for each item: | ||
{results: | {results: | ||
total_results: the total number of results for this search, | total_results: the total number of results for this search, | ||
Line 150: | Line 160: | ||
coreprice:"the core return price on the item, if any", | coreprice:"the core return price on the item, if any", | ||
condition:"the item's condition, as described by the vendor", | condition:"the item's condition, as described by the vendor", | ||
status: "the item's current status, e.g. 'Available', 'On Hold', or 'Sold'", | |||
date_entered: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was entered by the vendor", | |||
date_last_modified: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was last modified by the vendor", | |||
details_uri:"a URL to request for further information on this item", | details_uri:"a URL to request for further information on this item", | ||
images:["an array of URLs for images associated with this item"], | images:["an array of URLs for images associated with this item"], | ||
Line 157: | Line 170: | ||
"Q&A Key": "Q&A Value", | "Q&A Key": "Q&A Value", | ||
... | ... | ||
} | }, | ||
video: "video URL or Youtube video id, if available; if none is available, this parameter will not appear" | |||
} | } | ||
The vendor_sku value is the "Tag Number" of the item in ITrack, and is most useful as a display value for users. The vendor_sku is generally how a vendor recognizes the inventory item, but it not guaranteed to be unique in the vendor's sytem. The vendor_inventory_id is the back-end identifier for the item in the vendor's ITrack system, and is guaranteed to be unique for the item, but since it is a back-end identifier, it's not generally as useful to be displayed to website visitors as the vendor_sku. Notice that the details uri is based on vendor_id, vendor_store, and vendor_inventory_id. These three numeric identifiers are used to uniquely identify the item. | The vendor_sku value is the "Tag Number" of the item in ITrack, and is most useful as a display value for users. The vendor_sku is generally how a vendor recognizes the inventory item, but it not guaranteed to be unique in the vendor's sytem. The vendor_inventory_id is the back-end identifier for the item in the vendor's ITrack system, and is guaranteed to be unique for the item, but since it is a back-end identifier, it's not generally as useful to be displayed to website visitors as the vendor_sku. Notice that the details uri is based on vendor_id, vendor_store, and vendor_inventory_id. These three numeric identifiers are used to uniquely identify the item. | ||
Please note that the image URIs provided are for "full-size" images. If you are planning to display thumbnailed versions of the images, you can request a thumbnail directly by adding "w" (for width) and/or "h" (for height) request parameters to the image URI. These are treated as maximum values for the image, and the original aspect ratio will be maintained, so it is safe to provide both without worrying about distorting the image. | |||
The date_entered and date_last_modified fields are currently provided without timezone information. The time zone of the date-time value is assumed to be the local time zone of the vendor. As that information is not yet easily available from ITrack, it is not yet provided here. We apologize for any inconvenience. | |||
==Other Requests== | ==Other Requests== | ||
Line 181: | Line 199: | ||
vendor_inventory_id: 'Vendor's unique numeric ID for the item', | vendor_inventory_id: 'Vendor's unique numeric ID for the item', | ||
vendor_vehicle_id: 'Vendor's ID for the Vehicle or Whole Unit for the item, if available', | vendor_vehicle_id: 'Vendor's ID for the Vehicle or Whole Unit for the item, if available', | ||
vehicle_tracking_number: 'Tracking number of an associated vehicle, if available; will not be returned if unavailable', | |||
vehicle_mileage: 'Mileage of an associated vehicle, if available; will not be returned if unavailable', | |||
location: 'primary location of the inventory item, if available; will not be returned if unavailable', | |||
vin: 'VIN, if available', | vin: 'VIN, if available', | ||
core_price: 'core return price', | core_price: 'core return price', | ||
Line 188: | Line 209: | ||
condition: 'vendor specified item condition', | condition: 'vendor specified item condition', | ||
category: 'item category, i.e. USED, NEW, REMANUFACTURED', | category: 'item category, i.e. USED, NEW, REMANUFACTURED', | ||
status: 'the status of the item, i.e. AVAILABLE, ON HOLD, SOLD; only returned if activated for your apiuser', | |||
available_quantity: 'available quantity of item', | available_quantity: 'available quantity of item', | ||
side: 'side of vehicle item fits, if available and appropriate', | side: 'side of vehicle item fits, if available and appropriate', | ||
Line 194: | Line 216: | ||
... | ... | ||
}, | }, | ||
location: "the location of the item at the vendor's facility", | |||
date_created: 'the date and time the item was entered by the vendor, in YYYY-MM-DD hh:ii:ss format', | |||
date_last_modified: 'the date and time the item was last modified by the vendor, in YYYY-MM-DD hh:ii:ss format', | |||
video: 'video url or YouTube video id, if available; will not be returned if unavailable', | |||
vendor:{ | vendor:{ | ||
company:"company name", | company:"company name", | ||
Line 207: | Line 233: | ||
}, | }, | ||
images:["an array of URLs for images associated with this item"] | images:["an array of URLs for images associated with this item"] | ||
} | |||
==== Shipping Dimensions ==== | |||
Shipping dimensions and item weight are provided as Q&A elements when they are available. If they are not present or set for the item, they will not be included in the "qa" sub-object. If the item does have shipping dimensions set in ITrack, they are available in the qa sub-object as | |||
{ | |||
... | |||
shipping_length: "the length of the item as it would be shipped, as 'x in.'", | |||
shipping_width: "the width of the item as it would be shipped, as 'y in.'", | |||
shipping_height: "the height of the item as it would be shipped, as 'z in.'", | |||
weight: "the weight of the item as it would be shipped, as 'm lbs'", | |||
... | |||
} | |||
==== Item Videos ==== | |||
Videos of an item are entered by ITrack users as Q&A elements under the name "Video". This is usually a full URL to a video, in either "http(s)://www.youtube.com/watch?" or "http(s)://youtu.be/" formats. | |||
If a video is present, details->video will be present and not empty, and its value will contain the URL to the video. | |||
{ | |||
... | |||
'video': 'https://youtu.be/XXXXXXX' | |||
... | |||
} | |||
} | } | ||
===Available Lists=== | ===Available Lists=== | ||
Requests can be made to the API to fetch the complete list of part types, make/manufacturers, models, categories, and vendors for your API user. These results are customized to match your API user's mapping data (so the results can be used directly to produce search request URIs) and by default are limited to include just those part types, makes, manufacturers, models, and part categories that pertain to the result set returned to your API user in searches (the lists will not include part types that you wouldn't find in your search, for instance). The available vendor list will always provide all of the available vendors for your API User. The query string filter for part types is optional for makes (and part manufacturers, the API uses "make" for both vehicle makes and part manufacturers), models, and categories, and the filter for makes when getting available models is also optional. That said, it is strongly encouraged to specify a part type for category availability if vehicles or whole units may be included in all your possible search results, because the category field has a different contextual meaning between a whole unit and a component part. | Requests can be made to the API to fetch the complete list of part types, make/manufacturers, models, categories, and vendors for your API user. These results are customized to match your API user's mapping data (so the results can be used directly to produce search request URIs) and by default are limited to include just those part types, makes, manufacturers, models, and part categories that pertain to the result set returned to your API user in searches (the lists will not include part types that you wouldn't find in your search, for instance). The available vendor list will always provide all of the available vendors for your API User. The query string filter for part types is optional for makes (and part manufacturers, the API uses "make" for both vehicle makes and part manufacturers), models, and categories, and the filter for makes when getting available models is also optional. That said, it is strongly encouraged to specify a part type for category availability if vehicles or whole units may be included in all your possible search results, because the category field has a different contextual meaning between a whole unit and a component part. | ||
You may optionally pass the query string parameter of "all_results=true" if you want to include all of HeavyTruckParts.Net's possible choices, even if those options would not be found in your search results. You may optionally pass the query string parameter of "ignore_mapping=true" if you want to have the API ignore your possible mappings and return HTP's native results, rather providing you with the mapped value that matches your data. | You may optionally pass the query string parameter of "all_results=true" if you want to include all of HeavyTruckParts.Net's possible choices, even if those options would not be found in your search results. You may optionally pass the query string parameter of "ignore_mapping=true" if you want to have the API ignore your possible mappings and return HTP's native results, rather providing you with the mapped value that matches your data. Part type, make, and model lists support an optional "userid" parameter, which will use your end user availability for that user, if it is specified. | ||
<nowiki>https://api.heavytruckparts.net/inventory/available/part_types</nowiki> | <nowiki>https://api.heavytruckparts.net/inventory/available/part_types</nowiki> | ||
<nowiki>https://api.heavytruckparts.net/inventory/available/makes?part_type=<part type to filter make results by></nowiki> | <nowiki>https://api.heavytruckparts.net/inventory/available/makes?part_type=<part type to filter make results by></nowiki> | ||
Line 332: | Line 380: | ||
=== Parts Requests, Part Inquiries, and Logging Phone Calls and Emails === | === Parts Requests, Part Inquiries, and Logging Phone Calls and Emails === | ||
HeavyTruckParts.Net provides additional functionality to help support end user behaviors. This includes logging requests by end users for unlisted or unavailable items (parts requests), additional details on existing items (parts inquiries), and logging phone calls and contact emails from end users for inclusion in analytical and performance reports. | HeavyTruckParts.Net provides additional functionality to help support end user behaviors. This includes logging requests by end users for unlisted or unavailable items (parts requests), additional details on existing items (parts inquiries), and logging phone calls and contact emails from end users for inclusion in analytical and performance reports. | ||
Parts requests, part information inquiries, and contact emails all generate the requisite emails for the vendors -- it is not necessary to send any email messages (even with "logged emails") outside of the API. | |||
All of these are handled as variations of the enduser/log request. The request should be a PUT or POST request, with a JSON body, the contents of which is determined by the type of request. | All of these are handled as variations of the enduser/log request. The request should be a PUT or POST request, with a JSON body, the contents of which is determined by the type of request. | ||
==== Parts Request ==== | ==== Parts Request ==== | ||
To log an end user request for an item they could not find. | To log an end user request for an item they could not find. The entire "vehicle" object is optional, containing details about the vehicle for fitment. | ||
<nowiki>https://api.heavytruckparts.net/enduser/log/part_request</nowiki> | <nowiki>https://api.heavytruckparts.net/enduser/log/part_request</nowiki> | ||
{ | |||
'contact': { | |||
"contact": "<name of user to contact with item details>", | |||
"company": "<name of the user's company>", | |||
"address": "<user's street address>", | |||
"city": "<user's city>", | |||
"state": "<user's state/province>", | |||
"postal_code": "<user's zip or postal code>", | |||
"country" : "<user's country>", | |||
"phone_number": "<user's phone number>", | |||
"email": "<user's email address>", | |||
"preferred_contact_method": "<the way the user would prefer to be contacted, e.g. email, phone>", | |||
}, | |||
"part_type": "<part type of the desired item>", | |||
"make": "<make or manufacturer of the desired item>", | |||
"model": "<model of the desired item>", | |||
"year": "<optional year for the desired item>", | |||
"vehicle": { | |||
"make": "<optional vehicle make>", | |||
"model": "<optional vehicle model>", | |||
"vin": "<optional VIN of the vehicle>", | |||
"transmission": "<optional details regarding the vehicle's transmission>", | |||
"engine": "<optional details regarding the vehicle's engine>", | |||
"differential": "<optional details regarding the vehicle's differential>" | |||
}, | |||
"comments": "<additional comments, details, or questions from the user>" | |||
} | |||
Line 364: | Line 441: | ||
To log an end user's phone call for analytics purposes. | To log an end user's phone call for analytics purposes. | ||
<nowiki>https://api.heavytruckparts.net/enduser/log/phone_call</nowiki> | <nowiki>https://api.heavytruckparts.net/enduser/log/phone_call</nowiki> | ||
{ | |||
'contact': { | |||
"contact": "<name of user to contact with item details>", | |||
"company": "<name of the user's company>", | |||
"address": "<user's street address>", | |||
"city": "<user's city>", | |||
"state": "<user's state/province>", | |||
"postal_code": "<user's zip or postal code>", | |||
"country" : "<user's country>", | |||
"phone_number": "<user's phone number>", | |||
"email": "<user's email address>", | |||
"preferred_contact_method": "<the way the user would prefer to be contacted, e.g. email, phone>", | |||
}, | |||
"vendor_id": "<vendor id of the vendor being called>", | |||
"vendor_store_id": "<vendor store id of vendor being called>", | |||
"vendor_inventory_id": "<optional, vendor inventory id of item end user is calling regarding>", | |||
"part_type": "<optional, inventory part type of item end user is calling regarding>", | |||
"year": "<optional, year of item end user is calling regarding>", | |||
"make": "<optional, make or manufacturer of item that the end user is calling regarding>", | |||
"model": "<optional, model of item end user is calling regarding>", | |||
"category": "<optional, category of item end user is calling regarding>", | |||
"price": "<optional, price of item end user is calling regarding>" | |||
} | |||
==== Email Message ==== | ==== Email Message ==== | ||
To log an email send by an end user for analytics purposes. | To log an email send by an end user for analytics purposes. | ||
<nowiki>https://api.heavytruckparts.net/enduser/log/email</nowiki> | <nowiki>https://api.heavytruckparts.net/enduser/log/email</nowiki> | ||
{ | |||
'contact': { | |||
"contact": "<name of user sending the email>", | |||
"company": "<name of the user's company>", | |||
"address": "<user's street address>", | |||
"city": "<user's city>", | |||
"state": "<user's state/province>", | |||
"postal_code": "<user's zip or postal code>", | |||
"country" : "<user's country>", | |||
"phone_number": "<user's phone number>", | |||
"email": "<user's email address>", | |||
"preferred_contact_method": "<the way the user would prefer to be contacted, e.g. email, phone>", | |||
}, | |||
"vendor_id": "<vendor id of the vendor to be emailed>", | |||
"vendor_store_id": "<vendor store id of the vendor to be emailed>", | |||
"message": "<additional comments or questions from the user>" | |||
} | |||
==Sales Documents== | ==Sales Documents== | ||
Line 381: | Line 498: | ||
sale_total: 'decimal total value of sale; recommended but technically optional', | sale_total: 'decimal total value of sale; recommended but technically optional', | ||
user_id: 'end user or customer id value; optional', | user_id: 'end user or customer id value; optional', | ||
non_itrack_user: <true/false; is user_id from a website login system or a customer id from ITrack; optional, defaults to "false", that user_id is an ITrack customer_id> | |||
shipping_method: 'shipping preference: "Pick-Up"/"Will Call", "Fastest"/"Expedited", "Cheapest"/"Standard"; optional, if not present it assumes "standard" shipping', | shipping_method: 'shipping preference: "Pick-Up"/"Will Call", "Fastest"/"Expedited", "Cheapest"/"Standard"; optional, if not present it assumes "standard" shipping', | ||
comments: 'additional comments, special delivery instructions, notes, user-provided information, etc...', | comments: 'additional comments, special delivery instructions, notes, user-provided information, etc...', | ||
po_number: 'purchase order number; up to 20 characters; optional' | po_number: 'purchase order number; up to 20 characters; optional', | ||
approval_status: 'the vendor's approval status for the transaction: "approved", "rejected", "expired", "pending"; optional, if not present it assumes "pending", | |||
line_items: [ | line_items: [ | ||
{ | { | ||
Line 392: | Line 511: | ||
price: <decimal value price charged for the line item; this is just the price of the item and does not include shipping or tax>, | price: <decimal value price charged for the line item; this is just the price of the item and does not include shipping or tax>, | ||
core_price: <decimal value core price for the line item; optional>, | core_price: <decimal value core price for the line item; optional>, | ||
shipping_price: <decimal value of individual shipping cost for the item; optional>, | shipping_price: <decimal value of individual shipping cost for the item; optional/unused (reserved for future development)>, | ||
tax_price: <decimal value of individual tax cost for the item; optional> | tax_price: <decimal value of individual tax cost for the item; optional> | ||
}, [...] | }, [...] | ||
Line 420: | Line 539: | ||
} | } | ||
} | } | ||
Individual line items support a "shipping_price" parameter, but at this time, that value is unused and is merely reserved for future development. You may enter a value, and it will be stored remotely with the sale, but it is currently not imported into the ITrack system or used for any purpose. | |||
The creation process will return a JSON response: | The creation process will return a JSON response: | ||
Line 460: | Line 581: | ||
===Looking Up Sales Documents=== | ===Looking Up Sales Documents=== | ||
You may need to reference ITrack Sales Documents after their creation (to show end users their sales history, for instance). The online_transaction_id provided by the API in the /sale/create process can be used to look up the Sales Document or determine the ITrack-generated sales document id. | You may need to reference ITrack Sales Documents after their creation (to show end users their sales history, for instance). The online_transaction_id provided by the API in the /sale/create process or via /sale/list can be used to look up the Sales Document or determine the ITrack-generated sales document id. | ||
<nowiki>https://api.heavytruckparts.net/sale/lookup?vendor_id=<vendor id>&online_transaction_id=<online_transaction_id from /sale/create></nowiki> | <nowiki>https://api.heavytruckparts.net/sale/lookup?vendor_id=<vendor id>&online_transaction_id=<online_transaction_id from /sale/create></nowiki> | ||
Line 612: | Line 733: | ||
]} | ]} | ||
} | } | ||
===Listing Sales Documents=== | |||
It can be helpful to see a listing of all available ITrack Sales Documents, particularly if, as is common, you aren't generating all of the transactions via the /sale/create process. | |||
<nowiki>https://api.heavytruckparts.net/sale/list</nowiki> | |||
You may choose to filter your list by particular vendors: | |||
<nowiki>https://api.heavytruckparts.net/sale/list?vendor_id=<vendor id></nowiki> | |||
A HEAD request returns a count and list of ids necessary to identify sales documents in the system, i.e. just the vendor_id, vendor_store_id, online_transaction_id, and vendor_salesdocument_id. | |||
<nowiki>HEAD:https://api.heavytruckparts.net/sale/list</nowiki> | |||
{ | |||
"total_results": <total count of available sales documents>, | |||
"results": [{ | |||
"vendor_id": <vendor id of the sales document vendor>, | |||
"vendor_store": <vendor's store id where the sales document exists>, | |||
"vendor_salesdocument_id": <vendor's sales document id>, | |||
"online_transaction_id": <numeric id of the transaction as recorded as an online event>, | |||
"date_created": <YYYY-MM-DD HH:MM:SS style timestamp of when the sales document was created>, | |||
"date_closed": <YYYY-MM-DD HH:MM:SS style timestamp of when the sales document was closed; if closing date isn't available, the time of payment is used; if neither closing nor payment is available, this will be null>, | |||
"itrack_customer_id": <the vendor's ITrack customer id for the customer associated with this sales document, if available. 0 if no customer_id is available>, | |||
"vendor_approval_status": <One of "Pending", "Approved", "Expired" or "Rejected" indicating the vendor's approval response status for this sales document>, | |||
"customer_approval_status": <One of "Pending", "Approved", "Expired" or "Rejected" indicating the vendor's approval response status for this sales document> | |||
} | |||
A GET request returns additional data on each sales document, including the date of creation and (if valid) close; the associated itrack_customer_id, if any; and the approval status values for the sales document. | |||
<nowiki>GET:https://api.heavytruckparts.net/sale/list</nowiki> | |||
{ | |||
"total_results": <total count of available sales documents>, | |||
"results": [{ | |||
"vendor_id": <vendor id of the sales document vendor>, | |||
"vendor_store": <vendor's store id where the sales document exists>, | |||
"vendor_salesdocument_id": <vendor's sales document id>, | |||
"online_transaction_id": <numeric id of the transaction as recorded as an online event> | |||
}] | |||
} | |||
This list may be optionally filtered by userid/user_id, vendor_id, date_range (a comma separated start and end date), vendor_status, or customer_status: | |||
<nowiki>GET:https://api.heavytruckparts.net/sale/list?userid=<userid/ITrack customerid>&vendor_id=<vendor id>&date_range=<start date>,<end date>&vendor_status=<vendor approval status>&customer_status=<customer approval status></nowiki> | |||
===Sales Document Approval Status=== | |||
HeavyTruckParts.Net online sales transactions now include a set of Document Approval fields to track the communication between the vendor and customer regarding a Sales Document. Many transactions cannot be easily shipped via parcel carriers or requires additional fitment kits that might not be clear to the customer. The Document Approval fields track visibility and acceptance by both the vendor and customer for a particular sale. ITrack (version 37+) and HeavyTruckParts.Net will automatically manage these fields if the transaction originates from HeavyTruckParts.Net, but if the transaction originates from a different site or service, or if the transaction is being loaded into an ERP system other than ITrack, it may be necessary to manage these approval fields directly via API calls. | |||
The four states of an approval status are | |||
* '''Pending''': The transaction has been created and is waiting for a response - if it is Pending for both vendor and customer, it is waiting on the vendor to approve the document before it goes back to the user for final acceptance. | |||
* '''Accepted''': The transaction, in its current state, has been accepted by the party. If it is Accepted by the Vendor and Pending for the customer, the Sales Document is waiting on final approval and payment by the customer of the completed document. | |||
* '''Expired''': The transaction has expired waiting on approval by one or the other party; the party the status is Expired on did not indicate their approval in time before the document was considered invalid. | |||
* '''Rejected''': The transaction was rejected by the party because they do not like the terms of the transaction. Examples would be of the customer Rejecting the transaction after the vendor adds freight charges or the vendor Rejecting the transaction after contacting the customer because the customer's selected items do not actually meet their needs. | |||
<nowiki>https://api.heavytruckparts.net/sale/approve</nowiki> | |||
A PUT or POST request is used to update the approval status and will respond with the new approval status. A GET or HEAD request will return the current approval status of the sales document. The sales document can be specified either by vendor_id and online_transaction_id or by vendor_id, vendor_store, and vendor_salesdocument_id. | |||
PUT and POST requests should include a JSON object with the desired approval status of the sales document. If you do not wish to modify one of the approval status fields, it may be omitted, only the field(s) provided in the request will be updated. | |||
<nowiki>POST:https://api.heavytruckparts.net/sale/approve?vendor_id=<vendor id>&online_transaction_id=<online transaction id></nowiki> | |||
<nowiki>POST:https://api.heavytruckparts.net/sale/approve?vendor_id=<vendor id>&vendor_store=<vendor store id where the sales document exists>&vendor_salesdocument_id=<vendor's sales document id></nowiki> | |||
{ | |||
vendor_approval: <optionally, one of "Pending", "Approved", "Expired", or "Rejected">, | |||
customer_approval: <optionally, one of "Pending", "Approved", "Expired", or "Rejected"> | |||
} | |||
The response from the API following any GET, HEAD, PUT, or POST request will be the current approval status of the sales document | |||
{ | |||
vendor_approval_status: <one of "Pending", "Approved", "Expired" or "Rejected">, | |||
customer_approval_status: <one of "Pending", "Approved", "Expired" or "Rejected">, | |||
transaction_status: <a summary value of the approval status: "submittedToVendor", "pendingUserApproval", "pendingUserPayment", "expiredOnVendor", "expiredOnUser", "cancelledByVendor", "cancelledByUser", or "Pending"> | |||
} | |||
Please note that the sales document integration is under active development and may see additional changes in the near future. | Please note that the sales document integration is under active development and may see additional changes in the near future. | ||
== Advertising Partner Feeds == | == Advertising Partner Feeds == | ||
To better serve our advertising partners, the GET /inventory/feed endpoint is available. This request provides a simplified listing of all inventory available to your apiuser in a single JSON object. Please note that collating inventory can take some time, so if you use this request, please set your request timeout to a large value. 120 seconds should be sufficient for most advertising partners. There are several differences between this request and a search for all results, most notably, the description is truncated with an ellipsis, and only the "top ranked" image URL is provided. | To better serve our advertising partners, the GET /inventory/feed endpoint is available. This request provides a simplified listing of all inventory available to your apiuser in a single JSON object. Please note that collating inventory can take some time, so if you use this request, please set your request timeout to a large value. 120 seconds should be sufficient for most advertising partners, but some may need as many as 600 seconds. There are several differences between this request and a search for all results, most notably, an item hash value is included, the description is truncated with an ellipsis, and only the "top ranked" image URL is provided. The intended use of this endpoint is to provide a very fast list of all inventory items available to the advertising partner, and then further requests for complete item details would be made either on-demand or cached based on the item_hash value. | ||
<nowiki>GET https://api.heavytruckparts.net/inventory/feed</nowiki> | <nowiki>GET https://api.heavytruckparts.net/inventory/feed</nowiki> | ||
{"total_results": "the total number of results for this search", | {"total_results": "the total number of results for this search", | ||
"results": | "results": | ||
[" | ["type:"(USED,NEW,REMANUFACTURED, etc...)", | ||
"vendor":{ | "vendor":{ | ||
"company":"company name", | "company":"company name", | ||
Line 644: | Line 833: | ||
"condition":"the item's condition, as described by the vendor", | "condition":"the item's condition, as described by the vendor", | ||
"details_uri":"a URL to request for further information on this item", | "details_uri":"a URL to request for further information on this item", | ||
"images":"a URL for the image marked as the | "images":"a URL for the image marked as the 'top ranked' by the vendor", | ||
"item_hash": "a SHA256 hash of this item's current state" ]] | |||
} | } | ||
Latest revision as of 10:37, 19 August 2024
API access can be provided to the HeavyTruckParts.Net data store. The API can be a convenient way to provide access to search results or to a customer's inventory on HTP.Net.
RESTful Service
The API is a RESTful service. That means that requests to it work just like making a request to a website. You use a URL, with a possible query string to add filters to the behavior, with an HTTP method (usually GET) and the results are returned to you. Another thing to keep in mind that, as a pure RESTful service, there is NO STATE in the API. It does not have sessions, and doesn't remember anything about a request. That means that a user MUST provide authentication details with EVERY request made.
Authentication and Security
The API authenticates with a user and password (which will be pre-agreed on between ISoft and any client who wants API access) via HTTP Basic authentication. Basic authentication is not, in and of itself, secure. So to combine the ease of Basic authentication with additional security, the API requires access over HTTPS. Industry standard SSL-encryption protects every API request, so Basic authentication can be safely used.
Customized For Each API User
The API results are customized on the basis of the API user that authenticates with the API. So simply by presenting the correct user, the API will automatically determine which dataset to provide (automotive, motorcycle, yellow iron, or heavy truck). It also determines the customization for the user. The API user provides their own part types, manufacturer, and model information in a search. This information is used by the API to map to the values used by HeavyTruckParts.Net. Additionally, search results are customized by the API user, so an API user can have access to a predetermined set of vendors' inventory, with customizable default filters. An API user can be defined to prefer data in XML or JSON format; by default the API provides JSON-formatted data back to the API user.
You will be provided an API domain name based on your product specification within the ITrack family.
- https://api.heavytruckparts.net/ For Heavy Truck applications, including ITrack Pro HT, ITrack Chromium Heavy Truck, and ITrack Enterprise
- https://api.yellowironparts.net/ For Yellow Iron applications, including ITrack Pro YellowIron
- https://api.recyclers.net/ For Automotive applications, including ITrack Pro Auto
- https://api.cyclerecyclers.net/ For Motorcycle applications, including ITrack Pro MC
For the purposes of this documentation, we will use https://api.heavytruckparts.net as the API domain, but you should substitute the appropriate domain for your API user when making your own requests.
Customized For End Users
The API can accept an id for the end user -- that is, the person visiting the website of the API User or using the webapp built by the API user. Customizations-per-end-user that can be applied include custom pricing (if the id can be matched to the appropriate customerid in a vendor system), default distance sorting (if the id can be matched to a particular zip code), or special availability rules.
Making a Request
So how is a request made? Assuming that you have a valid API User and know how to make the request, providing that user and password via Basic authentication, API requests are just HTTP GET requests:
https://api.heavytruckparts.net/inventory/search/<part type>/<make or manufacturer>/<model>?<filter options>
The request should be URI encoded:
https://api.heavytruckparts.net/inventory/search/Engine%20Assembly/CUMMINS/ISX?year_range=2013,2015&zipcode=68503&distance=100
The requirement for URI encoding includes all elements, including the make or manufacturer and model. If you don't URI encode these elements, unencoded spaces, slashes, or other characters will cause incorrect, invalid, or empty results.
- Part Type: The part type is specified on the URL as the first part. This may be a string or numeric value; it will be mapped to the appropriate value for HTP.Net based on your API user. This is a many-to-many mapping: You may have a part type that maps to many HTP.Net part types, or many part types that map to a single HTP.Net part type.
- Make or Manufacturer: The vehicle make or part manufacturer for the part search, specified on the URL as the second part. This is a many-to-many mapping: You may have a manufacturer that maps to many HTP.Net manufacturers or many manufacturers that map to a single HTP.Net manufacturer.
- Model: The vehicle or part model for the part search, specified on the URL as the third part. This is many-to-many mapping: You may have a model that maps to many HTP.Net models or many models that map to a single HTP.Net model.
- Filter Options: An optional query string of <filter>=<value> options, separated by & symbols to add as many filter options as desired.
- year_range: a comma separated value of "first_year,last_year" inclusive. A 0 means "all years." "year_range=0,2003" is "all years up to and including 2003.
- zipcode: the zipcode to distance search from. By default, if a zipcode is provided, results will be sorted by distance.
- distance: a distance in miles to limit results to. Requires zipcode to be specified, 0 means "any distance."
- keywords: a space-separated list of keywords to perform a keyword search with. The keyword search looks for ALL keywords, but can be structured via pipe (|) operators for OR behavior. For example, keywords=(first set of search terms)|(second set of search terms)
- category: an item category to limit the results by. This is usually something like "NEW", "USED", or "CORE", but a full availability list for Categories can be requested (see Availability Lists below)
- By specifying the category option as an array, more than one category can be selected. E.g. category[]=NEW&category[]=USED
- store: a comma-separated list of store id values to restrict the results to. An empty list provides the default filter of "all stores." Use of this parameter requires knowing the store id value, assigned in ITrack, of the store or stores search results should be filtered to.
- userid: the end-user id, representing a person using the website or webapp which relies on the API. Pricing and other values in the results can be customized based on this value.
- page_number: the results are separated into separate "pages" results. This value indicates which "page" in the results should be returned.
- result_size: the number of results to be returned "per page." This value can be an integer count of results (the default is 25) or the word "all." Please note that specifying "all" or a large number can result in very poor search performance. Additionally, depending on the user configuration, the search may have specific requirements before this parameter takes effect: For non-vendor specific searches and/or large values of result_size, the API may require a part type, make, model, and enduserid to be specified. "Body" or "Vehicle" parts may require a year or year range to specified. If these values are not specified in the search, the API may ignore the result_size parameter and present the default 25 result page size. Please contact ISoft Data Systems if you have questions regarding result_size support and strict search requirements for page sizing for your specific API user requests.
- sort_column: the column in the results that the results should be sorted by. The default is "price," unless a zip code is specified, and then the default is "distance." Allowable values are "part_name", "make_model", "year", "oem_number", "vendor_sku", "description", "price", "coreprice", "condition", "type", "distance", "vendor", "date_added", and "date_updated".
- sort_order: the "direction" the sort_column should be sorted on. The default is "ascending". Allowable values are "ascending" and "descending" (or the abbreviations "asc" and "desc").
- show_suggested: an optional parameter which can be set to "1" or "true" to show suggested part types for a search. This only produces results for searches which do not have a part type set. This requests the API include links to more specific searches in the current search to "drill down" the search results. This may be turned on for an apiuser to affect all of their valid searches (without needing to be specified in the query string for the searches).
- require_images: an optional parameter which can be set to "1" or "true" to limit the search results to only items which have images associated with them.
- vendor: a comma-separated list of vendor id values to restrict the results to. An empty list provides the default filter of "all vendors configured for my API user." Use of this parameter requires knowing the vendor id values assigned by ISoft. These can also be found in the search results' vendor objects under "vendor_id".
- filter: an optional parameter which can be used to apply one or more Q&A filters to the results. These filter options are separated by semicolons, the option is separated from allowed values by a colon, and allowed values are separated by commas. E.g. "filter=optionA:valueA;optionB:valueB1,valueB2" Please note that these are case-insensitive but otherwise require exact matches. The filter option string should be URL encoded, and, due to framework limitations, filter options are not permitted to have question marks in them.
The exact search format can be customized for individual API users. In general, the search parts are "optional" but require a place holder (though in most cases, if some search parts are not used, a keyword search filter is encouraged to help narrow down search results). Due to the nature of URLs, something must be entered for each search component to form a valid URL. In a standard search URI, providing the "magic" character asterisk (*) for a search component will cause that search component to be ignored for the purposes of the search. For example,
https://api.heavytruckparts.net/inventory/search/*/FULLER/*?keywords=warranty
To perform a keyword-only search, you can leave the part type, manufacturer, and model as all "wildcards" and just specify a keyword filter:
https://api.heavytruckparts.net/inventory/search/*/*/*?keywords=warranty
Results
Results are provided, by default, in JSON format, though XML results could be provided instead. Results are "paginated" or broken into "pages", just like a Google search. 25 results are provided to a page by default; if no specific result "page" size is requested.
{results: total_results: the total number of results for this search, total_pages: the total number of search result "pages" in this search, [type:"(USED,NEW,REMANUFACTURED, etc...)", vendor:{ company:"company name", contact:"contact person", city:"city the vendor is in", state:"state the vendor is in", postal_code:"zip code or postal code for the vendor", phone_number:"the vendor's phone number", fax_number:"the vendor's fax number", email:"the vendor's email address", vendor_id: "the vendor's numeric id", vendor_store: "the vendor's numeric store id" }, part_name:"the part type name", make_model:"the make or manufacturer and model of the item", year:"the year of the item, if provided", oem_number:"any OEM number associated with the item", vendor_sku:"the SKU or Tag Number assigned to this item by the vendor", vendor_inventory_id: "the unique numeric id for this item in the vendor's ITrack system", description:"the description of the item", price:"the retail price of the item, or a custom price for the end user, if available", coreprice:"the core return price on the item, if any", condition:"the item's condition, as described by the vendor", status: "the item's current status, e.g. 'Available', 'On Hold', or 'Sold'", date_entered: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was entered by the vendor", date_last_modified: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was last modified by the vendor", details_uri:"a URL to request for further information on this item", images:["an array of URLs for images associated with this item"], distance:"the distance of the item, in miles, from a provided zipcode", page_number:"the page number this item is found on"] }
If show_suggested is set, the results include an additional suggested_part_types object:
{results: total_results: the total number of results for this search, total_pages: the total number of search result "pages" in this search, [type:"(USED,NEW,REMANUFACTURED, etc...)", vendor:{ company:"company name", contact:"contact person", city:"city the vendor is in", state:"state the vendor is in", postal_code:"zip code or postal code for the vendor", phone_number:"the vendor's phone number", fax_number:"the vendor's fax number", email:"the vendor's email address", vendor_id: "the vendor's numeric id", vendor_store: "the vendor's numeric store id" }, part_name:"the part type name", make_model:"the make or manufacturer and model of the item", year:"the year of the item, if provided", oem_number:"any OEM number associated with the item", vendor_sku:"the SKU or Tag Number assigned to this item by the vendor", vendor_inventory_id: "the unique numeric id for this item in the vendor's ITrack system", description:"the description of the item", price:"the retail price of the item, or a custom price for the end user, if available", coreprice:"the core return price on the item, if any", condition:"the item's condition, as described by the vendor", status: "the item's current status, e.g. 'Available', 'On Hold', or 'Sold'", date_entered: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was entered by the vendor", date_last_modified: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was last modified by the vendor", details_uri:"a URL to request for further information on this item", images:["an array of URLs for images associated with this item"], distance:"the distance of the item, in miles, from a provided zipcode", page_number:"the page number this item is found on"], suggested_part_types: [ { part_name: "the part type name", part_type_id: "the part type id value for this part type", uri: "the full URI for a search based on this part type but otherwise identical to the current search" } ] }
Your API user can be configured to include inventory Q&A options directly in the search results. If you want Q&A to be included in your search results, please contact ISoft Data Systems and ask to have user option 'include_qa_in_search_results' set. When Q&A are included in searches, Videos associated with the item, if any, will also be included in the results. If that option is enabled for your user, then the results will include a "qa" object with the "Q&A" fields for each item: {results:
total_results: the total number of results for this search, total_pages: the total number of search result "pages" in this search, [type:"(USED,NEW,REMANUFACTURED, etc...)", vendor:{ company:"company name", contact:"contact person", city:"city the vendor is in", state:"state the vendor is in", postal_code:"zip code or postal code for the vendor", phone_number:"the vendor's phone number", fax_number:"the vendor's fax number", email:"the vendor's email address", vendor_id: "the vendor's numeric id", vendor_store: "the vendor's numeric store id" }, part_name:"the part type name", make_model:"the make or manufacturer and model of the item", year:"the year of the item, if provided", oem_number:"any OEM number associated with the item", vendor_sku:"the SKU or Tag Number assigned to this item by the vendor", vendor_inventory_id: "the unique numeric id for this item in the vendor's ITrack system", description:"the description of the item", price:"the retail price of the item, or a custom price for the end user, if available", coreprice:"the core return price on the item, if any", condition:"the item's condition, as described by the vendor", status: "the item's current status, e.g. 'Available', 'On Hold', or 'Sold'", date_entered: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was entered by the vendor", date_last_modified: "the date and time, in YYYY-MM-DD hh:ii:ss format, that the item was last modified by the vendor", details_uri:"a URL to request for further information on this item", images:["an array of URLs for images associated with this item"], distance:"the distance of the item, in miles, from a provided zipcode", page_number:"the page number this item is found on"], qa: { "Q&A Key": "Q&A Value", ... }, video: "video URL or Youtube video id, if available; if none is available, this parameter will not appear" }
The vendor_sku value is the "Tag Number" of the item in ITrack, and is most useful as a display value for users. The vendor_sku is generally how a vendor recognizes the inventory item, but it not guaranteed to be unique in the vendor's sytem. The vendor_inventory_id is the back-end identifier for the item in the vendor's ITrack system, and is guaranteed to be unique for the item, but since it is a back-end identifier, it's not generally as useful to be displayed to website visitors as the vendor_sku. Notice that the details uri is based on vendor_id, vendor_store, and vendor_inventory_id. These three numeric identifiers are used to uniquely identify the item.
Please note that the image URIs provided are for "full-size" images. If you are planning to display thumbnailed versions of the images, you can request a thumbnail directly by adding "w" (for width) and/or "h" (for height) request parameters to the image URI. These are treated as maximum values for the image, and the original aspect ratio will be maintained, so it is safe to provide both without worrying about distorting the image.
The date_entered and date_last_modified fields are currently provided without timezone information. The time zone of the date-time value is assumed to be the local time zone of the vendor. As that information is not yet easily available from ITrack, it is not yet provided here. We apologize for any inconvenience.
Other Requests
The API handles more than just searches. You can request details on particular inventory items or fetch the available part types, manufacturers, or models for your API user.
Item Details
An item details request provides more information on a particular item than the basic search result provides.
https://api.heavytruckparts.net/inventory/details/<vendor code>/<vendor store>/<inventory item id>?[userid=<end-user id>
The information is provided in JSON form, just like the search results, and includes all of the important data from the search results entry as well as further information on that specific inventory item. In the QA sub-object are "Q&A" options which are vendor specified label: value pairs. The exact data in these fields and how many there are cannot be predicted, as they are specified by the item vendor. If you are receiving the legacy details response, which included Q&A options directly in the object and you want to update to the new details response, please contact ISoft Data Systems. The optional userid request option is used for determining custom pricing and availability when applicable.
{part_name: 'part type name', vendor_part_name: 'vendor-specific short part type description', year: 'year of item manufacture or production, if available', vehicle_make: 'make of vehicle for item, if available', vehicle_model: 'model of vehicle for item, if available', part_manufacturer: 'manufacturer of item, if available', part_model: 'part model of item, if available', oem_number: 'OEM number assigned to item', serial_number: 'Serial number assigned to item, if available', vendor_sku: 'Vendor SKU or Tag Number', vendor_inventory_id: 'Vendor's unique numeric ID for the item', vendor_vehicle_id: 'Vendor's ID for the Vehicle or Whole Unit for the item, if available', vehicle_tracking_number: 'Tracking number of an associated vehicle, if available; will not be returned if unavailable', vehicle_mileage: 'Mileage of an associated vehicle, if available; will not be returned if unavailable', location: 'primary location of the inventory item, if available; will not be returned if unavailable', vin: 'VIN, if available', core_price: 'core return price', price: 'item price', description: 'item description with all HTML tags stripped', html_description: 'item description with HTML tags intact', condition: 'vendor specified item condition', category: 'item category, i.e. USED, NEW, REMANUFACTURED', status: 'the status of the item, i.e. AVAILABLE, ON HOLD, SOLD; only returned if activated for your apiuser', available_quantity: 'available quantity of item', side: 'side of vehicle item fits, if available and appropriate', qa: { 'vendor_specified_option_label, for instance "HP" or "Color"': 'vendor_specified_option_value', ... }, location: "the location of the item at the vendor's facility", date_created: 'the date and time the item was entered by the vendor, in YYYY-MM-DD hh:ii:ss format', date_last_modified: 'the date and time the item was last modified by the vendor, in YYYY-MM-DD hh:ii:ss format', video: 'video url or YouTube video id, if available; will not be returned if unavailable', vendor:{ company:"company name", contact:"contact person", city:"city the vendor is in", state:"state the vendor is in", postal_code:"zip code or postal code for the vendor", phone_number:"the vendor's phone number", fax_number:"the vendor's fax number", email:"the vendor's email address", vendor_id: "the vendor's numeric id", vendor_store: "the vendor's numeric store id" }, images:["an array of URLs for images associated with this item"] }
Shipping Dimensions
Shipping dimensions and item weight are provided as Q&A elements when they are available. If they are not present or set for the item, they will not be included in the "qa" sub-object. If the item does have shipping dimensions set in ITrack, they are available in the qa sub-object as
{ ... shipping_length: "the length of the item as it would be shipped, as 'x in.'", shipping_width: "the width of the item as it would be shipped, as 'y in.'", shipping_height: "the height of the item as it would be shipped, as 'z in.'", weight: "the weight of the item as it would be shipped, as 'm lbs'", ... }
Item Videos
Videos of an item are entered by ITrack users as Q&A elements under the name "Video". This is usually a full URL to a video, in either "http(s)://www.youtube.com/watch?" or "http(s)://youtu.be/" formats.
If a video is present, details->video will be present and not empty, and its value will contain the URL to the video.
{ ... 'video': 'https://youtu.be/XXXXXXX' ... } }
Available Lists
Requests can be made to the API to fetch the complete list of part types, make/manufacturers, models, categories, and vendors for your API user. These results are customized to match your API user's mapping data (so the results can be used directly to produce search request URIs) and by default are limited to include just those part types, makes, manufacturers, models, and part categories that pertain to the result set returned to your API user in searches (the lists will not include part types that you wouldn't find in your search, for instance). The available vendor list will always provide all of the available vendors for your API User. The query string filter for part types is optional for makes (and part manufacturers, the API uses "make" for both vehicle makes and part manufacturers), models, and categories, and the filter for makes when getting available models is also optional. That said, it is strongly encouraged to specify a part type for category availability if vehicles or whole units may be included in all your possible search results, because the category field has a different contextual meaning between a whole unit and a component part.
You may optionally pass the query string parameter of "all_results=true" if you want to include all of HeavyTruckParts.Net's possible choices, even if those options would not be found in your search results. You may optionally pass the query string parameter of "ignore_mapping=true" if you want to have the API ignore your possible mappings and return HTP's native results, rather providing you with the mapped value that matches your data. Part type, make, and model lists support an optional "userid" parameter, which will use your end user availability for that user, if it is specified.
https://api.heavytruckparts.net/inventory/available/part_types https://api.heavytruckparts.net/inventory/available/makes?part_type=<part type to filter make results by> https://api.heavytruckparts.net/inventory/available/models?part_type=<part type to filter models by>&make=<make to filter models by> https://api.heavytruckparts.net/inventory/available/categories?part_type<part type to filter categories by> https://api.heavytruckparts.net/inventory/available/vendors
The results are, as before, specified in JSON format.
[ {part_types_id: 'part type id value', part_type_name: 'part type name'} ]
[ {make: 'make or manufacturer name'} ]
[ {model: 'model name'} ]
[ {category: 'category name'} ]
[ {vendor: {company: 'Vendor company name', address: 'street address for this vendor location', state: 'state or province for this vendor location', postal_code: 'zip code or postal code for this vendor location', country: 'country for this vendor location', phone_number: 'phone number for this vendor location', email: 'email address for this vendor location', vendor_id: numeric vendor id value, unique for the vendor on HeavyTruckParts.Net (if the vendor has more than one store, you may see this more than once), vendor_store_id: numeric vendor store id value for this vendor store location } } ]
Parts From the Same Vehicle
After requesting details on a particular item, it may be useful to find what other items are available which were taken off of the same whole unit or vehicle. This can be done by placing a "wholeunitparts" request with the appropriate vehicle id:
https://api.heavytruckparts.net/inventory/wholeunitparts/<vendor code>/<vendor store>/<vendor vehicle id>?[userid=<end-user id>
The results are in JSON format, and are a relatively simple listing of all the items which are marked as coming from that same whole unit, along with detail URIs for those items. [
{ part_name: 'part type name', vendor_part_name: 'vendor-specific short part type description', make_model: 'the make or manufacturer and model of the item', vendor_sku: 'Vendor SKU or Tag Number', details_uri: 'a URL to request for further information on this item', price: 'the retail price of the item, or a custom price for the end user, if available' }
]
End-User Templates
End user custom results processing (availability, quantity, and pricing) are defined by templates, created in partnership between the API user and ISoft Data Systems. These templates are given names for ease of reference. A GET request to enduser/templates will provide the template list (a template type may optionally be provided to limit the templates received, otherwise all template types will be returned). A PUT or POST request can be used to assign a template to an enduser by their enduserid. A HEAD request will provide all the available template types. A DELETE request will remove the associations between an end-user and a template, effectively reverting that user to the default behavior for that template type.
HEAD https://api.heavytruckparts.net/enduser/templates : Provides the template type list. https://api.heavytruckparts.net/enduser/templates[/<optional template type] https://api.heavytruckparts.net/enduser/templates : Returns the list of all templates which can be assigned to an end user https://api.heavytruckparts.net/enduser/templates/pricing : Returns the list of all pricing templates which can be assigned to an end user.
The results are returned in JSON format, specifying the template name and the type of template:
[{template_name: "template name", template_type: "template type"}, ... ]
When assigning a template, you can use the pseudo-type "all" to use the same template name for all template types:
POST https://api.heavytruckparts.net/enduser/templates/<template type>?userid=<end user id>&template=<name of template to apply to end user> POST https://api.heavytruckparts.net/enduser/templates/all?userid=1&template=Dealer : Would assign the "Dealer" template for all template types to the end user 1
The "all" pseudo-type also works for removing template associations:
DELETE https://api.heavytruckparts.net/enduser/templates/<template type>?userid=<end user id> DELETE https://api.heavytruckparts.net/enduser/templates/all?userid=1
End-User Lookups
If you are trying to introspect customerids from an attached ITrack System, the API may be configured to return the id value for a given email address. The resulting value is suitable for use as the "userid" or enduser id value that you pass to the API for customer-specific pricing and availability.
https://api.heavytruckparts.net/enduser/lookup?email=<email address>
If you know the end user id, it can be passed in to look up information about that customer as well.
https://api.heavytruckparts.ent/enduser/lookup?userid=<end user id>
The results are in JSON format. The GET method will return most of the customer data, the HEAD method will return just the customer id.
{userid: "customer id / end user id", company: "the name of the customer's company", name: "the customer's name", street: "the customer's street address", city: "the customer's city", state: "the state or province for the customer", zip: "the zip or postal code for the customer", country: "the full country name for the customer", country_code: "the two-letter country code for the customer's country", email: "the customer's email address", phone: "the customer's phone number" }
If you need a list of all enduserids that the system has associated with a template, the API can be configured to provide that information.
https://api.heavytruckparts.net/enduser/listall
The results are in JSON format, and contain an array of objects listing the end user and their current template association.
[{userid: "customer id / end user id", company: "the customer's company name", name: "the customer's name", email: "the customer's email address", templatename: "the name of the template associated with this customer" }]
It may be possible for ISoft to configure the API to automatically generate template associations for you. In this case, you may request that the API refresh the template associations (which generates associations for new users and corrects the associations for existing users) when making a list request:
https://api.heavytruckparts.net/enduser/listall?refresh_list=true
Mapped Types
If you have a deep part type mapping (you primarily interact with the API using an abstraction which replaces HeavyTruckParts.Net part types and has its own mapping to those types maintained in ITrack -- this is the Part List Authority in ITrack, and is used to represent concepts like "Function Groups" -- you may want to know what HeavyTruckParts.Net may be included in any particular custom mapped part. This list can be requested via
https://api.heavytruckparts.net/inventory/mappingtypes/<mapped type>
The results are in JSON format, and contain an array of objects listing the HeavyTruckParts.Net "part type" numbers and the human-readable type name that correspond to the mapped type, or would be included in searches against the mapped type, if any exist.
[{ part_type: "HeavyTruckParts.Net part type id", part_name: "The name of the HeavyTruckParts.Net part type" }]
Mapped types may be represented a hierarchical fashion. These hierarchies can be filtered by category. Each call to the "functiongroup" request will return a particular level of a hierarchy, optionally filtered by category. By providing a "parent" as part of the query string, you can get deeper levels of the hierarchy.
https://api.heavytruckparts.net/inventory/functiongroup?[category=<filter category>][&][parent=<parent function group id>]
The results are in JSON format, and contain an array of objects representing the mapped types at this level in the hierarchy. This includes the function group id, and the function group name. By providing a function group id as the parent to a subsequent request, you can retrieve the mapped types that have that mapped type id as their "parent" type.
[{ function_group_id: "mapped type id", function_grup_name: "The name of the mapped type" }]
Parts Requests, Part Inquiries, and Logging Phone Calls and Emails
HeavyTruckParts.Net provides additional functionality to help support end user behaviors. This includes logging requests by end users for unlisted or unavailable items (parts requests), additional details on existing items (parts inquiries), and logging phone calls and contact emails from end users for inclusion in analytical and performance reports.
Parts requests, part information inquiries, and contact emails all generate the requisite emails for the vendors -- it is not necessary to send any email messages (even with "logged emails") outside of the API.
All of these are handled as variations of the enduser/log request. The request should be a PUT or POST request, with a JSON body, the contents of which is determined by the type of request.
Parts Request
To log an end user request for an item they could not find. The entire "vehicle" object is optional, containing details about the vehicle for fitment.
https://api.heavytruckparts.net/enduser/log/part_request { 'contact': { "contact": "<name of user to contact with item details>", "company": "<name of the user's company>", "address": "<user's street address>", "city": "<user's city>", "state": "<user's state/province>", "postal_code": "<user's zip or postal code>", "country" : "<user's country>", "phone_number": "<user's phone number>", "email": "<user's email address>", "preferred_contact_method": "<the way the user would prefer to be contacted, e.g. email, phone>", }, "part_type": "<part type of the desired item>", "make": "<make or manufacturer of the desired item>", "model": "<model of the desired item>", "year": "<optional year for the desired item>", "vehicle": { "make": "<optional vehicle make>", "model": "<optional vehicle model>", "vin": "<optional VIN of the vehicle>", "transmission": "<optional details regarding the vehicle's transmission>", "engine": "<optional details regarding the vehicle's engine>", "differential": "<optional details regarding the vehicle's differential>" }, "comments": "<additional comments, details, or questions from the user>" }
Part Inquiry
To log an end user request for additional details on a particular item
https://api.heavytruckparts.net/enduser/log/part_inquiry { 'contact': { "contact": "<name of user to contact with item details>", "company": "<name of the user's company>", "address": "<user's street address>", "city": "<user's city>", "state": "<user's state/province>", "postal_code": "<user's zip or postal code>", "country" : "<user's country>", "phone_number": "<user's phone number>", "email": "<user's email address>", "preferred_contact_method": "<the way the user would prefer to be contacted, e.g. email, phone>", }, "vendor_id": "<vendor id of the vendor for the item>", "vendor_store_id": "<vendor store id of the item>", "vendor_sku": "<vendor sku (tag number) of item we're requesting more information about>", "comments": "<additional comments or questions from the user>" }
Phone Call
To log an end user's phone call for analytics purposes.
https://api.heavytruckparts.net/enduser/log/phone_call { 'contact': { "contact": "<name of user to contact with item details>", "company": "<name of the user's company>", "address": "<user's street address>", "city": "<user's city>", "state": "<user's state/province>", "postal_code": "<user's zip or postal code>", "country" : "<user's country>", "phone_number": "<user's phone number>", "email": "<user's email address>", "preferred_contact_method": "<the way the user would prefer to be contacted, e.g. email, phone>", }, "vendor_id": "<vendor id of the vendor being called>", "vendor_store_id": "<vendor store id of vendor being called>", "vendor_inventory_id": "<optional, vendor inventory id of item end user is calling regarding>", "part_type": "<optional, inventory part type of item end user is calling regarding>", "year": "<optional, year of item end user is calling regarding>", "make": "<optional, make or manufacturer of item that the end user is calling regarding>", "model": "<optional, model of item end user is calling regarding>", "category": "<optional, category of item end user is calling regarding>", "price": "<optional, price of item end user is calling regarding>" }
Email Message
To log an email send by an end user for analytics purposes.
https://api.heavytruckparts.net/enduser/log/email { 'contact': { "contact": "<name of user sending the email>", "company": "<name of the user's company>", "address": "<user's street address>", "city": "<user's city>", "state": "<user's state/province>", "postal_code": "<user's zip or postal code>", "country" : "<user's country>", "phone_number": "<user's phone number>", "email": "<user's email address>", "preferred_contact_method": "<the way the user would prefer to be contacted, e.g. email, phone>", }, "vendor_id": "<vendor id of the vendor to be emailed>", "vendor_store_id": "<vendor store id of the vendor to be emailed>", "message": "<additional comments or questions from the user>" }
Sales Documents
Some vendors may permit some API users to generate and interact with sales documents in their ITrack system. In order to use the Sales Document integration, the vendor must have support for it, and must have authorized ISoft Data Systems to allow your API account to use the integration. Please contact ISoft Data Systems for additional details.
Creating Sales Documents
There are several stages to creating a sales document in ITrack, which is why ISoft and the vendor need to coordinate to configure the vendor's sales document integration. This documentation will presume that the sales document integration has been configured and is operating, as that process is outside the scope of this document.
To request the creation of a sales document, make a PUT or POST request to the "/sale/create" endpoint.
https://api.heavytruckparts.net/sale/create
This request should include a JSON object with the details of the sale creation. Note that this object can represent a shopping cart with multiple line items (even from multiple vendors). {
sale_date: 'date and time of sale; in YYYY-MM-DD HH:ii:[ss] (SQL-standard) format; optional, if not present, it assumes the sale happened "now"', sale_total: 'decimal total value of sale; recommended but technically optional', user_id: 'end user or customer id value; optional', non_itrack_user: <true/false; is user_id from a website login system or a customer id from ITrack; optional, defaults to "false", that user_id is an ITrack customer_id> shipping_method: 'shipping preference: "Pick-Up"/"Will Call", "Fastest"/"Expedited", "Cheapest"/"Standard"; optional, if not present it assumes "standard" shipping', comments: 'additional comments, special delivery instructions, notes, user-provided information, etc...', po_number: 'purchase order number; up to 20 characters; optional', approval_status: 'the vendor's approval status for the transaction: "approved", "rejected", "expired", "pending"; optional, if not present it assumes "pending", line_items: [ { vendor_id: <numeric vendor id; provided by item as vendor.vendor_id>, vendor_store: <store id for the store the inventory is sourced from; provided by item as vendor.vendor_store>, vendor_inventory_id: <unique numeric inventory id; provided by item as vendor_inventory_id>, quantity: <quantity of item to be sold; optional, assumed to be 1 if not present>, price: <decimal value price charged for the line item; this is just the price of the item and does not include shipping or tax>, core_price: <decimal value core price for the line item; optional>, shipping_price: <decimal value of individual shipping cost for the item; optional/unused (reserved for future development)>, tax_price: <decimal value of individual tax cost for the item; optional> }, [...] ], billing_address: { contact: <billing contact's name>, company: <billing contact's company name, optional>, email: <billing contact's email address>, street: <billing contact's street address>, city: <billing contact's city>, state: <billing contact's state or province>, postal_code: <billing contact's zip or postal code>, country: <billing contact's country>, phone_number: <billing contact's phone number>, fax_number: <billing contact's fax number; optional> }, shipping_address: { contact: <shipping contact's name>, company: <shipping contact's company, optional>, email: <shipping contact's email address>, street: <ship-to street address>, city: <ship-to city>, state: <ship-to state or province>, postal_code: <ship-to zip or postal code>, country: <ship-to country>, phone_number: <shipping contact's phone number> }
}
Individual line items support a "shipping_price" parameter, but at this time, that value is unused and is merely reserved for future development. You may enter a value, and it will be stored remotely with the sale, but it is currently not imported into the ITrack system or used for any purpose.
The creation process will return a JSON response:
{ online_transaction_id: <the numeric id of the pending transaction; will be used to look up the sales document information in the future>, created: <the timestamp for the creation of this pending transaction, in YYYY-MM-DD HH:ii:ss format>, errors: [ { "item": { "vendor_id": 'The numeric identifier of the vendor the item with an error belongs to', "vendor_store": 'The numeric identifier of the vendor's store the item with an error belongs to', "vendor_inventory_id": 'The numeric identifier of the item with an error' }, "error": { "code": 'An error code describing the problem. Please see the error code table below.', "message": 'A human-readable message describing the error' } },[...] ] }
The errors object is an array, listing any line items from the transaction that were unable to be added, along with an error code and a human-readable explanation of why the item could not be added. If there were no errors, this object is empty. The error code will be one from the following table:
Error Code | Error |
---|---|
ERR_FORBIDDEN_VENDOR | Your user has not been authorized to create sales documents for this vendor. This may mean that the vendor has not completed the set up for their Sales Document Integration. Contact ISoft Data Systems to see if your API user can be enabled to sell items for this vendor. |
ERR_NOT_UNIQUE | The item was identified in a deprecated manner, and more than one item was found to match. Make the request as per documentation, specifying vendor_id, vendor_store, and vendor_inventory_id. |
ERR_NOT_AVAILABLE | The item was marked as being no longer available. This may mean that the item was sold before the transaction could be created. |
ERR_NOT_FOUND | The item was identified in a deprecated manner, and no items could be found in the database to match, OR no vendor_inventory_id was specified. Make sure that the item's vendor_inventory_id is specified in the request and that it is correct for the item. |
Looking Up Sales Documents
You may need to reference ITrack Sales Documents after their creation (to show end users their sales history, for instance). The online_transaction_id provided by the API in the /sale/create process or via /sale/list can be used to look up the Sales Document or determine the ITrack-generated sales document id.
https://api.heavytruckparts.net/sale/lookup?vendor_id=<vendor id>&online_transaction_id=<online_transaction_id from /sale/create>
If you know the sales document's store and document id, you can also reference it that way:
https://api.heavytruckparts.net/sale/lookup?vendor_id=<vendor id>&vendor_store=<vendor store id sales document was created at>&vendor_salesdocument_id=<vendor's sales document id>
A HEAD request returns basic information on the sales document. A GET request also includes line items and adjustments.
HEAD:https://api.heavytruckparts.net/sale/lookup?vendor_id=<vendor id>&online_transaction_id=<online_transaction_id> { vendor_id: <vendor id>, vendor_store: <vendor store id that sales document belongs to>, vendor_salesdocument_id: <vendor's sales document id>, salesdocument_date: <date of sale, in YYYY-MM-DD format>, document_is_void: <true/false; has this sales document been marked as VOID>, document_is closed: <true/false; has this sales document been marked as "closed." Documents are closed when the products on the document have been shipped.>, date_created: <date that sales document was created, in YYYY-MM-DD format>, date_closed: <date that sales document was finalized and closed, in YYYY-MM-DD; can usually be treated as date shipped>, shipping_tracking_number: <any tracking number associated with product shipment>, truck_number: <if a specific truck has been associated with this shipment>, online_transaction_id: <the online transaction id associated with this sales document, generated by the /sale/create or online "Buy Now" process>, subtotal: <sales document's subtotal, in USD>, total_tax: <total tax applied to this sales document>, comments: <public comments for the sales document (this may not include comments created in /sales/create, which generates internal comments)>, adjustments: <this will always be empty for a HEAD request>, user_id: <the API user id for the customer this document was sold to, if available>, billing_address: { contact: <billing contact>, company: <billing company>, email: <billing email address>, street: <billing street address>, mailing: <billing mailing address, if different from street address>, city: <billing city>, state: <billing state or province>, postal_code: <billing postal or zip code>, country: <billing country>, phone_number: <billing phone number> }, shipping_address: { contact: <shipping contact>, company: <shipping company>, email: <shipping email address>, street: <shipping street address>, mailing: <shipping mailing address, if different from street address>, city: <shipping city>, state: <shipping state>, postal_code: <shipping postal or zip code>, country: <shipping country>, phone_number: <shipping phone number> } }
A GET request provides the same object, but will include adjustments, if available, and an additional line_items object:
GET:https://api.heavytruckparts.net/sale/lookup?vendor_id=<vendor id>&online_transaction_id=<online_transaction_id> { vendor_id: <vendor id>, vendor_store: <vendor store id that sales document belongs to>, vendor_salesdocument_id: <vendor's sales document id>, salesdocument_date: <date of sale, in YYYY-MM-DD format>, document_is_void: <true/false; has this sales document been marked as VOID>, document_is closed: <true/false; has this sales document been marked as "closed." Documents are closed when the products on the document have been shipped.>, date_created: <date that sales document was created, in YYYY-MM-DD format>, date_closed: <date that sales document was finalized and closed, in YYYY-MM-DD; can usually be treated as date shipped>, shipping_tracking_number: <any tracking number associated with product shipment>, purchase_order_number: <Purchase Order number associated with the sales order>, truck_number: <if a specific truck has been associated with this shipment>, online_transaction_id: <the online transaction id associated with this sales document, generated by the /sale/create or online "Buy Now" process>, subtotal: <sales document's subtotal, in USD>, total_tax: <total tax applied to this sales document>, comments: <public comments for the sales document (this may not include comments created in /sales/create, which generates internal comments)>, adjustments: {[ name: <adjustment name>, description: <adjustment description>, amount: <amount of adjustment, in USD>, is_taxable: <true/false; is this adjustment considered a taxable item>, is_subtotal_adjustment: <true/false; is this adjustment included in the subtotal (is it "above the line")> ]}, user_id: <the API user id for the customer this document was sold to, if available>, billing_address: { contact: <billing contact>, company: <billing company>, email: <billing email address>, street: <billing street address>, mailing: <billing mailing address, if different from street address>, city: <billing city>, state: <billing state or province>, postal_code: <billing postal or zip code>, country: <billing country>, phone_number: <billing phone number> }, shipping_address: { contact: <shipping contact>, company: <shipping company>, email: <shipping email address>, street: <shipping street address>, mailing: <shipping mailing address, if different from street address>, city: <shipping city>, state: <shipping state>, postal_code: <shipping postal or zip code>, country: <shipping country>, phone_number: <shipping phone number> }, line_items: {[ vendor_id: <vendor id of item vendor>, vendor_store: <vendor store id of the item; note that this may be different from the sales order document's vendor_store>, vendor_sku: <vendor sku or "Tag Number" of the item>, vendor_inventory_id: <vendor inventory id>, vendor_part_name: <part type name, as assigned by the vendor>, year: <item year>, vehicle_make: <make of vehicle associated with item, if available>, vehicle_model: <model of vehicle associated with the item, if available>, part_manufacturer: <item's manufacturer>, part_model: <item's model>, sales_document_lineitem_type: <type of line item as applied to sales document>, description: <line item's description>, vin: <VIN associated with the line item, if any>, price: <price of the line item>, returnable: <true/false; if the line item is considered returnable>, days_to return: <number of days allowed for item return>, adjustments: {[ name: <adjustment name>, description: <adjustment description>, amount: <amount of adjustment, in USD>, is_taxable: <true/false; is this adjustment considered a taxable item>, is_subtotal_adjustment: <true/false; is this adjustment included in the subtotal (is it "above the line")> ]}, child_line_items: {[ vendor_id: <vendor id of child item vendor>, vendor_store: <vendor store id of the item; note that this may be different from the sales order document's vendor_store>, vendor_sku: <vendor sku or "Tag Number" of the item>, vendor_inventory_id: <vendor inventory id>, vendor_part_name: <part type name, as assigned by the vendor>, year: <item year>, vehicle_make: <make of vehicle associated with item, if available>, vehicle_model: <model of vehicle associated with the item, if available>, part_manufacturer: <item's manufacturer>, part_model: <item's model>, sales_document_lineitem_type: <type of line item as applied to sales document>, description: <line item's description>, vin: <VIN associated with the line item, if any>, price: <price of the line item>, returnable: <true/false; if the line item is considered returnable>, days_to return: <number of days allowed for item return>, adjustments: {[ name: <adjustment name>, description: <adjustment description>, amount: <amount of adjustment, in USD>, is_taxable: <true/false; is this adjustment considered a taxable item>, is_subtotal_adjustment: <true/false; is this adjustment included in the subtotal (is it "above the line")> ]} }} ]} }
Listing Sales Documents
It can be helpful to see a listing of all available ITrack Sales Documents, particularly if, as is common, you aren't generating all of the transactions via the /sale/create process.
https://api.heavytruckparts.net/sale/list
You may choose to filter your list by particular vendors:
https://api.heavytruckparts.net/sale/list?vendor_id=<vendor id>
A HEAD request returns a count and list of ids necessary to identify sales documents in the system, i.e. just the vendor_id, vendor_store_id, online_transaction_id, and vendor_salesdocument_id.
HEAD:https://api.heavytruckparts.net/sale/list
{
"total_results": <total count of available sales documents>, "results": [{ "vendor_id": <vendor id of the sales document vendor>, "vendor_store": <vendor's store id where the sales document exists>, "vendor_salesdocument_id": <vendor's sales document id>, "online_transaction_id": <numeric id of the transaction as recorded as an online event>, "date_created": <YYYY-MM-DD HH:MM:SS style timestamp of when the sales document was created>, "date_closed": <YYYY-MM-DD HH:MM:SS style timestamp of when the sales document was closed; if closing date isn't available, the time of payment is used; if neither closing nor payment is available, this will be null>, "itrack_customer_id": <the vendor's ITrack customer id for the customer associated with this sales document, if available. 0 if no customer_id is available>, "vendor_approval_status": <One of "Pending", "Approved", "Expired" or "Rejected" indicating the vendor's approval response status for this sales document>, "customer_approval_status": <One of "Pending", "Approved", "Expired" or "Rejected" indicating the vendor's approval response status for this sales document>
}
A GET request returns additional data on each sales document, including the date of creation and (if valid) close; the associated itrack_customer_id, if any; and the approval status values for the sales document.
GET:https://api.heavytruckparts.net/sale/list
{
"total_results": <total count of available sales documents>, "results": [{ "vendor_id": <vendor id of the sales document vendor>, "vendor_store": <vendor's store id where the sales document exists>, "vendor_salesdocument_id": <vendor's sales document id>, "online_transaction_id": <numeric id of the transaction as recorded as an online event> }]
}
This list may be optionally filtered by userid/user_id, vendor_id, date_range (a comma separated start and end date), vendor_status, or customer_status:
GET:https://api.heavytruckparts.net/sale/list?userid=<userid/ITrack customerid>&vendor_id=<vendor id>&date_range=<start date>,<end date>&vendor_status=<vendor approval status>&customer_status=<customer approval status>
Sales Document Approval Status
HeavyTruckParts.Net online sales transactions now include a set of Document Approval fields to track the communication between the vendor and customer regarding a Sales Document. Many transactions cannot be easily shipped via parcel carriers or requires additional fitment kits that might not be clear to the customer. The Document Approval fields track visibility and acceptance by both the vendor and customer for a particular sale. ITrack (version 37+) and HeavyTruckParts.Net will automatically manage these fields if the transaction originates from HeavyTruckParts.Net, but if the transaction originates from a different site or service, or if the transaction is being loaded into an ERP system other than ITrack, it may be necessary to manage these approval fields directly via API calls.
The four states of an approval status are
- Pending: The transaction has been created and is waiting for a response - if it is Pending for both vendor and customer, it is waiting on the vendor to approve the document before it goes back to the user for final acceptance.
- Accepted: The transaction, in its current state, has been accepted by the party. If it is Accepted by the Vendor and Pending for the customer, the Sales Document is waiting on final approval and payment by the customer of the completed document.
- Expired: The transaction has expired waiting on approval by one or the other party; the party the status is Expired on did not indicate their approval in time before the document was considered invalid.
- Rejected: The transaction was rejected by the party because they do not like the terms of the transaction. Examples would be of the customer Rejecting the transaction after the vendor adds freight charges or the vendor Rejecting the transaction after contacting the customer because the customer's selected items do not actually meet their needs.
https://api.heavytruckparts.net/sale/approve
A PUT or POST request is used to update the approval status and will respond with the new approval status. A GET or HEAD request will return the current approval status of the sales document. The sales document can be specified either by vendor_id and online_transaction_id or by vendor_id, vendor_store, and vendor_salesdocument_id.
PUT and POST requests should include a JSON object with the desired approval status of the sales document. If you do not wish to modify one of the approval status fields, it may be omitted, only the field(s) provided in the request will be updated.
POST:https://api.heavytruckparts.net/sale/approve?vendor_id=<vendor id>&online_transaction_id=<online transaction id> POST:https://api.heavytruckparts.net/sale/approve?vendor_id=<vendor id>&vendor_store=<vendor store id where the sales document exists>&vendor_salesdocument_id=<vendor's sales document id>
{
vendor_approval: <optionally, one of "Pending", "Approved", "Expired", or "Rejected">, customer_approval: <optionally, one of "Pending", "Approved", "Expired", or "Rejected">
}
The response from the API following any GET, HEAD, PUT, or POST request will be the current approval status of the sales document
{
vendor_approval_status: <one of "Pending", "Approved", "Expired" or "Rejected">, customer_approval_status: <one of "Pending", "Approved", "Expired" or "Rejected">, transaction_status: <a summary value of the approval status: "submittedToVendor", "pendingUserApproval", "pendingUserPayment", "expiredOnVendor", "expiredOnUser", "cancelledByVendor", "cancelledByUser", or "Pending">
}
Please note that the sales document integration is under active development and may see additional changes in the near future.
Advertising Partner Feeds
To better serve our advertising partners, the GET /inventory/feed endpoint is available. This request provides a simplified listing of all inventory available to your apiuser in a single JSON object. Please note that collating inventory can take some time, so if you use this request, please set your request timeout to a large value. 120 seconds should be sufficient for most advertising partners, but some may need as many as 600 seconds. There are several differences between this request and a search for all results, most notably, an item hash value is included, the description is truncated with an ellipsis, and only the "top ranked" image URL is provided. The intended use of this endpoint is to provide a very fast list of all inventory items available to the advertising partner, and then further requests for complete item details would be made either on-demand or cached based on the item_hash value.
GET https://api.heavytruckparts.net/inventory/feed {"total_results": "the total number of results for this search", "results": ["type:"(USED,NEW,REMANUFACTURED, etc...)", "vendor":{ "company":"company name", "contact":"contact person", "city":"city the vendor is in", "state":"state the vendor is in", "postal_code":"zip code or postal code for the vendor", "phone_number":"the vendor's phone number", "fax_number":"the vendor's fax number", "email":"the vendor's email address", "vendor_id": "the vendor's numeric id", "vendor_store": "the vendor's numeric store id" }, "part_name":"the part type name", "make_model":"the make or manufacturer and model of the item", "year":"the year of the item, if provided", "vendor_sku":"the SKU or Tag Number assigned to this item by the vendor", "vendor_inventory_id": "the unique numeric id for this item in the vendor's ITrack system", "description":"the description of the item, limited to 175 characters with an additional ellipsis, if appropriate", "price":"the retail price of the item", "coreprice":"the core return price on the item, if any", "condition":"the item's condition, as described by the vendor", "details_uri":"a URL to request for further information on this item", "images":"a URL for the image marked as the 'top ranked' by the vendor", "item_hash": "a SHA256 hash of this item's current state" ]] }
To obtain further information, like the complete description of the item, the full list of the item's images, item Q&A information, or the custom pricing for the enduser, please make a specific details request for the item.
Things to Remember
- The API is stateless. If you have a request for a particular end user (like custom pricing) it is your responsibility to provide that end user id, and to ensure that the correct end user id is passed in any request for that end user. If you are handling sessions for your users, session management is your responsibility; the API has no concept of sessions.
- The API tends to use the word "make" in the requests, responses, and documentation, but except for places like the item details where vehicle_make and part_manufacturer are explicitly separated, it considers make and manufacturer (as well as vehicle model and part model) interchangeably. If you check availability for "makes" for, say, engines, which are based on part manufacturer rather than vehicle make, then the engine manufacturers will be returned in the list, not the vehicle makes of the vehicles the engines came out of.
- Vendor_sku is the "tag number" of the item, which the vendor's sales team will recognize as representing the item. It's not guaranteed to be unique, which is fine when contacting the vendor, but when using the API to make specific requests about an item, the vendor_inventory_id must be used instead, as that value is unique to the vendor and store.