====== uMarketplace uReturn (RMA) API Add-on ======
===== Introduction =====
The uReturn (RMA) API add-on extends Magento 2 REST/Soap API and allow admin and vendor utilize it to create/pull/update uReturns information.
To get more technical details check:
- //app\code\Unirgy\RmaApi\etc\webapi.xml// - list of entry points for API calls
- //app\code\Unirgy\RmaApi\Api\Data// - data type interfaces used in API
- //app\code\Unirgy\RmaApi\Api\RmaManagementInterface.php// - interface for possible RMA operations
===== 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":"","password":""}
''
RESPONSE
''
"xxxxxxxxx 32 bit token xxxxxxxxx"
===== Create RMA =====
Before call Create RMA API you need to get details of Purchase Order using one of these API calls:
- [[https://unirgy.com/wiki/udropship/umarketplace/m2/vendor-api#get_single_purchase_order_info]]
- [[https://unirgy.com/wiki/udropship/umarketplace/m2/vendor-api#get_list_of_vendor_purchase_orders_possible_to_filter]]
Once it's done and you have all required entity IDs you are ready to create RMA. Request payload expect ''data'' param to be json encoded array that match //\Unirgy\RmaApi\Api\Data\CreateRmaRequestInterface// interface. It's inner ''items'' param should be json encoded array that match //\Unirgy\RmaApi\Api\Data\CreateRmaItemInterface// interface.
''
Example:
''
POST http://magento.loc/rest//V1/urma/create
{
"data": {
"udpo_id": "86",
"comment_text": "rma api comment",
"send_email": "1",
"rma_reason": "refund",
"items": [
{
"udpo_item_id": "99",
"condition": "unopened",
"qty": "1"
}
]
}
}
''
RESPONSE
''
"000000011"
===== Get list of RMAs (possible to filter) =====
In order to get list of RMAs perform ///V1/urmas// 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/rest/V1/urmas?searchCriteria[filter_groups][0][filters][0][field]=created_at&searchCriteria[filter_groups][0][filters][0][value]=2022-01-01+00:00:00&searchCriteria[filter_groups][0][filters][0][condition_type]=gt
''
RESPONSE
''
{
"items": [
{
"billing_address_id": 94,
"created_at": "2022-01-18 02:58:23",
"customer_id": 1,
"email_sent": 1,
"entity_id": 4,
"increment_id": "000000004",
"order_id": 47,
"shipping_address_id": 93,
"store_id": 1,
"total_qty": 1,
"updated_at": "2022-01-18 02:58:23",
"items": [
{
"entity_id": 4,
"name": "test PA",
"parent_id": 4,
"price": 16.55,
"product_id": 4,
"sku": "test-pa",
"weight": 1,
"item_condition": "opened",
"order_item_id": 87,
"qty": 1
}
],
"comments": [
{
"is_customer_notified": 1,
"parent_id": 4,
"rma_status": "pending",
"comment": "initial api comment",
"is_visible_on_front": 1,
"created_at": "2022-01-18 02:58:23",
"entity_id": 9
}
],
"udpo_id": "76",
"udpo_increment_id": "000000060-2",
"rma_reason": "refund",
"rma_status": "pending",
"shipment_id": "45",
"shipment_increment_id": "000000060-2-0",
"udropship_vendor": "1",
"vendor_name": "vendor1"
},
{
"billing_address_id": 96,
"created_at": "2022-01-18 03:00:25",
"customer_id": 1,
"email_sent": 1,
"entity_id": 5,
"increment_id": "000000005",
"order_id": 48,
"shipping_address_id": 95,
"store_id": 1,
"total_qty": 2,
"updated_at": "2022-01-18 03:00:25",
"items": [
{
"entity_id": 5,
"name": "test PA",
"parent_id": 5,
"price": 16.55,
"product_id": 4,
"sku": "test-pa",
"weight": 1,
"item_condition": "opened",
"order_item_id": 90,
"qty": 1
},
{
"entity_id": 6,
"name": "test CA 2",
"parent_id": 5,
"price": 18.95,
"product_id": 3,
"sku": "test-ca",
"weight": 1,
"item_condition": "unopened",
"order_item_id": 91,
"qty": 1
}
],
"comments": [
{
"is_customer_notified": 1,
"parent_id": 5,
"rma_status": "pending",
"comment": "initial api comment",
"is_visible_on_front": 1,
"created_at": "2022-01-18 03:00:25",
"entity_id": 10
}
],
"udpo_id": "78",
"udpo_increment_id": "000000061-2",
"rma_reason": "refund",
"rma_status": "pending",
"shipment_id": "47",
"shipment_increment_id": "000000061-2-0",
"udropship_vendor": "1",
"vendor_name": "vendor1"
},
{
"billing_address_id": 90,
"created_at": "2022-01-24 21:52:51",
"customer_id": 1,
"email_sent": 1,
"entity_id": 6,
"increment_id": "000000006",
"order_id": 45,
"shipping_address_id": 89,
"store_id": 1,
"total_qty": 1,
"updated_at": "2022-01-24 21:52:51",
"items": [
{
"entity_id": 7,
"name": "test PA",
"parent_id": 6,
"price": 16.55,
"product_id": 4,
"sku": "test-pa",
"weight": 1,
"item_condition": "unopened",
"order_item_id": 82,
"qty": 1
}
],
"comments": [],
"udpo_id": "72",
"udpo_increment_id": "000000058-1",
"rma_reason": "exchange",
"rma_status": "pending",
"shipment_id": "43",
"shipment_increment_id": "000000058-1-0",
"udropship_vendor": "1",
"vendor_name": "vendor1"
},
{
"billing_address_id": 94,
"created_at": "2022-01-24 21:56:42",
"customer_id": 1,
"email_sent": 1,
"entity_id": 8,
"increment_id": "000000008",
"order_id": 47,
"shipping_address_id": 93,
"store_id": 1,
"total_qty": 1,
"updated_at": "2022-01-24 21:56:42",
"items": [
{
"entity_id": 9,
"name": "test CA 2",
"parent_id": 8,
"price": 18.95,
"product_id": 3,
"sku": "test-ca",
"weight": 1,
"item_condition": "unopened",
"order_item_id": 88,
"qty": 1
}
],
"comments": [],
"udpo_id": "76",
"udpo_increment_id": "000000060-2",
"rma_reason": "exchange",
"rma_status": "pending",
"shipment_id": "45",
"shipment_increment_id": "000000060-2-0",
"udropship_vendor": "1",
"vendor_name": "vendor1"
},
{
"billing_address_id": 84,
"created_at": "2022-01-24 22:00:17",
"customer_id": 1,
"email_sent": 1,
"entity_id": 10,
"increment_id": "000000010",
"order_id": 42,
"shipping_address_id": 83,
"store_id": 1,
"total_qty": 1,
"updated_at": "2022-01-24 22:00:17",
"items": [
{
"entity_id": 11,
"name": "test PA",
"parent_id": 10,
"price": 16.55,
"product_id": 4,
"sku": "test-pa",
"weight": 1,
"item_condition": "unopened",
"order_item_id": 76,
"qty": 1
}
],
"comments": [],
"udpo_id": "67",
"udpo_increment_id": "000000055-2",
"rma_reason": "exchange",
"rma_status": "pending",
"shipment_id": "42",
"shipment_increment_id": "000000055-2-0",
"udropship_vendor": "1",
"vendor_name": "vendor1"
},
{
"billing_address_id": 106,
"created_at": "2022-04-26 06:24:52",
"customer_id": 1,
"email_sent": 1,
"entity_id": 11,
"increment_id": "000000011",
"order_id": 53,
"shipping_address_id": 105,
"store_id": 1,
"total_qty": 1,
"updated_at": "2022-04-26 06:24:52",
"items": [
{
"entity_id": 12,
"name": "Utest-0216",
"parent_id": 11,
"price": 1,
"product_id": 45,
"sku": "Utest-0216",
"weight": 1,
"item_condition": "unopened",
"order_item_id": 99,
"qty": 1
}
],
"comments": [
{
"is_customer_notified": 1,
"parent_id": 11,
"rma_status": "pending",
"comment": "rma api comment",
"is_visible_on_front": 1,
"created_at": "2022-04-26 06:24:53",
"entity_id": 11
}
],
"udpo_id": "86",
"udpo_increment_id": "000000066-1",
"rma_reason": "refund",
"rma_status": "pending",
"shipment_id": "49",
"shipment_increment_id": "000000066-1-0",
"udropship_vendor": "1",
"vendor_name": "vendor1"
}
],
"search_criteria": null,
"total_count": 6
}
===== Get Single RMA Info =====
In order to get single RMA information perform ///V1/urma/:id// GET API call. :id parameter could be either uReturn entity id or it's increment id.
''
Example:
''
GET http://magento.loc/rest/V1/urma/000000011
''
RESPONSE
''
{
"billing_address_id": 106,
"created_at": "2022-04-26 06:24:52",
"customer_id": 1,
"email_sent": 1,
"entity_id": 11,
"increment_id": "000000011",
"order_id": 53,
"shipping_address_id": 105,
"store_id": 1,
"total_qty": 1,
"updated_at": "2022-04-26 06:24:52",
"items": [
{
"entity_id": 12,
"name": "Utest-0216",
"parent_id": 11,
"price": 1,
"product_id": 45,
"sku": "Utest-0216",
"weight": 1,
"item_condition": "unopened",
"order_item_id": 99,
"qty": 1
}
],
"comments": [
{
"is_customer_notified": 1,
"parent_id": 11,
"rma_status": "pending",
"comment": "rma api comment",
"is_visible_on_front": 1,
"created_at": "2022-04-26 06:24:53",
"entity_id": 11
}
],
"udpo_id": "86",
"udpo_increment_id": "000000066-1",
"rma_reason": "refund",
"rma_status": "pending",
"shipment_id": "49",
"shipment_increment_id": "000000066-1-0",
"udropship_vendor": "1",
"vendor_name": "vendor1"
}
===== Add comment to RMA =====
In order to add comment to RMA perform ///V1/urma/:id/addComment// POST API call. :id parameter could be either RMA entity id or it's increment id. Request payload expect ''data'' json encoded array parameter that match //\Unirgy\RmaApi\Api\Data\CreateRmaCommentInterface// interface. For definition check //app\code\Unirgy\RmaApi\Api\Data\CreateRmaCommentInterface.php// file. It return bool true on success and may rise exception if RMA not found or does not belong to vendor.
''
Example:
''
POST http://magento.loc/index.php/rest/V1/urma/000000011/addComment
{
"data": {
"comment": "comment from addComment API call",
"is_customer_notified": true,
"is_visible_on_front": true,
"resolution_notes": "resolved via addComment API call",
"status": "approved"
}
}
''
RESPONSE
''
true
===== Get RMA Comments List =====
In order to get list of RMA comments perform ///V1/urma/:id/comments// GET API call. :id parameter could be either RMA entity id or it's increment id.
''
Example:
''
GET http://magento.loc/index.php/rest/V1/urma/000000011/comments
''
RESPONSE
''
{
"items": [
{
"is_customer_notified": 1,
"parent_id": 11,
"rma_status": "pending",
"comment": "rma api comment",
"is_visible_on_front": 1,
"created_at": "2022-04-26 06:24:53",
"entity_id": 11
},
{
"is_customer_notified": 1,
"parent_id": 11,
"rma_status": "approved",
"comment": "comment from addComment API call\n\n[vendor1 has changed the RMA status to approved]\n[vendor1 has changed the RMA resolution notes]",
"is_visible_on_front": 1,
"created_at": "2022-04-26 06:50:37",
"entity_id": 13
}
],
"search_criteria": {
"filter_groups": [
{
"filters": [
{
"field": "parent_id",
"value": "11",
"condition_type": "eq"
}
]
}
]
},
"total_count": 3
}
===== Add tracking number to RMA =====
In order to add tracking number to RMA perform ///V1/urma/:id/addTrack// POST API call. :id parameter could be either RMA 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 track id 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/urma/000000011/addTrack
{"carrier":"ups","title":"UPS","trackNumber":"UPS12345"}
RESPONSE
2
===== Delete tracking number from RMA =====
In order to delete tracking number from RMA perform ///V1/urma/:id/deleteTrack/:trackNumber// POST API call. **:id** parameter could be either RMA entity id or it's increment id, **:trackNumber** should be tracking number. It return bool true on success and may rise exception if RMA not found or does not belong to vendor and if tracking number not found within RMA.
''
Example:
''
POST http://magento.loc/index.php/rest/V1/urma/000000011/deleteTrack/UPS12345
''
RESPONSE
''
true