Pereiti prie turinio
ShopentlyLearn

Gauti — Grąžinimai, skundai ir keitimai

Skaitykite „Grąžinimai, skundai ir keitimai“ duomenis. Rezultatas priklauso nuo šio veiksmo parametrų.

GET/api/v1/requests/{request_id}

Tapatybės patvirtinimas
Bearer
Prieinama nuo plano
BASIC
Būtinos teisės
returns.request:read

Kodo pavyzdžiai

Užklausos pavyzdys

cURL

: "${SHOPENTLY_SHOP_URL:?}"

curl --disable --globoff --fail-with-body --silent --show-error \
  --proto '=https' --connect-timeout 5 --max-time 30 \
  --request GET \
  --header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \
  --url "${SHOPENTLY_SHOP_URL%/}"/api/v1/requests/example

PHP

<?php
declare(strict_types=1);

$baseUrl = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/');
$origin = parse_url($baseUrl);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
    isset($origin['user'], $origin['pass']) || isset($origin['user']) || isset($origin['path']) ||
    isset($origin['query']) || isset($origin['fragment'])) {
    throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin');
}
$credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: '';
if ($credential === '' || strpbrk($credential, "\r\n") !== false) {
    throw new RuntimeException('Invalid credential');
}
$headers = [];
$headers[] = 'Authorization: Bearer ' . $credential;
$responseHeaders = [];
$handle = curl_init($baseUrl . '/api/v1/requests/example');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPHEADER => $headers,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_PROTOCOLS => CURLPROTO_HTTPS,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
    CURLOPT_CONNECTTIMEOUT => 5,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HEADERFUNCTION => static function ($handle, string $line) use (&$responseHeaders): int {
        if (str_contains($line, ':')) {
            [$name, $value] = explode(':', $line, 2);
            $responseHeaders[strtolower(trim($name))] = trim($value);
        }
        return strlen($line);
    },
]);
$raw = curl_exec($handle);
$status = curl_getinfo($handle, CURLINFO_RESPONSE_CODE);
$error = curl_error($handle);
curl_close($handle);
if ($raw === false) {
    throw new RuntimeException('Transport error: ' . $error);
}
if ($status < 200 || $status >= 300) {
    throw new RuntimeException('HTTP ' . $status . '; request_id=' .
        ($responseHeaders['x-request-id'] ?? '') . '; retry_after=' . ($responseHeaders['retry-after'] ?? ''));
}
$result = $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE), PHP_EOL;

Python

from contextlib import ExitStack
import json
import os
from urllib.parse import urlsplit

import requests  # python -m pip install requests

base_url = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/")
origin = urlsplit(base_url)
if origin.scheme != "https" or not origin.hostname or origin.username or origin.password or origin.path or origin.query or origin.fragment:
    raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin")
credential = os.environ['SHOPENTLY_ACCESS_TOKEN']
if not credential or "\r" in credential or "\n" in credential:
    raise ValueError("Invalid credential")
headers = {}
headers["Authorization"] = 'Bearer' + " " + credential
body = None
if body is not None:
    headers["Content-Type"] = "application/json"

with ExitStack() as stack:
    session = stack.enter_context(requests.Session())
    files = None
    if False:
        image = stack.enter_context(open(os.environ["SHOPENTLY_IMAGE_FILE"], "rb"))
        if os.fstat(image.fileno()).st_size > 5242880:
            raise ValueError("Image exceeds 5 MiB")
        files = {"file": ("article.png", image, "image/png")}
    response = session.request(
        'GET', base_url + '/api/v1/requests/example', headers=headers,
        data=body.encode("utf-8") if body is not None else None, files=files,
        timeout=(5, 30), allow_redirects=False,
    )
    if not 200 <= response.status_code < 300:
        raise RuntimeError(f"HTTP {response.status_code}; request_id={response.headers.get('X-Request-ID', '')}; retry_after={response.headers.get('Retry-After', '')}")
    if False:
        if response.headers.get("Content-Type") != "image/webp" or len(response.content) > 5242880:
            raise ValueError("Unexpected image response")
        with open(os.environ["SHOPENTLY_OUTPUT_FILE"], "xb") as output:
            output.write(response.content)
    else:
        result = response.json() if response.content else None
        print(json.dumps(result, ensure_ascii=False, indent=2))

