Подключению к API Amazon (MWS)

В данной статье мы предлагаем рассмотреть особенности подключения к API сервиса Amazon Marketplace Web Service (MWS). Для ознакомления рассмотрим процесс получения списка заказов.

Начало работы с MWS

Формат получаемых данных в MWS отличается от JSON и XML и представляет собой уникальный формат, где вложения осуществляются с помощью разделителя ".". Например, если в JSON нужно передать ключ "b" со значением "c", вложенный в ключ "a" - {"a": { "b": "c"}}, то в MWS это будет выглядеть как "a.b" со значением "c". Формат получаемых данных в MWS - XML.

Подпись запроса формируется с использованием нескольких параметров:

• AWSAccessKeyId" - предоставляется Amazon;
• "SellerId" - 14-значный уникальный идентификатор продавца Amazon, состоящий из букв и цифр;
• "MWSAuthToken" - токен доверенного разработчика, который будет описан далее;
• "SignatureVersion" - версия метода получения сигнатуры, например, "2";
• "Timestamp" - дата и время отправки запроса в формате "ISO 8601";
• "Version" - версия конкретной ветки API в формате "YYYY-MM-DD";
• "SignatureMethod" - метод получения сигнатуры, например, "HmacSHA256".

Относительно "SellerId" и "MWSAuthToken", здесь нужно учитывать специфику Amazon в отношении предоставления девелоперам доступа к аккаунтам продавцов. Сначала аккаунт необходимо перевести в режим разработчика. После этого другие продавцы смогут предоставить новому программисту доступ для управления их данными через API. В личном кабинете продавца есть список доверенных кодеров, каждому из которых присваивается специальный ключ "MWSAuthToken". Этот ключ необходимо предоставить девелоперу для использования его в подписи API-запросов вместе с "SellerId". Поскольку продавцу, который стал разработчиком, не нужно предоставлять доступ самому себе, то при осуществлении запросов от себя, необходимо указывать ключ "MWSAuthToken" со значением "".

Amazon не предоставляет sandbox-режима, поэтому вся работа с подключением к API будет проводиться на реальных данных. Настройку подписи запросов можно выполнить для GET-запросов, но при попытке чего-то более сложного может возникнуть риск поломки. Для отправки запросов необходимо использовать URL https://mws.amazonaws.com/ .

Получение заказов из Amazon с помощью API

После успешной настройки подписи для запросов, через API можно получать определенные данные из личного кабинета, например, список заказов. Вся функциональность API разделена на ветки в зависимости от объектов, с которыми проводится работа: Orders, Products, Fulfillment Inbound Shipments, Fulfillment Outbound Shipments, Feeds и т.д. В данном случае мы будем использовать Orders API, доступный по ссылке http://docs.developer.amazonservices.com/en_US/orders-2013-09-01/Orders_Overview.html .

Для получения списка заказов необходимо сделать GET-запрос по адресу https://mws.amazonaws.com/Orders/2013-09-01 с параметром "Action" и значением "ListOrders". Параметр "Action" используется как для GET-, так и для POST-запросов и четко определяет функциональность API. Дополнительно к "ListOrders" можно указать фильтры для уточнения результатов, но базовый запрос можно сделать без них. При успешной настройке подписи для запроса, указанный URL вернет XML с такой структурой: ListOrdersResponse (корневой элемент), ListOrdersResult (элемент первого уровня) и Orders (элемент второго уровня), который содержит список элементов Order. Каждый элемент Order представляет собой XML-представление заказа в Amazon. Для реализации пагинации используется не отдельный query-параметр, а значение параметра "Action" - "ListOrdersByNextToken". Так, если запрос "ListOrders" вернул элемент второго уровня "NextToken", это означает, что продавец имеет более 100 заказов, и необходимо сделать еще как минимум один запрос с параметрами "Action" - "ListOrdersByNextToken" и "NextToken" со значением, полученным из предыдущего запроса. Дальнейшие страницы пагинации можно получить с помощью "ListOrdersByNextToken".

Рис. 1

Каждый заказ имеет ряд строковых свойств, таких как AmazonOrderId, PurchaseDate, OrderStatus, а также вложенные объекты ShippingAddress, OrderTotal и другие. Информация о заказах не совсем подходит для прямого использования на сайте, поэтому для получения полной информации также необходимо получить связанные продукты. Для получения данных о них, сначала нужно сделать запрос с параметром "Action" и значением "GetOrder", передав также параметр "AmazonOrderId" со значением, полученным из ответа на запрос "ListOrders" или "ListOrdersByNextToken". Ответ на этот запрос будет содержать список продуктов, идентифицированных значением поля ASIN (рис.2).

Рис. 2

