Table of Contents

uMarketplace Vendor API Add-on

Introduction

The Vendor API add-on extends Magento 2 REST/Soap API and allow vendors utilize it to pull/update Purchase Orders information and update inventory data. To get more technical details check:

  1. app\code\Unirgy\DropshipApi\etc\webapi.xml - list of entry points for API calls
  2. app\code\Unirgy\DropshipApi\Api\Data - data type interfaces used in API
  3. app\code\Unirgy\DropshipApi\Api\InventoryManagementInterface.php - interface for possible inventory operations
  4. app\code\Unirgy\DropshipApi\Api\UdpoManagementInterface.php - interface for possible operations on Purchase Orders

Authentication

In order to perform API operations vendor need authentication. System use Token-based authentication by vendor email/password. Before doing actual API calls vendor need to get authentication token by doing post to /V1/integration/admin/token with json encoded array of username, password. Response of that POST will be 32 bit token that need to be used for further API calls in Authorization request header with the Bearer HTTP authorization scheme to prove vendor identity. More information is available here http://devdocs.magento.com/guides/v2.0/get-started/authentication/gs-authentication-token.html

Example:

POST  http://magento.loc/index.php/rest/V1/integration/admin/token
{"username":"<vendor email>","password":"<vendor password>"}

RESPONSE “xxxxxxxxx 32 bit token xxxxxxxxx”

Get list of Vendor Purchase Orders (possible to filter)

In order to get list of Purchase Orders perform /V1/udpos GET API call. It expect searchCriteria as parameter. More details on how to construct the filter check can be found here http://devdocs.magento.com/guides/v2.1/rest/performing-searches.html

Example:

GET http://magento.loc/index.php/rest/V1/udpos?searchCriteria[filter_groups][0][filters][0][field]=created_at&searchCriteria[filter_groups][0][filters][0][value]=2016-07-01+00:00:00&searchCriteria[filter_groups][0][filters][0][condition_type]=gt

RESPONSE

