Підключення до 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.

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

• "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 і т.д. В даному випадку ми будемо використовувати OrdersAPI, доступний за посиланням 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 (мал. 1). Для реалізації пагінації використовується не окремий 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 Gb, 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.