uMarketplace Vendor API Add-on

The Vendor API add-on extends Magento Soap API and allow vendors to utilize it to pull/update Purchase Orders information and update inventory data. To get more technical details check:
- app\code\community\Unirgy\DropshipApi\etc\wsdl.xml/ - API wsdl definition
- app\code\community\Unirgy\DropshipApi\etc\acl.xml/ - API acl definition

In order to perform API operations vendor need authentication. The system authenticates the vendor by their email/apiKey. Before performing an actual API calls, vendor need to get authentication token by login soap call with username, api key parameters. Response of that POST will be 32 bit token that need to be used for further API calls. When in SessionId, request parameter to prove vendor identity. More information is avaialble here http://devdocs.magento.com/guides/m1x/api/soap/introduction.html

Example:
POST /index.php/api/v2_soap/index/ HTTP/1.1
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”><SOAP-ENV:Body><ns1:login><username xsi:type=“xsd:string”>xxx</username><apiKey xsi:type=“xsd:string”>xxxx</apiKey></ns1:login></SOAP-ENV:Body></SOAP-ENV:Envelope>

RESPONSE
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”> <SOAP-ENV:Body> <ns1:loginResponse> <loginReturn xsi:type=“xsd:string”>2dc6db6698fd2bac2f8e478238cafe74</loginReturn> </ns1:loginResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

In order to get list of Purchase Orders, salesOrderUdpoList API call will have to be performed. It expect filter or complex_filter as parameter. More details on how to construct such filter check http://devdocs.magento.com/guides/m1x/api/soap/sales/salesOrderShipment/sales_order_shipment.list.html

Example:
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”><SOAP-ENV:Body><ns1:salesOrderUdpoList><sessionId xsi:type=“xsd:string”>2dc6db6698fd2bac2f8e478238cafe74</sessionId><filters xsi:type=“ns1:filters”><complex_filter SOAP-ENC:arrayType=“ns1:complexFilter[1]” xsi:type=“ns1:complexFilterArray”><item xsi:type=“ns1:complexFilter”><key xsi:type=“xsd:string”>created_at</key><value xsi:type=“ns1:associativeEntity”><key xsi:type=“xsd:string”>gt</key><value xsi:type=“xsd:string”>2018-02-01</value></value></item></complex_filter></filters></ns1:salesOrderUdpoList></SOAP-ENV:Body></SOAP-ENV:Envelope>

RESPONSE
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”> <SOAP-ENV:Body> <ns1:salesOrderUdpoListResponse> <result SOAP-ENC:arrayType=“ns1:salesOrderUdpoEntity[3]” xsi:type=“ns1:salesOrderUdpoEntityArray”> <item xsi:type=“ns1:salesOrderUdpoEntity”> <increment_id xsi:type=“xsd:string”>145000016-1</increment_id> <created_at xsi:type=“xsd:string”>2018-02-01 17:24:50</created_at> <total_qty xsi:type=“xsd:string”>3.0000</total_qty> </item> <item xsi:type=“ns1:salesOrderUdpoEntity”> <increment_id xsi:type=“xsd:string”>145000017-1</increment_id> <created_at xsi:type=“xsd:string”>2018-02-01 17:28:24</created_at> <total_qty xsi:type=“xsd:string”>3.0000</total_qty> </item> <item xsi:type=“ns1:salesOrderUdpoEntity”> <increment_id xsi:type=“xsd:string”>145000018-1</increment_id> <created_at xsi:type=“xsd:string”>2018-02-01 17:29:44</created_at> <total_qty xsi:type=“xsd:string”>3.0000</total_qty> </item> </result> </ns1:salesOrderUdpoListResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

In order to get single Purchase Order information, salesOrderUdpoInfo API call will have to be performed. Parameter could be either Purchase Order entity id or it's increment id.

