Api.heavytruckparts.net - Revision history

Broy: /* Sales Documents */ Added documentation on making payments.

2025-02-21T19:12:24Z

Sales Documents: Added documentation on making payments.

@@ Line 502: / Line 502: @@
      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",
+     approval_status: 'the vendor's approval status for the transaction: "approved", "rejected", "expired", "pending"; optional, if not present it assumes "pending"',
      line_items: [
+         {
@@ Line 537: / Line 537: @@
          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.
+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 payment object is entirely optional but may be added if there is an immediate payment to associate with this transaction.  It is common to create the transaction, and then associate payments later via /sale/payment.
 The creation process will return a JSON response:
@@ Line 801: / Line 812: @@
    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.

Broy: /* Listing Sales Documents */ Add the supported filters for /sale/list

2024-08-19T16:37:04Z

Listing Sales Documents: Add the supported filters for /sale/list

← Older revision		Revision as of 11:37, 19 August 2024
Line 768:		Line 768:
	}]		}]
	}		}

			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===		===Sales Document Approval Status===

Broy: /* Advertising Partner Feeds */ Fixed some typos and added the item_hash result entry.

2024-03-21T20:50:50Z

Advertising Partner Feeds: Fixed some typos and added the item_hash result entry.

← Older revision		Revision as of 15:50, 21 March 2024
Line 802:		Line 802:

	== 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":
	["~~typ"e~~:"(USED,NEW,REMANUFACTURED, etc...)",		["type:"(USED,NEW,REMANUFACTURED, etc...)",
	"vendor":{		"vendor":{
	"company":"company name",		"company":"company name",
Line 830:		Line 830:
	"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 "top ranked" by the vendor]]		"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" ]]
	}		}

Broy: /* Sales Document Approval Status */

2024-03-15T20:55:50Z

Sales Document Approval Status

← Older revision		Revision as of 15:55, 15 March 2024
Line 778:		Line 778:
	* '''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.		* '''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>		<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.		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.		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>&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>		<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">,		vendor_approval: <optionally, one of "Pending", "Approved", "Expired", or "Rejected">,
Line 791:		Line 792:

	The response from the API following any GET, HEAD, PUT, or POST request will be the current approval status of the sales document		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">,		vendor_approval_status: <one of "Pending", "Approved", "Expired" or "Rejected">,

Broy: /* Sales Documents */ Added examples for /sales/list; Created documentation for the Sales Document Approval fields

2024-03-15T20:54:18Z

Sales Documents: Added examples for /sales/list; Created documentation for the Sales Document Approval fields

@@ Line 743: / Line 743: @@
 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>
 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>
 Please note that the sales document integration is under active development and may see additional changes in the near future.

Broy: /* Sales Documents */ Added some basic information on /sale/list; still needs example results.

2024-03-14T22:05:43Z

Sales Documents: Added some basic information on /sale/list; still needs example results.

← Older revision		Revision as of 17:05, 14 March 2024
Line 581:		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 733:		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>

			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>

	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.

Broy: /* Creating Sales Documents */ Clarified that item shipping is not currently used.

2023-12-20T21:57:55Z

Creating Sales Documents: Clarified that item shipping is not currently used.

← Older revision		Revision as of 16:57, 20 December 2023
Line 511:		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 539:		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:

Broy: /* Making a Request */ Added the require_images optional parameter

2023-07-21T15:33:24Z

Making a Request: Added the require_images optional parameter

← Older revision		Revision as of 10:33, 21 July 2023
Line 45:		Line 45:
	**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.		**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.

Broy: /* Creating Sales Documents */ Added "non_itrack_user" and "approval_status" parameters to the documentation.

2022-10-12T21:15:11Z

Creating Sales Documents: Added "non_itrack_user" and "approval_status" parameters to the documentation.

← Older revision		Revision as of 16:15, 12 October 2022
Line 497:		Line 497:
	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: [
	{		{

Broy: /* Making a Request */ Added date_updated/date_modified as a sort_column option.

2022-09-12T20:42:56Z

Making a Request: Added date_updated/date_modified as a sort_column option.

← Older revision		Revision as of 15:42, 12 September 2022
Line 42:		Line 42:
	**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 "~~date_added~~".		**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).