Skip to main content

RMA Webhook integration

Requirements​

  • Create a new endpoint to receive the returns created through Narvar

Proposal​

Create a new endpoint to be called from Narvar to create the returns in Hybris.

The endpoint will be a passthrough to the endpoint in Hybris.

Integration diagram​

RMA Webhook integration diagram

Components​

Narvar API Gateway​

Endpoint: POST /oauth/token​

Headers:

Authorization: Basic {(Base 64 encoded) client:secret}

Content-Type: application/x-www-form-urlencoded

Body:

Content Type application/x-www-form-urlencoded

Parameters:

grant_type:client_credentials

Hybris OAuth token endpoint is exposed through Narvar API Gateway in order to allow them to request an authentication token.

Endpoint: POST /rma​

Headers:

Authorization: Bearer {OAuth token got with the previous endpoint}

Content-Type: application/json

Body:

Content Type application/json

Data:

See body data format in Narvar RMA Webhook doc

Narvar Api Gateway Gitlab project

Hybris raphanarvarintegration extension​

raphanarvarintegration is our custom Hybris extension to add the needed customizations for Narvar Integration in Hybris. It provides a new endpoint to handle Narvar RMA Webhook requests.

When a Narvar RMA notification is received, it will trigger on Hybris the same process as when a customer requested a refund through the website previously.

Endpoint: POST /raphacommercewebservices/v2/rapha/rma​

This endpoint will trigger the RMA process in Hybris.

Auth:

OAuth Bearer token. OAuth client needs to have ROLE_NARVARRMAMANAGER authority.

Body:

It should accept Narvar RMA Webhook request data. Narvar RMA Webhook doc

Item Type modifications:​

ReturnRequest: Added String narvarRMANumber attribute. It can be null and not unique. It will store the Narvar RMA number related to this ReturnRequest. More than one ReturnRequest may be created by a Narvar RMA Notification, so many ReturnRequest can have the same narvarRMANumber.

DeliveryStatus: New enum type with the following values INITIATED, IN_TRANSIT, DELIVERED and CANCELLED. It represents the available triggers sent from Narvar in RMA updates.

ReturnEntry: Added DeliveryStatus deliveryStatus attribute. It can be null. This field will save the last trigger sent from Narvar for each return entry.

RMA process​

Only refunds will be handled by Hybris when Narvar RMA endpoint is called.

Narvar RMA Webhook can call Hybris with various RMA status (return_tracking_status):

return_initiated_standard

return_on_its_way_standard

return_delivered_standard

return_cancellation_standard

return_initiated_standard Creates the required return requests on Hybris. The process in Hybris to handle a refund is to create one ReturnRequest per returned order entry line and unit. For example:

If I return one unit of AHZ01XXBFSSML and two units of CLS01XXWHT390, three return request will be created:

ReturnRequest 1: 1x AHZ01XXBFSSML

Return Request 2: 1x CLS01XXWHT390

Return Request 3: 1x CLS01XXWHT390

raphanarvarintegration RMA endpoint will handle this and it will save Narvar RMA Number on all the Hybris Return Request created by the RMA notification. All the return entries will have INITIATED delivery status.

return_on_its_way_standard Updates all Hybris return requests related to the received RMA setting delivery status in all the return entries equal to IN_TRANSIT

Creates a new refund order process for the RMA

return_delivered_standard Updates all Hybris return requests related to the received RMA setting delivery status in all the return entries equal to DELIVERED

return_cancellation_standard Cancels all Hybris return requests related to the received RMA. Updates all Hybris return requests related to the received RMA setting delivery status in all the return entries equal to CANCELLED