Example:
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”><SOAP-ENV:Body><ns1:salesOrderUdpoInfo><sessionId xsi:type=“xsd:string”>2dc6db6698fd2bac2f8e478238cafe74</sessionId><udpoIncrementId xsi:type=“xsd:string”>145000018-1</udpoIncrementId></ns1:salesOrderUdpoInfo></SOAP-ENV:Body></SOAP-ENV:Envelope>\
RESPONSE
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”> <SOAP-ENV:Body> <ns1:salesOrderUdpoInfoResponse> <result xsi:type=“ns1:salesOrderUdpoEntity”> <increment_id xsi:type=“xsd:string”>145000018-1</increment_id> <store_id xsi:type=“xsd:string”>1</store_id> <created_at xsi:type=“xsd:string”>2018-02-01 17:29:44</created_at> <updated_at xsi:type=“xsd:string”>2018-02-01 17:29:44</updated_at> <order_id xsi:type=“xsd:string”>207</order_id> <total_qty xsi:type=“xsd:string”>3.0000</total_qty> <po_id xsi:type=“xsd:string”>9</po_id> <items SOAP-ENC:arrayType=“ns1:salesOrderUdpoItemEntity[1]” xsi:type=“ns1:salesOrderUdpoItemEntityArray”> <item xsi:type=“ns1:salesOrderUdpoItemEntity”> <parent_id xsi:type=“xsd:string”>9</parent_id> <sku xsi:type=“xsd:string”>ugiftcert</sku> <name xsi:type=“xsd:string”>ugiftcert</name> <order_item_id xsi:type=“xsd:string”>626</order_item_id> <product_id xsi:type=“xsd:string”>1106</product_id> <weight xsi:type=“xsd:string”>1.0000</weight> <price xsi:type=“xsd:string”>10.0000</price> <qty xsi:type=“xsd:string”>3.0000</qty> <item_id xsi:type=“xsd:string”>23</item_id> </item> </items> <tracks SOAP-ENC:arrayType=“ns1:salesOrderUdpoTrackEntity[0]” xsi:type=“ns1:salesOrderUdpoTrackEntityArray”/> <comments SOAP-ENC:arrayType=“ns1:salesOrderUdpoCommentEntity[0]” xsi:type=“ns1:salesOrderUdpoCommentEntityArray”/> </result> </ns1:salesOrderUdpoInfoResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

In order to add comment to Purchase Order, perform salesOrderUdpoAddComment API call. Parameters are udpoIncrementId - Purchase Order increment id, - comment string parameter.

Example:
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”><SOAP-ENV:Body><ns1:salesOrderUdpoAddComment><sessionId xsi:type=“xsd:string”>3e60ad92322db9005c7ea21cd11966d7</sessionId><udpoIncrementId xsi:type=“xsd:string”>145000018-1</udpoIncrementId><comment xsi:type=“xsd:string”>test api comment</comment><email xsi:nil=“true”/><includeInEmail xsi:nil=“true”/></ns1:salesOrderUdpoAddComment></SOAP-ENV:Body></SOAP-ENV:Envelope>

RESPONSE <?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”> <SOAP-ENV:Body> <ns1:salesOrderUdpoAddCommentResponse> <udpoIncrementId xsi:type=“xsd:boolean”>true</udpoIncrementId> </ns1:salesOrderUdpoAddCommentResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

In order to add tracking number to Purchase Order perform salesOrderUdpoAddTrack API call. Parameters are udpoIncrementId - Purchase Order increment id, carrier string parameter, carrier title in title parameter and tracking number in trackNumber parameter. It return bool true on success and may rise exception if PO not found or does not belong to vendor.

Example:
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”><SOAP-ENV:Body><ns1:salesOrderUdpoAddTrack><sessionId xsi:type=“xsd:string”>a81bf7681b46f0e4bc8322ed12a090a1</sessionId><udpoIncrementId xsi:type=“xsd:string”>145000015-1</udpoIncrementId><carrier xsi:type=“xsd:string”>ups</carrier><title xsi:type=“xsd:string”>ups</title><trackNumber xsi:type=“xsd:string”>track100000202-2-ext1</trackNumber></ns1:salesOrderUdpoAddTrack></SOAP-ENV:Body></SOAP-ENV:Envelope>

RESPONSE
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”> <SOAP-ENV:Body> <ns1:salesOrderUdpoAddTrackResponse> <result xsi:type=“xsd:int”>1</result> </ns1:salesOrderUdpoAddTrackResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

