Aanmelden

nShift Help Center

Pull API

Avatar
Malene Tidemann
Bijgewerkt

Secties in dit artikel:

 

Authenticatie van de publieke API

De publieke Returns API gebruikt Basic Authentication. Alle methoden die deel uitmaken van de API gebruiken dezelfde informatie voor authenticatie, de gebruikersnaam en het wachtwoord voor uw organisatie (afbeelding hieronder toont het gebruik vanuit Postman).

 

returns-authentication.png

 

Endpoints

Lijst van retourorders ophalen

URL: GET /return-orders

Endpoint retourneert een lijst van retourorders gebaseerd op de query string parameters die in de methode worden meegegeven.


Parameters:

Parameter Type Vereist
updatedAfter DateTime (ISO-formaat) Nee
updatedBefore DateTime (ISO-formaat) Nee
createdAfter DateTime (ISO-formaat) Nee
createdBefore DateTime (ISO-formaat) Nee

 

Voorbeeld Aanroep:

GET https://staging.returnado.com/public-api/v3/return-orders?updatedAfter=2022-12-20T01:30:00.
000-05:00&updatedBefore=2022-12-31T01:30:00.000-05:00&createdAfter=2022-12-20T01:30:00.000-05:0
0&createdBefore=2022-12-31T01:30:00.000-05:00


Haalt alle retourorders op die zijn bijgewerkt na 20-12-2022 en vóór 31-12-2022 en aangemaakt na 20-12-2020 en vóór 31-12-2022.

 

Respons

ResponseWrapper:

Veld Type Omschrijving
records ReturnOrder[] Gevonden records door zoekopdracht
totalRecords integer Aantal gevonden records

 

{
  "records": [
    {
      "returnOrderId": 56373,
      "returnOrderExtId": "{}",
      "orderId": "249-307",
      "createdAt": "2022-12-20T18:02:31Z",
      "updatedAt": "2022-12-20T18:02:32Z",
      "marketCode": "27001",
      "customerId": "john_doe@nshift.com",
      "status": "pre_approval",
      "currency": "GBP",
      "netOriginalTotal": 1198.8,
      "taxOriginalTotal": 0,
      "grossOriginalTotal": 1198.8,
      "netRefundItemsTotal": 999,
      "taxRefundItemsTotal": 0,
      "grossRefundItemsTotal": 999,
      "netShippingFeeRefund": 0,
      "taxShippingFeeRefund": 0,
      "grossShippingFeeRefund": 0,
      "netFeesTotal": 0,
      "taxFeesTotal": 0,
      "grossFeesTotal": 0,
      "netRefundTotal": 999,
      "taxRefundTotal": 0,
      "grossRefundTotal": 999,
      "items": [
        {
          "returnOrderId": 56373,
          "returnOrderExtId": "{}",
          "returnOrderItemId": 120808,
          "originalOrderItemId": "1",
          "productId": "iris",
          "productVariantId": "iris",
          "originalNetAmount": 999,
          "originalTaxAmount": 0,
          "originalGrossAmount": 999,
          "reportedCondition": "tags_are_intact",
          "reclamationReason": "style_doesnt_suit",
          "nextAction": "restock",
          "status": "pending",
          "refundQuantity": 1,
          "netRefundAmount": 999,
          "taxRefundAmount": 0,
          "grossRefundAmount": 999
        }
      ]
    }
  ],
  "totalRecords": 1
}

 

 

Retourorderitem ophalen op Id

URL: GET /return-orders/{returnOrderId}

Endpoint retourneert de retourorder die is geïdentificeerd door het id in het URL-pad.

 

Parameters:

Parameter Type Vereist
returnOrderId integer ja

 

Voorbeeld Aanroep:

GET https://staging.returnado.com/public-api/v3/return-orders/56373

Haalt de retourorder op die wordt geïdentificeerd door het id 56373.

 

Respons:

ReturnOrder