Atsakymo pavyzdys 200

JSON
{
  "data": {
    "created_at": "2026-01-01T12:00:00Z",
    "customer": {
      "email": "customer@example.invalid",
      "name": "Example"
    },
    "id": "example",
    "items": [
      {
        "id": "example",
        "name": "Example",
        "order_line_id": "example",
        "product_id": "example",
        "quantity": 1,
        "returned_quantity": 1,
        "sku": "example",
        "total": {
          "amount": "0.00",
          "currency": "PLN",
          "minor_units": 2
        },
        "unit_price": {
          "amount": "0.00",
          "currency": "PLN",
          "minor_units": 2
        },
        "variant_id": "example",
        "variant_options": [
          {
            "name": "Example",
            "value": "example"
          }
        ]
      }
    ],
    "number": "example",
    "order_id": "example",
    "order_number": "example",
    "products_value": {
      "amount": "0.00",
      "currency": "PLN",
      "minor_units": 2
    },
    "refund": {
      "amount": {
        "amount": "0.00",
        "currency": "PLN",
        "minor_units": 2
      },
      "completed_at": null,
      "status": "pending",
      "updated_at": "2026-01-01T12:00:00Z",
      "version": 1
    },
    "resolution_state": "unknown",
    "status": {
      "id": "example",
      "locale": "en",
      "name": "Example"
    },
    "type": "return",
    "updated_at": "2026-01-01T12:00:00Z",
    "version": 1
  },
  "meta": {
    "request_id": "example"
  }
}

Kaip tai veikia

  • Rinkinio ir detalių prieigos taškai pateikia prašymo numerį ir tipą, susijusį užsakymą, pateiktas prekes, kliento duomenis bei grąžinimo informaciją.
  • Galimi prašymų tipai yra return, exchange ir complaint.
  • Būsenų identifikatorius gaukite iš /api/v1/request-statuses.
  • Būsena ir grąžinama suma įrašomos atskirai, tikrinant versijas.
  • Pakeitus užregistruotą grąžinamą sumą atnaujinamas prašymo įrašas; pinigų pervedimas neatliekamas.

Parametrai

Kelio parametrai

request_idEilutėPrivalomas

Prašymo identifikatorius; atsakymo metaduomenyse nurodo HTTP užklausą.

Apribojimai
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
Pavyzdys: "example"

Ši operacija nepriima JSON turinio.

Atsakymai

Atsakymas 200

dataRequestDetailData Privalomas

Sėkmingo atsakymo duomenys.

Laukai · data
created_atEilutėPrivalomas

Sukūrimo laikas.

format: "date-time"
customerRequestCustomerData Privalomas

Šiam ištekliui užregistruota kliento informacija.

Laukai · customer
emailEilutėPrivalomas

El. pašto adresas.

nameEilutėPrivalomas

Ištekliaus pavadinimas atitinkamame kontekste.

idEilutėPrivalomas

Ištekliaus identifikatorius; išsaugokite grąžintą išraišką.

itemsMasyvas <RequestItemData > Privalomas

Į išteklių įtraukti elementai.

Laukai · items
numberEilutėPrivalomas

Žmogui rodomas užsakymo arba prašymo numeris.

order_idEilutėPrivalomas

Susijusio užsakymo identifikatorius.

order_numberEilutėPrivalomas

Susijusio užsakymo numeris.

products_valueMoneyData Privalomas

Užsakymo produktų vertė.

Laukai · products_value
amountEilutėPrivalomas

Dešimtainė suma, užkoduota JSON eilute; null tik ten, kur leidžiama.

currencyEilutėPrivalomas

Sumos valiutos kodas.

Apribojimai
pattern
"^[A-Z]{3}$"
minor_unitsSveikasis skaičiusPrivalomas

Valiutos naudojamų skaitmenų po kablelio skaičius.

minimum: 0maximum: 4
refundRefundData Privalomas

Užregistruota grąžinimo informacija.

Laukai · refund
amountMoneyData nullPrivalomas

