Product API

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: 

  1. 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. 

  1. Each product is validated against the product XSD. 

  1. A response is generated containing a success or failure for each product provided in the request. 

  1. 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 

 

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>  
    <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,  
      "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."  
            }  
         ]  
      }  
   ] }