Kirjaudu sisään

nShift Help Center

Pull API

Avatar
Malene Tidemann
Päivitetty

Artikkelin osiot:

 

Julkisen API:n todennus

Palautusten julkinen API käyttää Basic Authentication -menetelmää. Kaikki API:n menetelmät käyttävät samaa todennustietoa, organisaatiosi käyttäjänimeä ja salasanaa (kuva, joka näyttää esimerkin Postmanin käytöstä alla).

 

returns-authentication.png

 

Päätepisteet

Palautustilausten listan hakeminen

URL: GET /return-orders

Päätepiste palauttaa listan palautustilauksista kyselymerkkijonossa lähetettyjen parametrien perusteella.


Parametrit:

Parametri Tyyppi Pakollinen
updatedAfter DateTime (ISO-muodossa) Ei
updatedBefore DateTime (ISO-muodossa) Ei
createdAfter DateTime (ISO-muodossa) Ei
createdBefore DateTime (ISO-muodossa) Ei

 

Esimerkkikutsu:

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


Hakee kaikki palautustilaukset, jotka on päivitetty 20.12.2022 jälkeen ja 31.12.2022 ennen sekä luotu 20.12.2020 jälkeen ja 31.12.2022 ennen.

 

Vastaus

ResponseWrapper:

Kenttä Tyyppi Kuvaus
records ReturnOrder[] Haun löytämät tietueet
totalRecords integer Löytyneiden tietueiden määrä

 

{
  "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
}

 

 

Palautustilaustuotteen hakeminen tunnuksella

URL: GET /return-orders/{returnOrderId}

Päätepiste palauttaa palautustilauksen, joka on tunnistettu URL-polussa käytetyllä tunnuksella.

 

Parametrit:

Parametri Tyyppi Pakollinen
returnOrderId integer kyllä

 

Esimerkkikutsu:

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

Hakee palautustilauksen, jonka tunnus on 56373.

 

Vastaus:

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
    }
  ]
}

 

 

Palautusten yhteenveto

URL: GET /returns-summary

Päätepiste palauttaa pyynnön tehneen asiakkaan palautustilausten yhteenvedon.

Suodattimien perusteella päätepistettä voidaan käyttää suodattamaan palautustilaukset tietylle markkinalle (esimerkiksi vain Ruotsin markkina, jos palautustilauksia on kirjattu sekä Iso-Britannian että Ruotsin markkinoille).

periodStart ja periodEnd sovelletaan päivämäärään, jolloin palautustilausta viimeksi päivitettiin.


Tämä päätepiste sisältää myös sivutuksen. Sivutus alkaa sivulta 0.


Parametrit:

Parametri Tyyppi Pakollinen
periodStart DateTime (ISO-muodossa) kyllä
periodEnd DateTime (ISO-muodossa) ei
marketCode integer ei
pageSize integer ei
pageNumber integer ei

 

Esimerkkikutsu:

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

 

Hakee kyseiselle markkinalle kuuluvat tilaukset, jotka on päivitetty mainitulla aikavälillä. Sivutuksen vuoksi se ohittaa ensimmäiset 5 tilausta (järjestetty return_order_item_id:n mukaan).

 

Vastaus:

Palauttaa PaginatedResponse<ReturnSummary>

Kenttä Tyyppi Pakollinen
records ReturnSummary[] Haun palauttamat palautusyhteenvedot
totalRecords integer Löytyneiden tietueiden määrä
pagination.totalPages integer Tulosten kattamien sivujen määrä nykyisessä sivutusasetuksessa
pagination.currentPage integer Sivu, jolle tällä hetkellä haetut tiedot kuuluvat
pagination.currentPageSize integer Palautustilausyhteenvedot sivua kohden, joita API tällä hetkellä hakee

 

{
  "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
  }
}

Palautustilausyhteenvetopäätepiste tuo myös tietoa tilauksen tilasta sekä hyvityksen tilasta.

 

 

Palautustilauksen hyvityksen tilan päivittäminen

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

Tätä päätepistettä käytetään palautustilauksen tilan päivittämiseen.

 

Parametrit:

Kenttä Tyyppi Pakollinen
returnOrderId bool kyllä

 

Pyyntörunko:

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

 

Parametri Tyyppi Pakollinen
refundSucceeded boolean kyllä
orderId string ei
errorCode string ei
errorDescription string ei

 

Esimerkkikutsu:

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

 

Vastaus:

HTTP 200, jos pyyntö suoritetaan onnistuneesti.

Virhekoodit tarvittaessa:

Esimerkiksi, jos puuttuu refundSucceeded

 

{
  "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"
}

 

Aiheeseen liittyvät artikkelit