Для получения дополнительной информации о самих продуктах, необходимо обратиться к другой ветке API - Products API, по адресу https://mws.amazonaws.com/Products/2011-10-01 . В запросе к этой ветке указываются следующие параметры: "Action" - "GetMatchingProduct", "ASINList.ASIN.1" - здесь передается ASIN желаемого продукта. Запрос может содержать до 10 ASIN продуктов, передавая их как значения параметров "ASINList.ASIN.2", "ASINList.ASIN.3", ..., "ASINList.ASIN.10". Для этой ветки подпись запроса будет использовать значение "2011-10-01" для параметра "Version". Структура ответа может быть найдена на рис. 3.

Рис. 3

Во всем остальном необходимо реализовать обработку ошибок и интеграцию с бизнес-логикой. Кроме того, для каждого "Action" Amazon устанавливает собственные лимиты по количеству и частоте запросов, которые нужно учитывать отдельно в случае необходимости. Также, в некоторых запросах можно передавать параметр "MarketplaceId", который определяет регион. Например, для США и Бразилии используется домен https://mws.amazonservices.com . Значение параметра "MarketplaceId" для США равно "ATVPDKIKX0DER", а для Бразилии - "A2Q3Y263D00KWC".

Для ознакомления со всем списком смотрите http://docs.developer.amazonservices.com/en_US/dev_guide/DG_Endpoints.html .

Передача данных на примере присвоения трек-номера к заказу

Для передачи данных используется Feeds API. Все запросы этой категории требуют еще одной дополнительной подписи. Этот подпись базируется на содержимом файла фида, который необходимо передать в теле POST-запроса. Давайте предположим, что в Amazon есть заказ с идентификатором "A", за которым закреплен продукт с идентификатором связи "B" в количестве одной штуки, и мы хотим указать для этого заказа трек-номер "C" для службы доставки "D" методом "E".

В этом случае наш файл будет иметь следующий вид:

<?xml version="1.0" encoding="iso-8859-1"?> <AmazonEnvelope xsi:noNamespaceSchemaLocation="amzn-envelope.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instancet\"> <Header> <DocumentVersion>1.01</DocumentVersion> <MerchantIdentifier>{{ SellerId }}</MerchantIdentifier> </Header> <MessageType>OrderFulfillment</MessageType> <Message> <MessageID>1</MessageID> <OrderFulfillment> <AmazonOrderID>{{ A }}</AmazonOrderID> <FulfillmentDate>{{ FulfillmentDate }}</FulfillmentDate> <FulfillmentData> <CarrierName>{{ D }}</CarrierName> <ShippingMethod>{{ E }}</ShippingMethod> <ShipperTrackingNumber>{{ C }}</ShipperTrackingNumber> </FulfillmentData> <Item> <AmazonOrderItemCode>{{ B }}</AmazonOrderItemCode> <Quantity>1</Quantity> </Item> </OrderFulfillment> </Message> </AmazonEnvelope>

Помимо вышеуказанных параметров, мы также можем видеть SellerId и FulfillmentDate. SellerId - это уникальный идентификатор Amazon, о котором уже обсуждалось ранее, а FulfillmentDate - это дата отгрузки в формате ISO 8601. Подписью к файлу фида будет служить значение заголовка Content-MD5. Это значение представляет собой base64 закодированную строку, которая получается после выполнения кодирования md5 содержимого файла. Параметры D и E могут, например, иметь значения USPS и USPS First Class соответственно.

Тело запроса уже занято файлом, поэтому, хотя запрос передается методом POST, параметры Action со значением SubmitFeed и FeedType со значением POST_ORDER_FULFILLMENT_DATA нужно передавать как параметры строки запроса (query string). Для правильной передачи файла используйте заголовок Content-Type со значением text/xml.

Поскольку файл может быть очень большим, до 2 Гб, Amazon не предоставляет результат обработки файла в ответе, но возвращает Id зарегистрированного фида.

Таким образом, для примера, будет возвращен ответ следующего формата:

<?xml version="1.0"?> <SubmitFeedResponse xmlns="http://mws.amazonaws.com/doc/2009-01-01/"> <SubmitFeedResult> <FeedSubmissionInfo> <FeedSubmissionId>{{ FeedSubmissionId }}</FeedSubmissionId> <FeedType>_POST_ORDER_FULFILLMENT_DATA_</FeedType> <SubmittedDate>{{ SubmittedDate }}</SubmittedDate> <FeedProcessingStatus>_SUBMITTED_</FeedProcessingStatus> </FeedSubmissionInfo> </SubmitFeedResult> <ResponseMetadata> <RequestId>{{ RequestId }}</RequestId> </ResponseMetadata> </SubmitFeedResponse>

FeedSubmissionId - это идентификатор фида, с помощью которого позже можно проверить результат обработки файла. SubmittedDate - время регистрации фида. RequestId - это идентификатор запроса, присущий каждому ответу от Amazon. Затем, со временем, и если файл небольшой, мы можем выполнить GET-запрос с параметрами Action со значением GetFeedSubmissionResult и FeedSubmissionId со значением ранее сохраненного FeedSubmissionId для проверки статуса фида.

Другие загрузки фидов происходят аналогично и требуют знания Id различных сущностей в базе данных Amazon, таких, как A и B, которые вы можете получить в личном кабинете или с помощью API.