Dešimtainė suma, užkoduota JSON eilute; null tik ten, kur leidžiama.

completed_atEilutė nullPrivalomas

Užbaigimo laikas.

Eilutė:format: "date-time"
statusEilutėPrivalomas

Šios konkrečios operacijos priimama būsena.

Apribojimai
enum
["pending", "completed"]
updated_atEilutė nullPrivalomas

Paskutinio atnaujinimo laikas.

Eilutė:format: "date-time"
versionSveikasis skaičiusPrivalomas

Ištekliaus versija lygiagrečių pakeitimų kontrolei.

resolution_stateEilutėPrivalomas

Kliento prašymo sprendimo būsena.

Apribojimai
enum
["unknown", "open", "completed", "rejected", "cancelled"]
statusRequestStatusData Privalomas

Šios konkrečios operacijos priimama būsena.

Laukai · status
idEilutėPrivalomas

Ištekliaus identifikatorius; išsaugokite grąžintą išraišką.

localeEilutėPrivalomas

Šiai užklausai pasirinkta kalba.

nameEilutė nullPrivalomas

Ištekliaus pavadinimas atitinkamame kontekste.

typeRequestType Privalomas

Ištekliaus tipas.

updated_atEilutėPrivalomas

Paskutinio atnaujinimo laikas.

format: "date-time"
versionSveikasis skaičiusPrivalomas

Ištekliaus versija lygiagrečių pakeitimų kontrolei.

metaContextPageMeta ContextMeta PageMeta RequestMeta Privalomas

Atsakymo metaduomenys.

Laukai · meta

ContextPageMeta

localeEilutėPrivalomas

Šiai užklausai pasirinkta kalba.

market_codeEilutėPrivalomas

Konteksto prieigos taško grąžintas rinkos kodas.

market_idEilutėPrivalomas

Konteksto prieigos taško grąžintas rinkos identifikatorius.

paginationPagination Privalomas

Skaidymo į puslapius pagal žymeklį metaduomenys.

request_idEilutėPrivalomas

Prašymo identifikatorius; atsakymo metaduomenyse nurodo HTTP užklausą.

minLength: 1maxLength: 100

ContextMeta

localeEilutėPrivalomas

Šiai užklausai pasirinkta kalba.

market_codeEilutėPrivalomas

Konteksto prieigos taško grąžintas rinkos kodas.

market_idEilutėPrivalomas

Konteksto prieigos taško grąžintas rinkos identifikatorius.

request_idEilutėPrivalomas

Prašymo identifikatorius; atsakymo metaduomenyse nurodo HTTP užklausą.

minLength: 1maxLength: 100

PageMeta

paginationPagination Privalomas

Skaidymo į puslapius pagal žymeklį metaduomenys.

request_idEilutėPrivalomas

Prašymo identifikatorius; atsakymo metaduomenyse nurodo HTTP užklausą.

minLength: 1maxLength: 100

RequestMeta

request_idEilutėPrivalomas

Prašymo identifikatorius; atsakymo metaduomenyse nurodo HTTP užklausą.

minLength: 1maxLength: 100
Atsakymo pavyzdys

HTTP būsena

200
Sėkmingas atsakymas Schema
400
Netinkama užklausa
401
Būtinas tapatybės patvirtinimas
403
Prieiga uždrausta
404
Išteklius nerastas
409
Versijų konfliktas
422
Tikrinimo klaida
429
Viršytas užklausų limitas
Kitos HTTP būsenos (7)
405
Metodas neleidžiamas
413
Užklausa per didelė
415
Nepalaikomas formatas
500
Serverio klaida
502
API tinklų sietuvo klaida
503
Paslauga nepasiekiama
504
Baigėsi laukimo laikas

Klaidų katalogas: ErrorResponse

Antraštės

401

WWW-AuthenticateEilutėNeprivalomas

Serverio reikalaujama tapatybės patvirtinimo schema.

405

AllowEilutėNeprivalomas

Šio ištekliaus palaikomi HTTP metodai.

429, 503

Retry-AfterSveikasis skaičiusNeprivalomas

Mažiausias laukimo laikas prieš kartojant, sekundėmis.

minimum: 0