Amazon Reports

The purpose of this document is to give good understanding how Amazon Settlement reports will be incorporated within Hemi.

Summary of Changes: (The purpose of this table is to keep traceability and Product team to highlight the things that were changed into the scope, based on comments or discussions)

In order to incorporate the Amazon Reports in Hemi we will need two new tables.

Report Amazon Template

<v1.2> The FTP Credential > Type will be used only for the enumerations while In order to drop the relevant report into the correct folder we want to use the FTP Paths. Each FTP Path should have FTP Path > Label named the same way as the report type this way we connect which report to which folder to be dropped. </v1.2>

Report Amazon (slave table of Report Amazon Template)

Once we have set the whole report template we can start requesting the Settlement reports. However there we are not able to directly request a new report because they are periodically generated from Amazon we need to use Get Reports, in order to store the actual report in Report Amazon table.

Get Reports

API Call: GET /reports/2021-06-30/reports

Docs: https://developer-docs.amazon.com/sp-api/docs/reports-api-v2021-06-30-reference#getreports

Parameters:

Min count : 1 Max count : 10 | Report Amazon Template > Report Type | The report type from Report Amazon Template > Report Type | | processingStatuses**optional | A list of processing statuses used to filter reports. Min count : 1 | “DONE“ | We want to get only reports with status “DONE“ | | marketplaceIdsoptional | A list of marketplace identifiers used to filter reports. The reports returned will match at least one of the marketplaces that you specify. Min count : 1 Max count : 10 | Report Amazon Template > Account | We map the correct marketplace id based on Report Amazon Template > Account | | createdSince**optional | The earliest report creation date and time for reports to include in the response, in ISO 8601 date time format. The default is 90 days ago. Reports are retained for a maximum of 90 days. | Report Amazon Template > Time Period

Report Amazon Template > Start Date | Based on the Report Amazon Template > Search Type we can have two cases: Time Period - for the period we specify the hours so we will get all the reports from now until the specified period Start and End Date - we specify the exact period | | **createdUntil**optional | The latest report creation date and time for reports to include in the response, in ISO 8601 date time format. The default is now. | Report Amazon Template > Time Period Report Amazon Template > End Date | Based on the Report Amazon Template > Search Type we can have two cases: Time Period - for the period we specify the hours so we will get all the reports from now until the specified period Start and End Date - we specify the exact period |

Example request:

There is no body

Request Mapping: The mapping happens directly in the parameters

Example Response

{
    "reportType": "GET_VAT_TRANSACTION_DATA",
    "processingEndTime": "2022-07-05T21:43:32+00:00",
    "processingStatus": "DONE",
    "marketplaceIds": [
        "A1F83G8C2ARO7P"
    ],
    "reportDocumentId": "amzn1.spdoc.1.3.3470cc0f-2488-40e8-b967-a88ac3ba1c65.T2K8J5HL6DFMK8.3001",
    "reportId": "1809470019178",
    "dataEndTime": "2022-07-05T21:42:07+00:00",
    "createdTime": "2022-07-05T21:43:15+00:00",
    "processingStartTime": "2022-07-05T21:43:21+00:00",
    "dataStartTime": "2022-04-05T21:42:07+00:00"
}

Response Mapping:

DONE -The report has completed processing. FATAL - The report was aborted due to a fatal error. IN_PROGRESS-The report is being processed. IN_QUEUE -The report has not yet started processing. It may be waiting for another IN_PROGRESS report.

Please note we will receive only reports with status “Done“ | | marketplaceIds | | | | | reportDocumentId | | N/A | This field is returned only when the feed is with status “DONE“ and need to be used in the Get Report Document right after we get the report | | reportId | | Report Amazon > External ID | | | dataEndTime | | Report Amazon > Start Date | The date when we submit the feed. Human readable format | | createdTime | | Report Amazon > End Date | The date when we submit the feed. Human readable format | | processingStartTime | | N/A | | | dataStartTime | | N/A | | | | | Report Amazon > Error | If any errors are returned we store them here | | | | Report Amazon > File | Once we successfully get the reportDocumentId we use it to get the document and store the url to the report here |

Get Report Document

In order to download the actual reports (files) we need to get the reportDocumentId and this is requested right after we receive Report with “DONE“ status after Get Reports request.

API Call: GET /reports/2021-06-30/documents/{reportDocumentId}

Docs: https://developer-docs.amazon.com/sp-api/docs/reports-api-v2021-06-30-reference#getreportdocument

Example request:

There is no body

Request Mapping: From the response of Get Reports request we use the reportDocumentId which wont be stored in ****Hemi and will be get directly for them response. However if we receive and error during this step we need to store the error in Report Amazon > Error

Example Response

{
    "reportDocumentId": "amzn1.spdoc.1.3.3470cc0f-2488-40e8-b967-a88ac3ba1c65.T2K8J5HL6DFMK8.3001",
    "url": "https://tortuga-prod-eu.s3-eu-west-1.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.d410e367-253b-4e30-8136-a846dbc76c11.T15N6OVVH99IH6?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220705T214345Z&X-Amz-SignedHeaders=host&X-Amz-Expires=300&X-Amz-Credential=AKIAX2ZVOZFBG22SVBUH%2F20220705%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=418803a71a324e16006afef1a3fb56b0dcc993b8539bc8d4aba842c14a81b272"
}

The URL contains the actual report file which we need to decompress if not a .csv and store them on the FTP which is set in Report Amazon Template > FTP Please note we first store the files locally on the machine in “.temp” folder and them we move them to the specified FTP. If any error occur during the file transfer we store it in Amazon Report > Error. If there is already an error in Amazon Report > Error we replace the error with the latest one.

The actual Compression Algorithm used is GZIP!