Amazon Smart Connect - API transmitters

The purpose of this page is to describe the needs and mappings for the transmitters needed for the Amazon Smart connect project

In their essence the transmitters shouldn’t do anything else but connect the right way to Amazon, use the right parameters from our APIs to the Amazon APIs and then simply relay the actual call (body of the messages should be transferred as received. The error messages should be handled as a body in our internal messaging as if we’ve received an error message from Amazon this will mean we’ve successfully relayed the actual call)

These APIs should use the Amazon authentication from the CMC project and in case of needs do a re-authentication before it proceeds with the actual Amazon call. It will be great if it also uses the standard Amazon limits tracker

The structure below will follow a description of each call that we need to send with the Hemi API endpoint we need to prepare followed by the Amazon endpoint we need to call and how to map the parameters. At the end there will be an explanation of the handling of the errors from Amazon

Here is the external facing document we can share for this as well and refer to it if needed for the calls needs from customers perspective

Hemi_AmazonSmartConnect_Labels_API_transition.docx

Create packages for the Shipment

Hemi API Endpoint: /amazonSmartConnect/shipments/createPackage/{shipmentId}

Hemi Operation: POST

Parameters received: {shipmentId}

Amazon API Endpoint: /externalFulfillment/shipments/2021-01-06/shipments/{shipmentId}/packages

Amazon Operation: POST

Parameters Mapping:

Additional Information: This call is expected to have a Body that we simply need to transmit as received to Amazon without any adjustments

Get the Shipping options

Hemi API Endpoint: /amazonSmartConnect/shipments/retrieveShippingOptions/ {shipmentId}/{packageId}

Hemi Operation: POST

Parameters received: {shipmentId} & {packageId}

Amazon API Endpoint: /externalFulfillment/shipments/2021-01-06/shippingOptions?shipmentId={shipmentId}&packageId={packageId}

Amazon Operation: GET

Parameters Mapping:

Generate the invoice for the Shipment

Hemi API Endpoint: /amazonSmartConnect/shipments/generateInvoice/{shipmentId}/{packageId}

Hemi Operation: POST

Parameters received: {shipmentId} & {packageId}

Amazon API Endpoint: /externalFulfillment/shipments/2021-01-06/shipments/{shipmentId}/packages/{packageId}/invoice

Amazon Operation: POST

Parameters Mapping:

Generate the shipLabel for the Shipment

Hemi API Endpoint: /amazonSmartConnect/shipments/generateShipLabel/{shipmentId}/{packageId}/{operation}

Hemi Operation: POST

Parameters received: {shipmentId} & {packageId} & {operation}

Amazon API Endpoint: externalFulfillment/shipments/2021-01-06/shipments/{shipmentId}/packages/{packageId}/shipLabel?operation={operation}

Amazon Operation: POST

Parameters Mapping:

Note: there is one more query parameter that can be used (shippingOptionId) but for the moment we don’t want to support it. Also there is an option for a Body for this call but we don’t expect this will be used ever for this project

Retrieve already existing shipLabel for the shipment

Hemi API Endpoint: /amazonSmartConnect/shipments/retrieveShipLabel/{shipmentId}/{packageId}

Hemi Operation: POST

Parameters received: {shipmentId} & {packageId}

Amazon API Endpoint: /externalFulfillment/shipments/2021-01-06/shipments/{shipmentId}/packages/{packageId}/shipLabel

Amazon Operation: GET

Parameters Mapping:

Error handling

As this is going to run through our own API we need to prepare the Amazon error handling slightly differently.

If our own API has a problem we should return the standard error codes with our own error messaging.

If our API successfully accepts the call though and successfully sends it to Amazon, no matter the response this means that our transmitter did its job.

If Amazon responds with a successful message we should simply send the body back as a response body to our call.

If Amazon responds with an error though we should put it in a specific message type so it is known on the other end that it was an error with the right status code and actual message.

This should have the following structure:

{
    "status": 400
    "amazonResponse":{
    }
}

Where status should be the code as received from Amazon and amazonResponse should be the body of the response as received from Amazon