В данной статье мы предлагаем рассмотреть особенности подключения к 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".
В этом случае наш файл будет иметь следующий вид:
<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 зарегистрированного фида.
Таким образом, для примера, будет возвращен ответ следующего формата:
<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.
Статьи, которые могут вас также заинтересовать
Готовы Начать? Дайте нам знать!
Poland, Warsaw, 00-842
Łucka street 15/204
Пн-Пт 9.00 - 19.00