Web Service Authentication

Preparation for access
The authentication mechanism for using these web services leverages the Salesforce OAuth 2.0 JWT Bearer flow to generate an access token that will permit access to the APIs for up to 30 minutes at a time. Attempts to call the web services without a valid access token will fail.
In order to get access, the third-party user must log into their mySutton account, go to their Settings and to the Product API link to enable their API access:
This will email them their API Token to be used below. Note that this token should be treated like a “password” and stored securely by the third party. If the API token is ever lost or compromised, a new token can be generated via their mySutton account.

Authentication Process
In order to obtain an access token, a HTTPS POST operation must be performed to the following URL:

https://suttontools.my.salesforce-sites.com/authenticate/services/apexrest/suttonsapi

The body of the HTTPS request needs to be a JSON-formatted payload as follows:

Element	Sub Element	Description
request		The top-level element in the body
	username	The third party’s username used to normally to access the Community Portal (String value).
	apiToken	The API token generated by the Community Portal (String value).

Example request:

{
    "request": {
        "username": "thirdparty@reseller.com.au",
        "apiToken": "KJGREKNB345345OHLSAFDSF4D464HSDF243BFDFBFHE6NJDSSB35JGF244N7"
    }
}

The HTTPS POST request should set a Content-Type header of application/json also.

The response that comes back will consist of two values:

Element	Description
instance_url	The Salesforce instance to which further API requests (below) should be directed.
access_token	The access token to use for those requests that is valid for the next 30 minutes.

Example Response:

{
    "instance_url": "https://suttontools.my.salesforce.com",
    "access_token": "00DO00000053omK!ARYAQG0TRJtjKLZE1BcCZn4x1pfc1KJ8faC.K1Neqjq2FpNmuaNSww4a4DlP0Qa.Hv9zVGFAi0AfOkSwD2RQ8Zo9mlTfVpmc"
}

The access_token returned needs to be set as an Authorization header for further HTTPS API requests with a value of Bearer {access_token}. The instance_url should be used in the below sections wherever you see {instance_url} documented.

Error Handling
If there are any issues with the JSON request passed in (e.g., it is badly formatted), you will get a JSON error response such as this:

[
    {
        "message": "Unexpected parameter encountered during deserialization: requst at [line:2, column:16]",
        "errorCode": "JSON_PARSER_ERROR"
    }
]

If the request is ok, but there is an issue with authentication, (e.g., wrong or invalid apiToken), you will get simply an error back.

Product Category API

Request
Categories is the overarching mechanism used for organising products into groups, e.g., drill bits, chisels, sawblades, etc. In order to query product categories, send a request to this endpoint:

HTTPS GET {instance_url}/services/apexrest/V1/ProductCategories

The following parameters can be added to this URL, in the form ?param1=value1&param2=value2&...

Parameter	Required	Possible or Example Values	Description
Region	No*	AUSTRALIA	The specific region to fetch product categories for; values are AUSTRALIA, EUROPE, ASIA, USA, NEW ZEALAND
UniqueCategoryNames	No*	R784, R581, K333Sets	A list of Unique Product Category Names to query. Multiple values can be specified and need to be separated by commas.
Offset		300	Use this parameter in combination with the with Size parameter to achieve pagination. If there is likely to be a large number of categories returned, e.g., you are querying by Region. The Offset should be a multiple of the page size, starting from 0.
Size	No	100	How many categories to return in one call.
IncludeImages	No	true or false	Boolean value as to whether to return image URL information in the response. These will be links to images on Amazon S3.
LastSyncHours	No*	1	An integer to find categories that have been modified (or had a product in them modified) in the last ‘n’ hours.
QtyPriceOnly	No	true or false	Cuts down the response to a smaller subset of the product category information as we are only going to be querying quantity/price information for the products in the categorie(s).

Note that for the parameters above marked with *, at least one of these parameters must be provided.

Example Request
{instance_url}/services/apexrest/V1/ProductCategories?Region=USA&Offset=400&Size=100

Response
The response that is returned is primarily an array of category records and some supporting information. The main elements are outlined in the below table:

