Marketplaces / Autofixa / Autofixa Offers

Autofixa Offers

The purpose of this document is to specify the way Hemisphere should integrate into Autofixa’s offers flow to update stock, price and product shipping information

We need to cover two flows for the offers - Create and Update. As Autofixa controls the whole product content creation we don’t have any product details specified in Hemisphere. This means that our first steps will always be around Creating of an offer which will push all needed statuses to the right place for any subsequent updates. Below can be found all specifications for the two flows

Create Offer

API Call: POST /api/offer/create

API Docs: https://autofixa-test-seller-api.azurewebsites.net/index.html

Example Call:

{
  "productId": 0,
  "sku": "string",
  "sellerSKU": "string",
  "title": "string",
  "quantity": 0,
  "price": 0,
  "specialPrice": 0,
  "specialPriceStartDate": "2021-12-20T08:25:11.711Z",
  "specialPriceEndDate": "2021-12-20T08:25:11.711Z",
  "shippings": [
    {
      "shippingId": 0,
      "shippingName": "string",
      "isActive": true,
      "price": 0
    }
  ]
}

Call Mapping:

Integration Field	Integration required	Hemi Mapping	Hemi Notes
`productId`	N	N/A	As previously mentioned we have no record of the actual product in Hemisphere and as it is a catalogue we are creating an offer against an EAN which is the most important and leading field in the communication (`sku` in the Autofixa payload)
`sku`	Y	Item > MPN
`sellerSKU`	Y	Item > SKU
`title`	Y	Item Account > Title
`quantity`	Y	Item Account > Quantity
`price`	Y	Item Account > StartPrice

Example Response:

Success

//Headers

api-supported-versions: 1.0
 content-length: 4
 content-type: application/json; charset=utf-8
 date: Tue21 Dec 2021 11:32:59 GMT
 request-context: appId=cid-v1:8dbe6804-6855-4248-8dcc-0dff9f1ad32e
 server: Microsoft-IIS/10.0
 strict-transport-security: max-age=5184000; includeSubDomains; preload
 x-powered-by: ASP.NET

 //Body

 3847

Bad Request:

 //Headers

 content-length: 350
 content-type: application/json; charset=utf-8
 date: Wed22 Dec 2021 09:12:16 GMT
 request-context: appId=cid-v1:8dbe6804-6855-4248-8dcc-0dff9f1ad32e
 server: Microsoft-IIS/10.0
 strict-transport-security: max-age=5184000; includeSubDomains; preload
 x-powered-by: ASP.NET

 //Body

 {
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "00-a6eb7718cbf268428f17838d60259cb0-b5a282c3c0e9e547-00",
  "errors": {
    "$.shippings[1]": [
      "'{' is invalid after a value. Expected either ',', '}', or ']'. Path: $.shippings[1] | LineNumber: 16 | BytePositionInLine: 4."
    ]
  }
}

note: We are expecting to store the errors

Server Error

//Headers

api-supported-versions: 1.0
 content-length: 53
 content-type: application/json
 date: Wed22 Dec 2021 09:14:26 GMT
 request-context: appId=cid-v1:8dbe6804-6855-4248-8dcc-0dff9f1ad32e
 server: Microsoft-IIS/10.0
 strict-transport-security: max-age=5184000; includeSubDomains; preload
 x-powered-by: ASP.NET

 //Body

 {
  "StatusCode": 500,
  "Message": "Internal Server Error."
}

note: We are expecting to store the Message

Response Mapping: If we have a successful Creation we should map the Offer ID as received to Item Account Storesome > Product ID. Otherwise we are to store the correct error as per the above notes

Additional Information:

Workflow steps - Nothing specific - pure pick and send to Autofixa, no additional steps to go through
Type of communication - Synchronous communication. This call at this point can accept only 1 by 1 communication. We should build our functionality to be able to put multiples in the feed at a later stage but only 1 to start with
Hemisphere requirements for execution - We are to pick offers for creation for products that cover the following parameters
- revise_item = pending
- productStatus IN (Awaiting Creation, Product Created, Product Not Created)
- ChannelItemID = ''
- item_closed = 0
Everything will be picked 1 by 1, doesnt matter if a product is in variation(it will not use the default logic to pick all products in the one variation).
Outstanding specifics
- Shippings - Autofixa allows a specific number of shipment services (currently 3) on each product. Those are controlled by the Type but are in reality always present all of them. This means that if we just stop updating one of the 3 it will keep its latest update and potentially be available with that old value when we don’t want it to be available at all (because we’ve dropped it from our template). Best way to handle this is to have a place to keep all shipping services that Autofixa provides. These services should be created as part of the setup for the Storesome Account. Then we have to track what is created as shipment methods in the “Hemisphere Shipping Template” that is applied to the product and map the Shipping Template > Shipping Method > Shipping Service field with “Name” from the Storesome Shipping Services that we’ve created as available. For every method that we map we should pass “true” for the isActive filed in the product payload to Autofixa. For every “Storesome Shipping Service” that we can’t map (is not present in the Shipping Methods of the template) we should send “false”. As already suggested this setup should happen via a new table under Account Storesome (Account Storesome Shipping Service) that will hold the necessary information (as multi records) for each Storesome service. The table should hold the Names of the Services, their type (an enumeration value field to ensure the 3 services of Autofixa are prioritised the right way one over the other) and the id of the shipping service
- Fields specifications - For both Create and Update almost all fields are mandatory - Only fields that are not mandatory to be filled in every time are the special price fields. This will be explained further in the Update section. What is important to specify here is that for create the fields protect_quantity and protect_price are not important and are not to be looked at
Limits - 1 by 1 per call
Error reporting - nothing specific but to make sure we store the right error against the right line
When successful we want to update the productStatus to “published” and the listingStatus to “active” (if the quantity was positive. If not - listingStatus should not be updated). Additionally we need to update the ChannelItemID and fill it in with a grouping element (variation group) or if any such is not present the MPN of the product
Last but not least we need to store from the successful response an offerID (example has been requested). This should be stored in Item Account Storesome > Product ID (TBD if we shouldn’t have this as ChannelItemID?). The offer ID is then used in the update flow
As always update_quantity and update_price should reflect the correct status of the communication
- sent - if we are working with this at the moment
- normal - if we’ve successfully completed the operation
- error - if there has been a problem (to include the message in the respective error fields as well)
  
  Both fields are to act together and as per our standards not overlap any pending values that should trigger a consecutive update (please refer to the respective stock and price abstraction explanations and flag systematisation)