{
  "returnOrderId": 56373,
  "returnOrderExtId": "{}",
  "orderId": "249-307",
  "createdAt": "2022-12-20T18:02:31Z",
  "updatedAt": "2022-12-20T18:02:32Z",
  "marketCode": "27001",
  "customerId": "john_doe@nshift.com",
  "status": "pre_approval",
  "currency": "GBP",
  "netOriginalTotal": 1198.8,
  "taxOriginalTotal": 0,
  "grossOriginalTotal": 1198.8,
  "netRefundItemsTotal": 999,
  "taxRefundItemsTotal": 0,
  "grossRefundItemsTotal": 999,
  "netShippingFeeRefund": 0,
  "taxShippingFeeRefund": 0,
  "grossShippingFeeRefund": 0,
  "netFeesTotal": 0,
  "taxFeesTotal": 0,
  "grossFeesTotal": 0,
  "netRefundTotal": 999,
  "taxRefundTotal": 0,
  "grossRefundTotal": 999,
  "items": [
    {
      "returnOrderId": 56373,
      "returnOrderExtId": "{}",
      "returnOrderItemId": 120808,
      "originalOrderItemId": "1",
      "productId": "iris",
      "productVariantId": "iris",
      "originalNetAmount": 999,
      "originalTaxAmount": 0,
      "originalGrossAmount": 999,
      "reportedCondition": "tags_are_intact",
      "reclamationReason": "style_doesnt_suit",
      "nextAction": "restock",
      "status": "pending",
      "refundQuantity": 1,
      "netRefundAmount": 999,
      "taxRefundAmount": 0,
      "grossRefundAmount": 999
    }
  ]
}

 

 

Retouroverzicht ophalen

URL: GET /returns-summary

De endpoint retourneert het overzicht van retourorders voor de klant die ze opvraagt. 

Op basis van de filters kan de endpoint worden gebruikt om alleen retourorders voor een specifieke markt te filteren (bijvoorbeeld alleen de markt Zweden als retourorders worden geregistreerd voor zowel VK als Zweden).

De periodStart en periodEnd worden toegepast op de datum waarop de retourorder voor het laatst is bijgewerkt.


Deze endpoint bevat ook paginering. Paginering begint bij pagina 0.


Parameters:

Parameter Type Vereist
periodStart DateTime (ISO-formaat) ja
periodEnd DateTime (ISO-formaat) nee
marketCode integer nee
pageSize integer nee
pageNumber integer nee

 

Voorbeeld Aanroep:

GET https://staging.returnado.com/public-api/v3/returns-summary?periodStart=2022-12-10T01:30:00
.000-05:00&periodEnd=2022-12-31T01:30:00.000-05:00&marketCode=27001&pageSize=5&pageNumber=1

 

Haalt de orders op behorend tot de aangegeven markt, bijgewerkt binnen de genoemde periode. Vanwege paginering worden de eerste 5 orders overgeslagen (gesorteerd op return_order_item_id)

 

Respons:

Retourneert PaginatedResponse<ReturnSummary>

Veld Type Vereist
records ReturnSummary[] Retouroverzichten geretourneerd door zoekopdracht
totalRecords integer Aantal gevonden records
pagination.totalPages integer Aantal pagina's dat wordt beslagen door de resultaten in de huidige pagineringsconfiguratie
pagination.currentPage integer Pagina waartoe de momenteel opgehaalde data behoort
pagination.currentPageSize integer Aantal retourorderoverzichten per pagina die de API momenteel ophaalt

 