Element	Sub Element	Description
TotalCount		How many categories have been returned. If the results are being paginated and this doesn’t match the “Size” parameter passed in, then you can assume you have all results back.
Success		True/false as to whether the API call was successful.
ErrorMessage		If success = false, this will show the error that occurred.
Categories		An array of the categories returned.
	UniqueCategoryName	The unique category name identifying this category from every other category, e.g., PD101Sets
	SellRegions	An array of regions as to where this product is sold (AUSTRALIA, USA, EUROPE, etc).
	RecommendedApplications	An array of the various applications for this tool category with a range of materials.
	ShortDesc	A Short description for the product category.
	LongDesc	A Long description for the product category.
	FeaturesAndBenefits	An array of Strings describing the features and benefits of the category.
	CatProductAttributes	The overarching attributes for the products in this category.
	CategoryImages	An array of image information with URLs pointing to an Amazon S3 bucket where the images can be obtained.

Example Response

{
    "TotalCount": 1,
    "Success": true,
    "ErrorMessage": "",
    "Categories": [
        {
            "VideoLink": "",
            "UpDownCut": [],
            "UnitOfMeasure": [],
            "UniqueCategoryName": "PD101",
            "Trades": [
                "Automotive",
                "Cabinet Making",
                "Carpenter",
                "Electrician",
                "Fitter & Turner",
                "General Contractor",
                "Maintenance Repair",
                "Mechanic",
                "Metal Worker",
                "Plasterer",
                "Plumber",
                "Woodworker"
            ],
            "ToolsSurfaceFinish": [],
            "ToolMaterial": [],
            "Standard": null,
            "ShankTolerance": [ 
                "ANSI B94-11 / DIN338"
            ],
            "ShankForm": [
                "A"
            ],
            "Shank": [],
            "SellRegions": [
                "AUSTRALIA"
            ],
            "RecommendedApplications": [
                {
                    "MaterialSubGroup": [
                        "Aluminium",
                        "Copper / Brass",
                        "Metal Pipe",
                        "Sheet Metal",
                        "Steel"
                    ],
                    "MaterialGroup": "Metal"
                },
                {
                    "MaterialSubGroup": [
                        "Plasterboard"
                    ],
                    "MaterialGroup": "Masonry"
                },
                {
                    "MaterialSubGroup": [
                        "PVC Plastic"
                    ],
                    "MaterialGroup": "Specialty"
                },
                {
                    "MaterialSubGroup": [
                        "Chipboard",
                        "Hard Wood",
                        "MDF",
                        "Pallet",
                        "Plywood",
                        "Sandwich Construction",
                        "Soft Wood",
                        "Window Frame",
                        "Wood & Nails"
                    ],
                    "MaterialGroup": "Wood"
                },
                {
                    "MaterialSubGroup": [
                        "Steel"
                    ],
                    "MaterialGroup": "P"
                },
                {
                    "MaterialSubGroup": [
                        "Cast Iron"
                    ],
                    "MaterialGroup": "K"
                },
                {
                    "MaterialSubGroup": [
                        "Non-Ferous Metals"
                    ],
                    "MaterialGroup": "N"
                },
                {
                    "MaterialSubGroup": [
                        "Hard Materials"
                    ],
                    "MaterialGroup": "H"
                }
            ],
            "ProductGroup": null,
            "PowerTools": [
                "Power Drill",
                "Hammer Drill",
                "Pedestal Drill"
            ],
            "MaxCutDepth": [
                "5xD"
            ],
            "ShortDesc": "P&N Bright Max jobber drill bits”,
            "LongDesc": "P&N Bright Max jobber drills are a general purpose drill bit designed for machine and hand held drilling in a wide range of ferrous & non-ferrous materials such as steel, aluminium, brass, wood & plastics.",
            "LastModifiedForSync": "2020-09-08T10:15:07.000Z",
            "isIndustrial": true,
            "isConsumer": true,
            "isActive": false,
            "Id": "a2D1e000000CbZUEA0",
            "HelixAngle": [
                "R30"
            ],
            "Flute": [],
            "FeaturesAndBenefits": [
                "118° standard point for general purpose applications",
                "Precision engineered parallel shank for accurate hole size",
                "",
                "",
                "Made from M2 High Speed Steel (HSS) offering the best combination of strength, heat & wear resistance",
                "Bright finish for general purpose applications, non-ferrous metals & plastics"
            ],
            "Coolant": [],
            "CatType": "Drills",
            "CatSubType": "Jobber",
            "CatProductAttributes": {
                "Point Angle": "118°",
                "x": "als",
                "Shank Form": "A",
                "Point Tolerance": "h8",
                "Point Form": "Standard",
                "Max Cut Depth": "5xD",
                "Material": "HSS",
                "Helix Angle": "R30",
                "Finish": "Brt",
                "Designation": "N",
                "Cutting Edges": "ul",
                "Standard": "ANSI B94-11 / DIN338"
            },
            "CatName": "Jobber Drills - Bright Max",
            "CategoryType": "None",
            "CategoryImages": [
                {
                    "UrlS3": "https://s3-ap-southeast-2.amazonaws.com/suttontools/Media+Library/Product+Images/PN/Drills/Jobber+-+Bright+Max/JPEG+72dpi/P&N_Jobber_DIN338_HSS.jpg",
                    "Type": "Hero",
                    "MIMEType": null,
                    "isHidden": false,
                    "ImageOrder": 0,
                    "Id": "a2E1e000000Gx0XEAS"
                },
                {
                    "UrlS3": "https://s3-ap-southeast-2.amazonaws.com/suttontools/Media+Library/Product+Images/PN/Drills/Jobber+-+Bright+Max/JPEG+72dpi/P&N_JobberHSS_Drawing.jpg",
                    "Type": "Line Drawing",
                    "MIMEType": null,
                    "isHidden": false,
                    "ImageOrder": 0,
                    "Id": "a2E1e000000Gx0hEAC"
                },
                {
                    "UrlS3": "https://s3-ap-southeast-2.amazonaws.com/suttontools/Media+Library/Product+Images/PN/Drills/Jobber+-+Bright+Max/JPEG+72dpi/P&N_Jobber_HSS_Tip.jpg",
                    "Type": "Gallery",
                    "MIMEType": null,
                    "isHidden": false,
                    "ImageOrder": 0,
                    "Id": "a2E1e000000Gx0cEAC"
                }
            ],
            "CatCode": "PD101",
            "Brand": [
                "P&N",
                "Bright Max"
            ],
            "AngleFromVertical": []
        }
    ]
}