Update Offer

API Call: PUT /api/offer

API Docs: https://autofixa-test-seller-api.azurewebsites.net/index.html

Example Call:

{
  "id": 0,
  "sku": "string",
  "sellerSKU": "string",
  "title": "string",
  "quantity": 0,
  "price": 0,
  "specialPrice": 0,
  "specialPriceStartDate": "2021-12-20T16:13:00.919Z",
  "specialPriceEndDate": "2021-12-20T16:13:00.919Z",
  "shippings": [
    {
      "shippingId": 0,
      "shippingName": "string",
      "isActive": true,
      "price": 0
    }
  ]
}

Call Mapping:

Integration Field	Integration required	Hemi Mapping	Hemi Notes
`id`	Y	Item Account Storesome > Product ID	This is a mandatory field for an update
`sku`	Y	Item > MPN
`sellerSKU`	Y	Item > SKU
`title`	Y	Item Account > Title
`quantity`	Y	Item Account > Quantity
`price`	Y	Item Account > StartPrice

Example Response:

true
// OR
Bad Request
// OR
Server Error

Response Mapping: Nothing specific to be mapped - we are counting on the code predominantly. Example for a 400 request doesn’t provide any additional information but for 400 and 500 we should store the string against the respective lines

Note: Specific examples will be added to be examined in the doc as well

Additional Information:

Workflow steps - Nothing specific - pure pick and send to Autofixa, no additional steps to go through
Type of communication - Synchronous communication. This call at this point can accept only 1 by 1 communication. We should build our functionality to be able to put multiples in the feed at a later stage but only 1 to start with
Hemisphere requirements for execution - We are to pick offers for update for products that cover the following parameters
- revise_item = pending
- productStatus = published
- ChannelItemID <> ''
- item_closed = 0
- protect_quantity = 0
Outstanding specifics
- Shippings - Autofixa allows a specific number of shipment services (currently 3) on each product. Those are controlled by the Type but are in reality always present all of them. This means that if we just stop updating one of the 3 it will keep its latest update and potentially be available with that old value when we don’t want it to be available at all (because we’ve dropped it from our template).
  
  Best way to handle this is to have a place to keep all shipping services that Autofixa provides. These services should be created as part of the setup for the Storesome Account. Then we have to track what is created as shipment methods in the “Hemisphere Shipping Template” that is applied to the product and map the Shipping Template > Shipping Method > Shipping Service field with “Name” from the Storesome Shipping Services that we’ve created as available. For every method that we map we should pass “true” for the isActive filed in the product payload to Autofixa. For every “Storesome Shipping Service” that we can’t map (is not present in the Shipping Methods of the template) we should send “false”.
  
  As already suggested this setup should happen via a new table under Account Storesome (Account Storesome Shipping Service) that will hold the necessary information (as multi records) for each Storesome service. The table should hold the Names of the Services, their type (an enumeration value field to ensure the 3 services of Autofixa are prioritised the right way one over the other) and the id of the shipping service
- Fields specifications - Due to the need of almost all fields to be provided always (including Stock and Price at the same time) we should be prepared for some exceptions - If we have protect_price = 1 then we can send an offer update but we should take the price from the Last Price Sent field AND we should trigger an offer update ONLY via the “update_quantity” flag. If we have protect_quantity = 1 we don’t want to risk messing up the qty calculations on the Marketplace so we are to block the whole flow
Limits - 1 by 1 per call
Error reporting - nothing specific but to make sure we store the right error against the right line
When successful we want to update accordingly the listingStatus (to active if the update was with positive qty OR to inactive if the update was with 0 qty)
As always update_quantity and update_price should reflect the correct status of the communication
- sent - if we are working with this at the moment
- normal - if we’ve successfully completed the operation
- error - if there has been a problem (to include the message in the respective error fields as well) Both fields are to act together and as per our standards not overlap any pending values that should trigger a consecutive update (please refer to the respective stock and price abstraction explanations and flag systematisation)Stock Update general requirements Price Update General requirements

Is this article helpful?

0 0 0