{
"items": [{
    "billing_address_id": 14,
    "created_at": "2018-03-02 18:33:51",
    "customer_id": 2,
    "email_sent": 0,
    "entity_id": 1,
    "increment_id": "000000012-1",
    "order_id": 12,
    "udropship_status": 9,
    "shipping_address_id": 13,
    "store_id": 1,
    "total_qty": 4,
    "total_weight": 0,
    "updated_at": "2018-03-12 09:05:41",
    "items": [{
        "entity_id": 1,
        "name": "Push It Messenger Bag",
        "parent_id": 1,
        "price": 56.81,
        "product_id": 14,
        "row_total": 170.43,
        "sku": "24-WB04",
        "order_item_id": 12,
        "qty": 3
    }, {
        "entity_id": 2,
        "name": "Fusion Backpack",
        "parent_id": 1,
        "price": 69.98,
        "product_id": 6,
        "row_total": 69.98,
        "sku": "24-MB02",
        "order_item_id": 13,
        "qty": 1
    }],
    "comments": [{
        "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
    }, {
        "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 'Pending' to 'Ready to Ship']",
        "is_visible_on_front": null,
        "created_at": "2018-03-02 18:34:08",
        "entity_id": 1
    }]
}, {
    "billing_address_id": 16,
    "created_at": "2018-03-12 08:47:24",
    "customer_id": 2,
    "email_sent": 0,
    "entity_id": 2,
    "increment_id": "000000013-1",
    "order_id": 13,
    "udropship_status": 0,
    "shipping_address_id": 15,
    "store_id": 1,
    "total_qty": 6,
    "total_weight": 4,
    "updated_at": "2018-03-12 08:47:24",
    "items": [{
        "entity_id": 3,
        "name": "Orestes Yoga Pant ",
        "parent_id": 2,
        "price": 82.74,
        "product_id": 859,
        "row_total": 82.74,
        "sku": "MP10-32-Blue",
        "weight": 1,
        "order_item_id": 14,
        "qty": 1
    }, {
        "entity_id": 4,
        "name": "Orestes Yoga Pant -32-Blue",
        "parent_id": 2,
        "price": 0,
        "product_id": 848,
        "sku": "MP10-32-Blue",
        "weight": 1,
        "order_item_id": 15,
        "qty": 1
    }, {
        "entity_id": 5,
        "name": "Helios Endurance Tank",
        "parent_id": 2,
        "price": 25.88,
        "product_id": 681,
        "row_total": 25.88,
        "sku": "MT04-S-Blue",
        "weight": 1,
        "order_item_id": 16,
        "qty": 1
    }, {
        "entity_id": 6,
        "name": "Helios Endurance Tank-S-Blue",
        "parent_id": 2,
        "price": 0,
        "product_id": 677,
        "sku": "MT04-S-Blue",
        "weight": 1,
        "order_item_id": 17,
        "qty": 1
    }, {
        "entity_id": 7,
        "name": "Inez Full Zip Jacket",
        "parent_id": 2,
        "price": 59.22,
        "product_id": 1305,
        "row_total": 59.22,
        "sku": "WJ07-M-Red",
        "weight": 1,
        "order_item_id": 18,
        "qty": 1
    }, {
        "entity_id": 8,
        "name": "Inez Full Zip Jacket-M-Red",
        "parent_id": 2,
        "price": 0,
        "product_id": 1298,
        "sku": "WJ07-M-Red",
        "weight": 1,
        "order_item_id": 19,
        "qty": 1
    }, {
        "entity_id": 9,
        "name": "Maxima Drawstring Short",
        "parent_id": 2,
        "price": 27.19,
        "product_id": 1940,
        "row_total": 27.19,
        "sku": "WSH02-29-Yellow",
        "weight": 1,
        "order_item_id": 20,
        "qty": 1
    }, {
        "entity_id": 10,
        "name": "Maxima Drawstring Short-29-Yellow",
        "parent_id": 2,
        "price": 0,
        "product_id": 1930,
        "sku": "WSH02-29-Yellow",
        "weight": 1,
        "order_item_id": 21,
        "qty": 1
    }, {
        "entity_id": 11,
        "name": "Savvy Shoulder Tote",
        "parent_id": 2,
        "price": 35.25,
        "product_id": 10,
        "row_total": 35.25,
        "sku": "24-WB05",
        "order_item_id": 22,
        "qty": 1
    }, {
        "entity_id": 12,
        "name": "Compete Track Tote",
        "parent_id": 2,
        "price": 39.5,
        "product_id": 9,
        "row_total": 39.5,
        "sku": "24-WB02",
        "order_item_id": 23,
        "qty": 1
    }],
    "comments": []
}, {
    "billing_address_id": 18,
    "created_at": "2018-03-12 08:47:25",
    "customer_id": 2,
    "email_sent": 0,
    "entity_id": 3,
    "increment_id": "000000014-1",
    "order_id": 14,
    "udropship_status": 0,
    "shipping_address_id": 17,
    "store_id": 1,
    "total_qty": 4,
    "total_weight": 0,
    "updated_at": "2018-03-12 08:47:25",
    "items": [{
        "entity_id": 13,
        "name": "Push It Messenger Bag",
        "parent_id": 3,
        "price": 56.81,
        "product_id": 14,
        "row_total": 56.81,
        "sku": "24-WB04",
        "order_item_id": 24,
        "qty": 1
    }, {
        "entity_id": 14,
        "name": "Overnight Duffle",
        "parent_id": 3,
        "price": 37.39,
        "product_id": 13,
        "row_total": 37.39,
        "sku": "24-WB07",
        "order_item_id": 25,
        "qty": 1
    }, {
        "entity_id": 15,
        "name": "Driven Backpack",
        "parent_id": 3,
        "price": 31.39,
        "product_id": 12,
        "row_total": 31.39,
        "sku": "24-WB03",
        "order_item_id": 26,
        "qty": 1
    }, {
        "entity_id": 16,
        "name": "Endeavor Daytrip Backpack",
        "parent_id": 3,
        "price": 29.11,
        "product_id": 11,
        "row_total": 29.11,
        "sku": "24-WB06",
        "order_item_id": 27,
        "qty": 1
    }],
    "comments": []
}, {
    "billing_address_id": 20,
    "created_at": "2018-03-12 08:47:29",
    "customer_id": 2,
    "email_sent": 0,
    "entity_id": 4,
    "increment_id": "000000015-1",
    "order_id": 15,
    "udropship_status": 0,
    "shipping_address_id": 19,
    "store_id": 1,
    "total_qty": 4,
    "total_weight": 0,
    "updated_at": "2018-03-12 08:47:29",
    "items": [{
        "entity_id": 17,
        "name": "Push It Messenger Bag",
        "parent_id": 4,
        "price": 56.81,
        "product_id": 14,
        "row_total": 56.81,
        "sku": "24-WB04",
        "order_item_id": 28,
        "qty": 1
    }, {
        "entity_id": 18,
        "name": "Overnight Duffle",
        "parent_id": 4,
        "price": 37.39,
        "product_id": 13,
        "row_total": 37.39,
        "sku": "24-WB07",
        "order_item_id": 29,
        "qty": 1
    }, {
        "entity_id": 19,
        "name": "Driven Backpack",
        "parent_id": 4,
        "price": 31.39,
        "product_id": 12,
        "row_total": 31.39,
        "sku": "24-WB03",
        "order_item_id": 30,
        "qty": 1
    }, {
        "entity_id": 20,
        "name": "Endeavor Daytrip Backpack",
        "parent_id": 4,
        "price": 29.11,
        "product_id": 11,
        "row_total": 29.11,
        "sku": "24-WB06",
        "order_item_id": 31,
        "qty": 1
    }],
    "comments": []
}], 
"search_criteria": {"filter_groups": []}, 
"total_count": 4
}