Product API

Request
Products are the individual units which are sold by Sutton Tools and are organised into Categories. In order to query products, send a request to this endpoint:

HTTPS GET {instance_url}/services/apexrest/V1/Products

The following parameters can be added to this URL, in the form ?param1=value1&param2=value2&...

Parameter	Required	Possible or Example Values	Description
Region	No*	AUSTRALIA	The specific region to fetch product categories for; values are AUSTRALIA, EUROPE, ASIA, USA, NEW ZEALAND
UniqueCategoryNames	No*	R784, R581, K333Sets	A list of Unique Product Category Names to query. Multiple values can be specified and need to be separated by commas.
Offset		300	Use this parameter in combination with the with Size parameter to achieve pagination. If there is likely to be a large number of categories returned, e.g., you are querying by Region. The Offset should be a multiple of the page size, starting from 0.
Size	No	100	How many categories to return in one call.
IncludeImages	No	true or false	Boolean value as to whether to return image URL information in the response. These will be links to images on Amazon S3.
LastSyncHours	No*	1	An integer to find categories that have been modified (or had a product in them modified) in the last ‘n’ hours.
QtyPriceOnly	No	true or false	Cuts down the response to a smaller subset of the product category information as we are only going to be querying quantity/price information for the products in the categorie(s).
WarehouseCode	No	AKL, CBT, EUR, EUS, SIN	The warehouse code to query stock levels for, if applicable.

Note that for the parameters above marked with *, at least one of these parameters must be provided.

Example Request
{instance_url}/services/apexrest/V1/Product?ProductIds=a2E1e000000Gx0hEAC&LastSyncHours=1

Response
The response that is returned is primarily an array of category records and some supporting information.

Element	Sub Element	Description
TotalCount		How many categories have been returned. If the results are being paginated and this doesn’t match the “Size” parameter passed in, then you can assume you have all results back.
Success		True/false as to whether the API call was successful.
ErrorMessage		If success = false, this will show the error that occurred.
Categories		An array of the categories returned.
	SellRegions	An array of regions as to where this product is sold (AUSTRALIA, USA, EUROPE, etc).
	Quantity	The current stock on hand of this product.
	ProductImages	An array of image information with URLs pointing to an Amazon S3 bucket where the images can be obtained for this product.
	ProductAttributes	The specific attributes of this product.
	Prices	An array of one or more prices for this product, by currency.

