Next revision
|
Previous revision
|
udropship:umarketplace:vendor-api [2018/03/19 10:04] wtsergo created |
udropship:umarketplace:vendor-api [2018/03/23 21:29] renata |
===== Introduction ===== | ===== Introduction ===== |
| |
This add-on extend magento Soap API and allow vendors utilize it to pull/update Purchase Orders information and update inventory data. | 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: | To get more technical details check:\\ |
- //app\code\community\Unirgy\DropshipApi\etc\wsdl.xml/ - API wsdl definition | - //app\code\community\Unirgy\DropshipApi\etc\wsdl.xml/ - API wsdl definition\\ |
- //app\code\community\Unirgy\DropshipApi\etc\acl.xml/ - API acl definition | - //app\code\community\Unirgy\DropshipApi\etc\acl.xml/ - API acl definition |
| |
===== Authentication ===== | ===== Authentication ===== |
| |
In order to perform API operations vendor need authentication. System use authentication by vendor email/apiKey. Before doing actual API calls vendor need to get authentication token by doing **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 in sessionId request parameter to prove vendor identity. More information you can get here [[http://devdocs.magento.com/guides/m1x/api/soap/introduction.html]] | 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]] |
| |
'' | '' |
===== Get list of Vendor Purchase Orders (possible to filter) ===== | ===== Get list of Vendor Purchase Orders (possible to filter) ===== |
| |
In order to get list of Purchase Orders need to perform salesOrderUdpoList API call. 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]] | 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]] |
| |
'' | '' |
<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>\\ | <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 | RESPONSE\\ |
<?xml version="1.0" encoding="UTF-8"?> | <?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: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/"> |
===== Get Single Purchase Order Info ===== | ===== Get Single Purchase Order Info ===== |
| |
In order to get list of single Purchase Order information need to perform ///V1/udpo/:id// GET API call. :id parameter could be either Purchase Order entity id or it's increment id. | 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. |
| |
'' | '' |
</SOAP-ENV:Envelope> | </SOAP-ENV:Envelope> |
'' | '' |
| |
| |
===== Get Purchase Order Comments List ===== | |
| |
In order to get list of Purchase Order comments need to perform ///V1/udpo/:id/comments// GET API call. :id parameter could be either Purchase Order entity id or it's increment id. | |
| |
'' | |
Example:\\ | |
GET http://magento222.loc/index.php/rest/V1/udpo/000000012-1/comments\\ | |
\\ | |
RESPONSE\\ | |
{"items":[{"is_customer_notified":null,"parent_id":1,"comment":"[vendor1 changed PO status from 'Pending' to 'Ready to Ship']","is_visible_on_front":null,"created_at":"2018-03-02 18:34:08","entity_id":1},{"is_customer_notified":null,"parent_id":1,"comment":"vendor1: Test API Comment","is_visible_on_front":null,"created_at":"2018-03-12 09:05:16","entity_id":2},{"is_customer_notified":null,"parent_id":1,"comment":"[vendor1 changed PO status from 'Ready to Ship' to 'Acknowledged']","is_visible_on_front":null,"created_at":"2018-03-12 09:05:41","entity_id":3},{"is_customer_notified":null,"parent_id":1,"comment":"vendor1: Test API Comment with status change","is_visible_on_front":null,"created_at":"2018-03-12 09:05:41","entity_id":4}],"search_criteria":{"filter_groups":[{"filters":[{"field":"parent_id","value":"1","condition_type":"eq"}]}]},"total_count":4} | |
'' | |
| |
| |
===== Add comment to Purchase Order ===== | ===== Add comment to Purchase Order ===== |
| |
In order to add comment to Purchase Order perform ///V1/udpo/:id/addComment// POST API call. :id parameter could be either Purchase Order entity id or it's increment id. Request payload expect ''comment'' string parameter and optional ''status'' parameter. For possible values check //app\code\Unirgy\DropshipPo\Model\Source.php// **UDPO_STATUS_*** string constants. It return bool true on success and may rise exception if PO not found or does not belong to vendor. | In order to add comment to Purchase Order, perform **salesOrderUdpoAddComment** API call. Parameters are ''udpoIncrementId'' - Purchase Order increment id, ''- comment'' string parameter. |
| |
'' | '' |
Example:\\ | Example:\\ |
POST http://magento222.loc/index.php/rest/V1/udpo/000000012-1/addComment\\ | <?xml version="1.0" encoding="UTF-8"?> |
{"comment":"Test API Comment","status":9}\\ | <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 | RESPONSE |
true | <?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> |
'' | '' |
| |
===== Add tracking number to Purchase Order ===== | ===== Add tracking number to Purchase Order ===== |
| |
In order to add tracking number to Purchase Order perform ///V1/udpo/:id/addTrack// POST API call. :id parameter could be either Purchase Order entity id or it's increment id. Request payload expect carrier code in ''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. | 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:\\ | Example:\\ |
POST http://magento222.loc/index.php/rest/V1/udpo/000000012-1/addTrack\\ | <?xml version="1.0" encoding="UTF-8"?> |
{"carrier":"ups","title":"UPS","trackNumber":"UPS12345"}\\ | <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 | RESPONSE\\ |
true | <?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> |
'' | '' |
| |
===== Delete tracking number from Purchase Order ===== | ===== Delete tracking number from Purchase Order ===== |
| |
In order to delete tracking number from Purchase Order perform ///V1/udpo/:id/deleteTrack/:trackNumber// POST API call. **:id** parameter could be either Purchase Order entity id or it's increment id, **:trackNumber** should be tracking number. It return bool true on success and may rise exception if PO not found or does not belong to vendor and if tracking number not found within PO. | 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:\\ | Example:\\ |
POST http://magento222.loc/index.php/rest/V1/udpo/000000012-1/deleteTrack/UPS12345\\ | <?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 | RESPONSE |
true | <?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> |
'' | '' |
| |
===== Perform Inventory update ===== | ===== Perform Inventory update ===== |
| |
Vendor can use ///V1/udstock/update// POST API calls to update his 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: | 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 | * sku |
* priority | * priority |
* specialToDate | * specialToDate |
| |
But only **sku** or **vendor_sku** are required. When not using multivendor add-on it's possible to use only this keys in offer details array **sku**, **vendor_sku**, **stock_qty**, **stock_qty_add** | 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. | Response of API call will contain string information of how many items were updated and errors list at the end if any. |
'' | '' |
Example:\\ | Example:\\ |
POST http://magento222.loc/index.php/rest/V1/udstock/update/\\ | <?xml version="1.0" encoding="UTF-8"?> |
{"items":[{"sku":"24-MB01","vendor_sku":"v2-24-MB01","stock_qty":"11"},{"vendor_sku":"v2-24-MB04","stock_qty":"22"},{"vendor_sku":"not-existing-vendor-sku","stock_qty":"22"},{"sku":"not-existing-sku","vendor_sku":"not-existing-vendor-sku","stock_qty":"22"}]}\\ | <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\\ | RESPONSE\\ |
"Updated 2 items of 4: (Product not found for vendor sku \"not-existing-vendor-sku\", Product not found for sku \"not-existing-sku\")" | <?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> |
'' | '' |
| |