跳至内容
ShopentlyLearn

折扣 · 获取列表

折扣 · 获取列表. 所有优惠码均须允许叠加。优惠按顺序计算。

GET/api/v1/discounts/coupons

身份验证
Bearer
最低套餐
STANDARD
所需权限
discounts.coupons: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/discounts/coupons

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/discounts/coupons');
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/discounts/coupons', 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": [],
  "meta": {
    "locale": "example",
    "market_code": "example",
    "market_id": "poland",
    "pagination": {
      "has_more": false,
      "limit": 1,
      "next_cursor": null
    },
    "request_id": "learn-example-request"
  }
}

概览

合并所选商品与分类的范围。分类包括直接归属的商品。

参数

查询参数

limit整数可选

此页记录数上限。

minimum: 1maximum: 100
默认值: 50
cursor字符串 null可选

上一页返回的不透明续页值。

字符串:minLength: 1maxLength: 1024
market_id字符串 null可选

上下文端点返回的市场标识符。

约束 · 字符串 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"

此操作不接受 JSON 请求体。

响应

响应 200

data数组 <CampaignData > 必填

成功响应的数据。

字段 · data

CampaignData

audience字符串可选

客户

约束
enum
["all", "guest", "customer", "selected"]

默认值: "all"

benefit_type字符串可选

由允许值说明的数据结构变体。

约束
enum
["percentage", "fixed", "none"]

默认值: "percentage"

category_ids数组 <字符串> 可选

相关分类的标识符。

maxItems: 1000
约束 · 数组 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
code字符串 null可选

稳定的机器可读代码。

约束 · 字符串 1
pattern
"^[A-Za-z0-9]{6,16}$"
combine_coupons布尔值可选

与其他优惠码叠加

默认值: false

combine_promotions布尔值可选

允许此代码用于已参加自动促销的商品

默认值: false

created_at字符串必填

创建时间。

format: "date-time"
created_byCreatorData 必填

创建者

customer_ids数组 <字符串> 可选

此资源记录的客户信息。

maxItems: 1000
约束 · 数组 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
enabled布尔值必填

此设置是否启用。

ends_at字符串 null可选

失效时间

字符串:format: "date-time"
free_shipping布尔值可选

免运费

默认值: false

id字符串必填

资源标识符;请保留返回的原值。

kind字符串必填

由允许值说明的数据结构变体。

约束
enum
["coupon", "promotion"]
markets数组 <shopently_engine__domains__discounts__adapters__public_http__schemas__MarketData > 必填

商店上下文中可用的市场。

minItems: 1maxItems: 1000
minimum_quantity整数可选

购物车最低商品数量

minimum: 1maximum: 2147483647

默认值: 1

name字符串必填

对应上下文中的资源名称。

minLength: 1maxLength: 160
per_customer_limit整数可选

每位客户的使用次数上限

minimum: -1maximum: 2147483647

默认值: -1

percentage字符串可选

百分比

maxLength: 19
约束
pattern
"^(0|[1-9][0-9]{0,13})(\\.[0-9]{1,4})?$"

默认值: "10"

product_ids数组 <字符串> 可选

相关产品的标识符。

maxItems: 1000
约束 · 数组 1
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
product_scope字符串可选

商品

约束
enum
["all", "selected"]

默认值: "all"

show_account布尔值可选

在客户账户中

默认值: false

show_cart布尔值可选

在购物车中

默认值: false

show_product布尔值可选

在商品页面上

默认值: false

starts_at字符串 null可选

生效时间

字符串:format: "date-time"
updated_at字符串必填

最近更新时间。

format: "date-time"
usage_limit整数可选

使用次数上限

minimum: -1maximum: 2147483647

默认值: -1

used_count整数必填

已使用次数

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