In order to delete tracking number from Purchase Order perform salesOrderUdpoRemoveTrack API call. Parameters are udpoIncrementId - Purchase Order increment id and tracking number in trackNumber parameter. It return bool true on success and may rise exception if PO not found or does not belong to vendor.

Example:
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”><SOAP-ENV:Body><ns1:salesOrderUdpoRemoveTrack><sessionId xsi:type=“xsd:string”>1c3f163fc457ed4b975a5081a3e2158e</sessionId><udpoIncrementId xsi:type=“xsd:string”>145000015-1</udpoIncrementId><trackId xsi:type=“xsd:string”>track100000202-2-ext1</trackId></ns1:salesOrderUdpoRemoveTrack></SOAP-ENV:Body></SOAP-ENV:Envelope>

RESPONSE <?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”> <SOAP-ENV:Body> <ns1:salesOrderUdpoRemoveTrackResponse> <result xsi:type=“xsd:boolean”>true</result> </ns1:salesOrderUdpoRemoveTrackResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>

Vendors can use salesUdstockUpdate API calls to update ther products inventory (products offers when multivendor add-on used). Request payload expect items parameter which should be array of arrays (later one contain single offer data details). Each offer detail can have following parameters:

• sku
• priority
• carrier_code
• vendor_sku
• vendor_cost
• stock_qty
• stock_qty_add
• backorders
• status
• shipping_price
• vendor_title
• state
• state_descr
• freeshipping
• vendor_price
• special_price
• specialFromDate
• specialToDate

But only sku or vendor_sku are required. When Multivendor add-on is not used, it's possible to use only this keys in offer details array sku, vendor_sku, stock_qty, stock_qty_add

Response of API call will contain string information of how many items were updated and errors list at the end if any.

Example:
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”><SOAP-ENV:Body><ns1:salesUdstockUpdate><sessionId xsi:type=“xsd:string”>a3d459b6dff11cd103096df1d96fc8a1</sessionId><udstock SOAP-ENC:arrayType=“ns1:salesUdstockEntity[4]” xsi:type=“ns1:salesUdstockEntityArray”><item xsi:type=“ns1:salesUdstockEntity”><sku xsi:type=“xsd:string”>ace000</sku><vendor_sku xsi:type=“xsd:string”>v2-ace000</vendor_sku><stock_qty xsi:type=“xsd:string”>11</stock_qty></item><item xsi:type=“ns1:salesUdstockEntity”><vendor_sku xsi:type=“xsd:string”>v2-ace001</vendor_sku><stock_qty xsi:type=“xsd:string”>22</stock_qty></item><item xsi:type=“ns1:salesUdstockEntity”><vendor_sku xsi:type=“xsd:string”>not-existing-vendor-sku</vendor_sku><stock_qty xsi:type=“xsd:string”>22</stock_qty></item><item xsi:type=“ns1:salesUdstockEntity”><sku xsi:type=“xsd:string”>not-existing-sku</sku><vendor_sku xsi:type=“xsd:string”>not-existing-vendor-sku</vendor_sku><stock_qty xsi:type=“xsd:string”>22</stock_qty></item></udstock></ns1:salesUdstockUpdate></SOAP-ENV:Body></SOAP-ENV:Envelope>

RESPONSE
<?xml version=“1.0” encoding=“UTF-8”?> <SOAP-ENV:Envelope xmlns:SOAP-ENV=“http://schemas.xmlsoap.org/soap/envelope/” xmlns:ns1=“urn:Magento” xmlns:xsd=“http://www.w3.org/2001/XMLSchema” xmlns:xsi=“http://www.w3.org/2001/XMLSchema-instance” xmlns:SOAP-ENC=“http://schemas.xmlsoap.org/soap/encoding/” SOAP-ENV:encodingStyle=“http://schemas.xmlsoap.org/soap/encoding/”> <SOAP-ENV:Body> <ns1:salesUdstockUpdateResponse> <result xsi:type=“xsd:string”>Updated 1 items of 4: (Product not found for vendor sku “v2-ace001”, Product not found for vendor sku “not-existing-vendor-sku”, Product not found for sku “not-existing-sku”)</result> </ns1:salesUdstockUpdateResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>