Example Response

{
    "TotalCount": 1,
    "Success": true,
    "ErrorMessage": "",
    "Products": [
        {
            "SKU": "",
            "SellRegions": [
                "NEW ZEALAND"
            ],
            "Quantity": 10,
            "ProductImages": [
                {
                    "UrlS3": "https://s3-ap-southeast-2.amazonaws.com/suttontools/Media+Library/Product+Images/PN/Drills/Jobber+-+Bright+Max/JPEG+72dpi/P&N_Jobber_DIN338_HSS.jpg",
                    "Type": "Hero",
                    "MIMEType": null,
                    "isHidden": false,
                    "ImageOrder": 0,
                    "Id": "a2E1e000000Gx0nEAC"
                }
            ],
            "ProductCode": "1209699",
            "ProductAttributes": {
                "Item #": "1209699",
                "d1 (mm)": "9.5",
                "l1": "125",
                "l2": "81"
            },
            "Prices": [
                {
                    "UnitPrice": 15.33,
                    "Region": "AUSTRALIA",
                    "CurrencyIsoCode": "AUD"
                }
            ],
            "PackQuantity": "Bulk",
            "Name": "DRL JBBR 9.50 BRT",
            "Multiple": 5,
            "M3ShortDesc": "DRL JBBR 9.50 BRT",
            "M3ItemStatus": "50",
            "M3ItemNo": "1209699",
            "M3ItemDesc": "DRILL 9.5mm JOBBER DIN338 HSS",
            "LastModifiedForSync": "2020-09-07T14:19:49.000Z",
            "isActive": true,
            "Id": "01t28000004A6QtAAK",
            "CatCode": "PD101",
            "Barcode": "9312621723123"
        }
    ]
}

Product Application API
Request
The application information for a product is displayed in the “Applications” tab under a given product category. In order to query product application information, send a request to this endpoint:

HTTPS GET {instance_url}/services/apexrest/V1/Applications

The following parameters can be added to this URL, in the form ?param1=value1&param2=value2&...

Parameter	Required	Possible or Example Values	Description
UniqueCategoryName	No*	R784, R581, K333Sets	A list of Unique Product Category Names to query for their products. Multiple values can be specified and need to be separated by commas.
CategoryId	No*		A comma separated list of Category Ids to query. These values are specific internal Ids of records required, and normally will not be used to access applications.
CategoryCode	No*	R784, R581, K333	A comma separated list of Category Codes to query. These values may or may not be unique, as against the UniqueCategoryName parameter.

Note that for the parameters above marked with *, at least one of these parameters must be provided.

Example Request
{instance_url}/services/apexrest/V1/Applications?UniqueCategoryName=PD101

Response
The response that is returned is primarily an array of application records and some supporting information.

Element	Sub Element	Description
Success		True/false as to whether the API call was successful.
ApplicationList		A list of applications for this product with detail about each, as per the website.

Example Response

{
    "Success": true,
    "ApplicationList": [
        {
            "VDI": "2",
            "StrengthUnit": "Mpa",
            "Strength": 640,
            "Recommendation": "Optimal",
            "MC": 0.22,
            "KC1": 1500,
            "ISO": "P",
            "IsIndustrial": true,
            "IsCommercial": false,
            "IndustrialMaterial": "Steel",
            "Id": "a2B1e000000G1a2EAC",
            "HardnessUnit": "HB",
            "Hardness": 190,
            "Description": "Steel - Non-alloy, cast & free cutting (~ 0.45 %C)",
            "Condition": "Annealed",
            "CommercialMaterialSubGroup": null,
            "CommercialMaterialGroup": null
        },
        {
            "VDI": "3",
            "StrengthUnit": "Mpa",
            "Strength": 840,
            "Recommendation": "Effective",
            "MC": 0.24,
            "KC1": 1675,
            "ISO": "P",
            "IsIndustrial": true,
            "IsCommercial": false,
            "IndustrialMaterial": "Steel",
            "Id": "a2B1e000000G1a3EAC",
            "HardnessUnit": "HB",
            "Hardness": 250,
            "Description": "Steel - Non-alloy, cast & free cutting (~ 0.45 %C)",
            "Condition": "Quenched & Tempered",
            "CommercialMaterialSubGroup": null,
            "CommercialMaterialGroup": null
        }
    ]
}