{
  "records": [
    {
      "marketCode": "27001",
      "marketName": "Arena-1",
      "customerId": "john_doe_1@gmail.com",
      "orderId": "968-309",
      "returnOrderId": 56367,
      "returnOrderItemId": 120801,
      "productId": "hermes",
      "productVariantId": "hermes",
      "sku": "hermes",
      "productName": "hermes",
      "currencyCode": "GBP",
      "returnedQuantity": 1,
      "returnReasonCode": "style_doesnt_suit",
      "itemConditionCode": "accessory_missing",
      "nextActionCode": "restock",
      "originalValueGross": 579,
      "returnValueGross": 579,
      "reconversionValueGross": 0,
      "refundValueGross": 579,
      "orderCreatedAt": "2022-12-19T10:19:36Z",
      "createdAt": "2022-12-19T10:22:10Z",
      "currentState": "awaiting_approval",
      "stateUpdatedAt": "2022-12-19T10:22:10Z",
      "claim": false,
      "refundApproved": false
    },
    {
      "marketCode": "27001",
      "marketName": "Arena-1",
      "customerId": "john_doe_2@nshift.com",
      "orderId": "819-761",
      "returnOrderId": 56368,
      "returnOrderItemId": 120802,
      "productId": "hera",
      "productVariantId": "hera",
      "sku": "hera",
      "productName": "hera",
      "currencyCode": "GBP",
      "returnedQuantity": 1,
      "returnReasonCode": "colour_not_as_expected",
      "itemConditionCode": "accessory_missing",
      "nextActionCode": "restock",
      "originalValueGross": 39,
      "returnValueGross": 39,
      "reconversionValueGross": 0,
      "refundValueGross": 39,
      "orderCreatedAt": "2022-12-19T14:57:25Z",
      "createdAt": "2022-12-19T14:58:37Z",
      "currentState": "awaiting_approval",
      "stateUpdatedAt": "2022-12-19T14:58:37Z",
      "claim": false,
      "refundApproved": false
    },
    {
      "marketCode": "27001",
      "marketName": "Arena-1",
      "customerId": "john_doe@nshift.com",
      "orderId": "249-307",
      "returnOrderId": 56373,
      "returnOrderItemId": 120808,
      "productId": "iris",
      "productVariantId": "iris",
      "sku": "iris",
      "productName": "iris",
      "currencyCode": "GBP",
      "returnedQuantity": 1,
      "returnReasonCode": "style_doesnt_suit",
      "itemConditionCode": "tags_are_intact",
      "nextActionCode": "restock",
      "originalValueGross": 999,
      "returnValueGross": 999,
      "reconversionValueGross": 0,
      "refundValueGross": 999,
      "orderCreatedAt": "2022-12-20T17:59:56Z",
      "createdAt": "2022-12-20T18:02:31Z",
      "currentState": "awaiting_approval",
      "stateUpdatedAt": "2022-12-20T18:02:32Z",
      "claim": false,
      "refundApproved": false
    }
  ],
  "totalRecords": 8,
  "pagination": {
    "totalPages": 2,
    "currentPage": 1,
    "currentPageSize": 3
  }
}

De endpoint voor ReturnOrderSummary geeft ook informatie over de status van de order, evenals de status van de terugbetaling.

 

 

Status terugbetaling retourorder bijwerken

URL: PUT /update-return-status/{returnOrderId}

Deze endpoint wordt gebruikt om de status van de retourorder bij te werken.

 

Parameters:

Veld Type Vereist
returnOrderId bool true

 

Request Body:

{
  "refundSucceeded": true,
  "orderId": null,
  "errorCode": "e404",
  "errorDescription": "insufficient funds"
}

 

Parameter Type Vereist
refundSucceeded boolean ja
orderId string nee
errorCode string nee
errorDescription string nee

 

Voorbeeld aanroep:

PUT https://staging.returnado.com/public-api/v3/update-return-status/56367

 

Respons:

HTTP 200 als het verzoek succesvol is voltooid.

Foutcodes waar van toepassing:

Bijvoorbeeld, als refundSucceeded ontbreekt

 

{
  "code": 422,
  "error": "Unprocessable Entity",
  "message": "Field error in object 'returnOrderUpdateStatusDto' on field 'refundSucceeded': 
   rejected value [null]; codes [NotNull.returnOrderUpdateStatusDto.refundSucceeded,NotNull.
   refundSucceeded,NotNull.java.lang.Boolean,NotNull]; arguments [org.springframework.context
   .support.DefaultMessageSourceResolvable: codes [returnOrderUpdateStatusDto.refundSucceeded,
   refundSucceeded]; arguments []; default message [refundSucceeded]]; default message [must 
   not be null]",
  "timestamp": "2023-01-16T17:22:05Z"
}

 

Verwante artikelen