Overview
Use the Product API to create a product record in Aimbase.
Related APIs:
- To filter, sort, retrieve and update a brand use the Brand Odata.
- To filter, sort, retrieve and update a product use the Product Odata.
Product data is submitted to our API via HTTP POST. The API will accept JSON or XML based on what content type is set in the Content-Type HTTP header. To submit JSON data set the Content-Type header to “application/json”, to submit XML set the Content-Type HTTP header to “application/xml”.
The Product API requires authentication so the HTTP POST will require a valid Authenticate message header with an API token. See the Aimbase Authentication Web Service Specification for more details on how to retrieve a valid API token.
The process flow of sending product(s) to the system is as follows:
New products should be included in a request sent via an HTTP POST to the end point. The request may contain one or more products.
Each product is validated against the product XSD.
A response is generated containing a success or failure for each product provided in the request.
Any product successfully passing the first wave of validation checks will be assigned an Id that uniquely identifies the record in the staging process. This Id will be included in the response.
Possible response codes are:
201 (Created). This response indicates that the Product data was successfully parsed. The body of the response will contain the success or failure status for each product that was submitted in the request.
400 (Bad Request). Along with the 400 response, the body of the response will contain an error message describing why the request was a bad request. See Appendix D for the structure of an error response.
500 (Internal Server Error). An unknown error occurred during the import.
The HTTP endpoint that will accept the POST data are:
https://{baseaddress}/api/product?manufacturer={MFGcode}
Note: {baseaddress} and {MFGcode} will be provided by Rollick.
Below is the list of properties that are accepted in the POST body.
Product Data Schema
| Field Name | Required | Format | Description |
| Code | X | Max Length: 50 | The product code is the unique identifier for a model. All products must be unique by Code and ModelYear. |
| Name | X | Max Length: 80 | |
| Brand | Max Length: 128 | The Brand name. | |
| PlantCode | Max Length: 6 | The unique identifier of the Plant. | |
| PlantName | Max Length: 50 | ||
| ProductTypeName | Max Length: 50 | ||
| SkuCode | Max Length: 50 | ||
| ModelYear | X | Number >= 0 and <= 3000 | |
| IsActive | Bool, 1 or 0 value | ||
| DealerMustCarryForLocator | Booelan | The true/false value in this field indicates a dealer must have the product assigned to be able to receive that lead or returned in the dealer locator. | |
| ApplicationContextCode | Max Length: 20 |
Used to designate the product as being available for lead generation or just for satisfaction. Possible Values: B = Both S = Sales (lead generation) O= Owner (satisfaction) If no value passed, defaults to Owners only. |
|
| ProductCategory | Product Category Element | A tree structure of product categories. |
Product Category Data Schema
| Field Name | Required | Format | Description |
| Code | X | Max Length: 48 | The unique identifier for the product category. |
| Name | X | Max Length: 128 | |
| SubCategory | Product Category Element |
Custom Data Schema
| Field Name | Required | Format | Description |
| FieldName | X | Max Length: 2048 | The field name of the custom field. |
| FieldName | X | Max Length: 2048 | The field name of the custom field. |
APPENDIX A – Sample POST/Response (XML)
Post:
<Products>
<Product>
<Code>100DSLC</Code>
<Name>100 Diesel Cruiser</Name>
<Brand>Diesel Cruiser</Brand>
<PlantCode>FL</PlantCode>
<PlantName>Florida Plant</PlantName>
<ProductTypeName>Boat</ProductTypeName>
<ModelYear>2014</ModelYear>
<IsActive>1</IsActive>
<DealerMustCarryForLocator>true</DealerMustCarryForLocator>
<ProductCategory>
<Code>OUT</Code>
<Name>Outboard Boats</Name>
<ProductCategory>
<Code>FOB</Code>
<Name>Fiberglass Outboard Boats</Name>
<ProductCategory>
<Code>Under 14ft</Code>
<Name>Under 14ft</Name>
</ProductCategory>
</ProductCategory>
</ProductCategory>
</Product>
<Product>
<Code>101DSLC</Code>
<Name>101 Diesl Cruiser</Name>
<ModelYear>2014</ModelYear>
<IsActive>true</IsActive>
<Customs>
<Custom>
<FieldName>Field1</FieldName>
<FieldValue>FieldValue1</FieldValue>
</Custom>
<Custom>
<FieldName>Field2</FieldName>
<FieldValue>FieldValue2</FieldValue>
</Custom>
</Customs>
</Product>
</Products>
Response:
<Products> <Product> <Id>0</Id> <Status>Success</Status> <StatusMessage>Product successfully received</StatusMessage> <Messages /> <Code>100DSLC</Code> <ModelYear>2014</ModelYear> </Product> </Products>
APPENDIX B – Sample POST/Response (JSON)
Post:
[
{
"Code":"100DSLC",
"Name":"100 Diesel Cruiser",
"Brand":"Diesel Cruiser",
"PlantCode":"FL",
"PlantName":"Florida Plant",
"ProductTypeName":"Boat",
"SkuCode":null,
"ModelYear":2014,
"IsActive":1,
"DealerMustCarryForLocator":"true",
"ApplicationContextCode":null,
"ProductCategory":{
"Code":"OUT",
"Name":"Outboard Boats",
"SubCategory":{
"Code":"FOB",
"Name":"Fiberglass Outboard Boats",
"SubCategory":{
"Code":"Under 14ft",
"Name":"Under 14ft",
"SubCategory":null
}
}
}
},
{
"Code":"101DSLC",
"Name":"101 Diesl Cruiser",
"Brand":null,
"PlantCode":null,
"PlantName":null,
"ProductTypeName":null,
"SkuCode":null,
"ModelYear":2014,
"IsActive":1,
"ApplicationContextCode":null,
"ProductCategory":null,
"Customs":{
"Custom":[
{
"FieldName":"Field1",
"FieldValue":"FieldValue1"
},
{
"FieldName":"Field2",
"FieldValue":"FieldValue2"
}
]
}
} ]
Response:
{ "TopLevelError" : null, "ProductResponseRecords" : [{ “Code” : “100DSLC”, “ModelYear” : 2014 "Id" : "0", "Status" : "Success", "StatusMessage" : "Product successfully received", } "Messages" : [ ] ] }
APPENDIX C – Sample Failed Responses (XML/JSON)
The error responses below were generated by submitting a product without the required field “IsActive”.
XML Response
<Products> <Product> <Status>Failure</Status> <StatusMessage>Product failed validation</StatusMessage> <Messages> <Message> <Field>IsActive</Field> <Message>The IsActive field is required.</Message> </Message> </Messages> <Code>100DSLC</Code> <ModelYear>2014</ModelYear> </Product> </Products>
JSON Response
{ "TopLevelError":null, "ProductResponseRecords":[ { "Code":"100DSLC ", "ModelYear":"2014", "Id":null, "Status":"Failure", "StatusMessage":"Product failed validation.", "Messages":[ { "Field":"IsActive", "Message":"The IsActive field is required." } ] } ] }