Table of Contents
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":"<vendor email>","password":"<vendor 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:
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