Get Single Purchase Order Info

In order to get single Purchase Order information perform /V1/udpo/:id GET API call. :id parameter could be either Purchase Order entity id or it's increment id.

Example:

GET  http://magento.loc/index.php/rest/V1/udpo/000000012-1

RESPONSE

{
    "billing_address_id": 14,
    "created_at": "2018-03-02 18:33:51",
    "customer_id": 2,
    "email_sent": 0,
    "entity_id": 1,
    "increment_id": "000000012-1",
    "order_id": 12,
    "udropship_status": 9,
    "shipping_address_id": 13,
    "store_id": 1,
    "total_qty": 4,
    "total_weight": 0,
    "updated_at": "2018-03-12 09:05:41",
    "items": [{
        "entity_id": 1,
        "name": "Push It Messenger Bag",
        "parent_id": 1,
        "price": 56.81,
        "product_id": 14,
        "row_total": 170.43,
        "sku": "24-WB04",
        "order_item_id": 12,
        "qty": 3
    }, {
        "entity_id": 2,
        "name": "Fusion Backpack",
        "parent_id": 1,
        "price": 69.98,
        "product_id": 6,
        "row_total": 69.98,
        "sku": "24-MB02",
        "order_item_id": 13,
        "qty": 1
    }],
    "comments": [{
        "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
    }, {
        "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 'Pending' to 'Ready to Ship']",
        "is_visible_on_front": null,
        "created_at": "2018-03-02 18:34:08",
        "entity_id": 1
    }]
}

Get Purchase Order Comments List

In order to get list of Purchase Order comments 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://magento.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

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.

Example:
POST http://magento.loc/index.php/rest/V1/udpo/000000012-1/addComment
{“comment”:“Test API Comment”,“status”:9}

RESPONSE true

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.

Example:
POST http://magento.loc/index.php/rest/V1/udpo/000000012-1/addTrack
{“carrier”:“ups”,“title”:“UPS”,“trackNumber”:“UPS12345”}

RESPONSE true

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.

Example:
POST http://magento.loc/index.php/rest/V1/udpo/000000012-1/deleteTrack/UPS12345
[]

RESPONSE true

Perform Inventory update

Vendors can use /V1/udstock/update POST API calls to update their products inventory (products offers, when Multivendor add-on is 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:

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

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

Example:

POST  http://magento.loc/index.php/rest/V1/udstock/update/
{
    "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"
        }
    ]
}

RESPONSE

"Updated 2 items of 4: (Product not found for vendor sku "not-existing-vendor-sku", Product not found for sku "not-existing-sku")"