Manual
Return shipments without the storefront, too: store API and admin API.
Headless shops and apps get routes of the store API: login to the order, creating, return document and labels, with the same conditions as in the shop. The ERP and processes of your own get routes of the admin API and the entities of the plugin, all with the permission “Use return shipments (full access)”.
Store API
Which routes does the store API have?
Every route of the store API is POST and lies under /store-api/dvsn/return-shipment/. Except the login to the order, they need a logged-in customer in the context token or the access the login to the order opens.
| Route | what for | Fields | Response |
|---|---|---|---|
order-login | login to the order without a customer account | orderNumber, emailOrZipcode | 200 with orderId; 404; 429 with Retry-After |
create | create a return shipment | orderId, comment, lineItems, optional carrier | id and number; 400 return_shipment_invalid |
document | return document | id | PDF as base64; 404; 403 approval_pending |
label | label or QR code of a carrier | id, carrier, kind (label, qr_code) | file as base64 |
dhl-label | DHL label | id | file as base64 |
dhl-qr-code | QR code of DHL | id | file as base64 |
ups-label | UPS label | id | file as base64 |
Files come as JSON with content (base64), contentType, fileName and fileExtension.
How does a customer without an account get to his order?
As in the shop, a customer without a customer account logs in with order number and email address or postal code. The route checks the same as the page in the shop and slows down too many attempts the same way. After that the access to the order applies to the context token of this request, and the other routes work with the orderId.
POST /store-api/dvsn/return-shipment/order-loginwith{"orderNumber": "11099", "emailOrZipcode": "24103"}- Response 200 with the
orderId; 404 when order number and detail do not match. - Response 429 after too many attempts, with the header
Retry-After: that many seconds until the next attempt.
How does an app create a return shipment, and why does the route refuse?
The route create checks the same as the form in the shop: conditions on order and products, deadline, reasons and procedures of the sales channel, required comments and quantity. Per position id (the position of the order), quantity, reasonId, procedureId and comment come along; carrier is dhl, ups or self. What applies: photos, files and the checklist belong to the form of the shop, so a reason with required files refuses via the store API.
Code in violations | means |
|---|---|
order_not_found | the order does not exist, or it belongs to another customer or sales channel |
order_not_returnable | a condition of the order or the deadline allows no return shipment; detail names the reason |
nothing_selected | no position has a piece |
position_unknown, position_twice | a position the customer cannot return, or the same position twice |
quantity_invalid, quantity_too_high | no whole number from 1, or more pieces than are open |
reason_missing, reason_unknown | reason missing or not valid in this sales channel |
procedure_missing, procedure_unknown | procedure missing or not valid |
comment_missing | the reason asks for a comment |
files_missing | the reason asks for a photo or a file |
carrier_unavailable | a carrier that is not offered, for DHL and UPS also below the minimum value; detail then names it |
A refusal comes with status 400 and the code return_shipment_invalid; meta.parameters.violations names code, lineItemId and detail per violation.
A return shipment via the store API triggers the same flows as one from the shop, so the mails “Return shipment created” to customer and team. While it waits for approval, document answers 403 approval_pending.
How does an app get the return document and the label?
The routes of the labels deliver the newest label of the return shipment or create the first one, with the mail “Return label”; they create no further label. The same rules apply as on the page of the return shipment, also the payment of a chargeable label.
| Response | means |
|---|---|
| 200 | the file as base64 |
| 404 | return shipment unknown or not the customer’s |
| 400 | a request that does not fit, for example a QR code at UPS |
| 403 | a rule of the label does not fit, or the return shipment waits for approval (approval_pending) |
| 409 | a limit is reached, or a label is being created right now |
| 502 | the carrier refuses; its message is in the response only with “Show the error message of the carrier” |
Admin API
What can an ERP do via the admin API?
The routes of the admin API lie under /api/dvsn-return-shipment/; each requires the permission of the plugin. Added to them are the usual endpoints of Shopware for the entities of the plugin, for example dvsn_return_shipment, dvsn_return_shipment_reason or dvsn_return_shipment_dhl, likewise only with the permission.
| Area | Routes |
|---|---|
| Creating | create, create/prepare/{orderId}, create/search |
| Status and approval | status/change, status/usage, approval/approve, approval/label-option, order-delivery/suggestion/{id}, order-delivery/apply |
| Checking | goods-receipt/check, goods-receipt/suggestion, goods-receipt/reopen |
| Compensation | refund/prepare/{id}, refund/calculate, refund/save, refund/document/{refundId}, replacement/prepare/{id}, replacement/create, b-stock/create |
| Communication | message/send, attachment/{attachmentId} |
| Documents and labels | document/{returnShipmentId}, label/check/{id}, label/create, label/send-mail, label/file/{fileId} |
| Checking credentials | dhl-api-validator/validate, ups-api-validator/validate, ups-api-validator/validate-oauth-token |
| Analysis | dashboard/{part}, statistics/{tab}, export/rows, return-rate/product/{id}, return-rate/product/{id}/comments, return-rate/customer/{id}, return-rate/shop |
| Product hints | product-hint/suggestion, product-hint/product/{id}, product-hint/product/{id}/comments, product-hint/reject, product-hint/create |
What applies:
- A change of status via the admin API stands in the history of the return shipment and triggers the flow “Status changed”. Whether the customer gets a mail is then decided by the switch “Send mail to the customer” at the status.
- A status that a return shipment uses cannot be deleted via the API either; the response names
DVSN_RETURN_SHIPMENT_STATUS_IN_USE. - An integration writing with the header
sw-skip-trigger-flowtriggers no flow and so no mail.
How to set up the access for an ERP
An ERP accesses via an integration of Shopware. An integration with administrator rights may do everything; without them it needs a role with the permission Use return shipments (full access). The permission holds every entity of the plugin and the read rights on the core that the return shipments need.
- 1
Under Settings › System › Users & permissions create a role, for example “ERP”, and in the card Additional permissions switch on Use return shipments (full access).
- 2
Open Settings › System › Integrations and click Add integration. Enter a Name.
- 3
Leave Administrator off and choose the role with the permission under Roles.
- 4
Copy Access key ID and Secret access key into the ERP and click Save integration.
With access key ID and secret the ERP fetches a token via the OAuth route of Shopware and calls the routes with it.
Common questions
Can an app create return shipments without the storefront?
Yes, via the store API with the route create. It checks the same conditions as the form in the shop and triggers the same mails.
Does the customer need a customer account for it?
No. The route order-login opens the order with order number and email address or postal code for the context token; after that the other routes work with the order.
Do deadline and conditions also apply via the store API?
Yes. Conditions on order and products, deadline, reasons and procedures of the sales channel are checked the same way; a refusal names the code per violation.
Can the store API upload photos for the return shipment?
No, photos, files and the checklist belong to the form of the shop. A reason that asks for photos refuses via the store API with files_missing.
How does an app load the label via the store API?
With the route label and the fields id, carrier and kind, or with dhl-label, dhl-qr-code and ups-label. They deliver the newest label or create the first one, as a file in base64.
Which permission does an ERP need for the admin API?
An integration with administrator rights or with a role that has “Use return shipments (full access)”. Every route and every entity of the plugin requires this permission.
Does a change of status via the admin API send a mail?
It triggers the flow “Status changed”. The customer gets the mail when the new status has “Send mail to the customer” on and the flow is active.
More chapters