コンテンツにスキップ
ShopentlyLearn

取得 — 返品・苦情・交換

「返品・苦情・交換」のデータを取得します。結果はこの操作のパラメーターによって決まります。

GET/api/v1/requests/{request_id}

認証
Bearer
利用可能な最低プラン
BASIC
必要な権限
returns.request:read

コード例

リクエスト例

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))

レスポンス例 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"
  }
}

仕組み

  • コレクションと詳細エンドポイントから、申請番号・種類、関連注文、申請対象商品、顧客情報、返金情報を取得します。
  • 有効な種類は return、exchange、complaint です。
  • ステータス識別子は /api/v1/request-statuses から取得します。
  • ステータスと返金額は、別々にバージョンを確認する書き込みです。
  • 記録上の返金額を変えても申請レコードが更新されるだけで、送金は行われません。

パラメーター

パスパラメーター

request_id文字列必須

申請識別子。レスポンスのメタデータでは HTTP リクエストを識別します。

制約
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
例: "example"

この操作は JSON 本文を受け付けません。

レスポンス

レスポンス 200

dataRequestDetailData 必須

成功レスポンスのデータ。

フィールド · data
created_at文字列必須

作成時刻。

format: "date-time"
customerRequestCustomerData 必須

このリソースに記録された顧客情報。

フィールド · customer
email文字列必須

メールアドレス。

name文字列必須

該当コンテキストでのリソース名。

id文字列必須

リソース識別子。返された値をそのまま保持してください。

items配列 <RequestItemData > 必須

リソースに含まれる項目。

フィールド · items
number文字列必須

人向けの注文番号または申請番号。

order_id文字列必須

関連する注文の識別子。

order_number文字列必須

関連する注文番号。

products_valueMoneyData 必須

注文内の商品の金額。

フィールド · products_value
amount文字列必須

JSON 文字列として表した10進数の金額。null は許可される場合のみ。

currency文字列必須

金額の通貨コード。

制約
pattern
"^[A-Z]{3}$"
minor_units整数必須

通貨で使用する小数桁数。

minimum: 0maximum: 4
refundRefundData 必須

記録上の返金情報。

フィールド · refund
amountMoneyData null必須

JSON 文字列として表した10進数の金額。null は許可される場合のみ。

completed_at文字列 null必須

完了時刻。

文字列:format: "date-time"
status文字列必須

この操作で受け付けるステータス。

制約
enum
["pending", "completed"]
updated_at文字列 null必須

最終更新時刻。

文字列:format: "date-time"
version整数必須

同時更新制御に使うリソースバージョン。

resolution_state文字列必須

顧客申請の解決状態。

制約
enum
["unknown", "open", "completed", "rejected", "cancelled"]
statusRequestStatusData 必須

この操作で受け付けるステータス。

フィールド · status
id文字列必須

リソース識別子。返された値をそのまま保持してください。

locale文字列必須

このリクエストで選択した言語。

name文字列 null必須

該当コンテキストでのリソース名。

typeRequestType 必須

リソース種別。

updated_at文字列必須

最終更新時刻。

format: "date-time"
version整数必須

同時更新制御に使うリソースバージョン。

metaContextPageMeta ContextMeta PageMeta RequestMeta 必須

レスポンスのメタデータ。

フィールド · meta

ContextPageMeta

locale文字列必須

このリクエストで選択した言語。

market_code文字列必須

コンテキストエンドポイントが返した市場コード。

market_id文字列必須

コンテキストエンドポイントが返した市場識別子。

paginationPagination 必須

カーソルによるページ分割のメタデータ。

request_id文字列必須

申請識別子。レスポンスのメタデータでは HTTP リクエストを識別します。

minLength: 1maxLength: 100

ContextMeta

locale文字列必須

このリクエストで選択した言語。

market_code文字列必須

コンテキストエンドポイントが返した市場コード。

market_id文字列必須

コンテキストエンドポイントが返した市場識別子。

request_id文字列必須

申請識別子。レスポンスのメタデータでは HTTP リクエストを識別します。

minLength: 1maxLength: 100

PageMeta

paginationPagination 必須

カーソルによるページ分割のメタデータ。

request_id文字列必須

申請識別子。レスポンスのメタデータでは HTTP リクエストを識別します。

minLength: 1maxLength: 100

RequestMeta

request_id文字列必須

申請識別子。レスポンスのメタデータでは HTTP リクエストを識別します。

minLength: 1maxLength: 100
レスポンス例

HTTP ステータス

200
成功 スキーマ
400
無効なリクエスト
401
認証が必要です
403
権限がありません
404
リソースが見つかりません
409
バージョンの競合
422
検証エラー
429
リクエスト上限を超過
その他の HTTP ステータス (7)
405
許可されていないメソッド
413
リクエストが大きすぎます
415
未対応の形式
500
サーバーエラー
502
API ゲートウェイエラー
503
サービスを利用できません
504
タイムアウト

エラー一覧: ErrorResponse

ヘッダー

401

WWW-Authenticate文字列任意

サーバーが要求する認証方式。

405

Allow文字列任意

このリソースが対応する HTTP メソッド。

429, 503

Retry-After整数任意

再試行までに最低限待つ秒数。

minimum: 0