第一個請求
檢查與商店的連線。依照步驟建立 API 金鑰、取得權杖並傳送第一個請求。
快速開始
- 建立金鑰
- 取得權杖
- 檢查連線
快速開始
-
建立 API 金鑰
在商店管理後台開啟 API 設定,然後建立金鑰。
請將金鑰保存在安全的地方。關閉視窗後,你將無法再次查看它。
建立 API 金鑰
SHOPENTLY_SHOP_URL- 商店的 HTTPS 位址,不含 /api/v1。請將範例替換為您自己的位址。
https://twoj-sklep.exampleSHOPENTLY_API_KEY- 在商店管理面板中產生的金鑰。
身份驗證
cURL 示例中的 SHOPENTLY_SHOP_URL、SHOPENTLY_API_KEY 和 SHOPENTLY_ACCESS_TOKEN 是本機佔位符。請在整合伺服器上私密設定這些變量;切勿在原始碼、瀏覽器頁面、螢幕截圖或日誌中公開真實憑據。
-
取得 · 權杖
POST/api/v1/auth/token使用金鑰取得權杖。後續請求將攜帶這個權杖。
示例
請求示例
cURL
: "${SHOPENTLY_SHOP_URL:?}" response=$(curl --disable --globoff --fail-with-body --silent --show-error \ --proto '=https' --connect-timeout 5 --max-time 30 \ --write-out '\n%{http_code}' \ --request POST \ --header "Authorization: ApiKey ${SHOPENTLY_API_KEY:?}" \ --header 'Content-Type: application/json' \ --data-raw '{}' \ --url "${SHOPENTLY_SHOP_URL%/}"/api/v1/auth/token) || exit 1 status=$(printf '%s' "$response" | tail -n 1) case "$status" in 2??) printf '%s\n' "$response" | sed '$d' ;; *) printf 'HTTP %s\n' "$status" >&2; exit 1 ;; esacPHP
<?php $base = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/'); $origin = parse_url($base); if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) || array_intersect(['user', 'pass', 'path', 'query', 'fragment'], array_keys($origin))) { throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin'); } $credential = getenv('SHOPENTLY_API_KEY') ?: ''; if ($credential === '' || preg_match('/\s/', $credential)) { throw new RuntimeException('Invalid credential'); } $curl = curl_init($base . '/api/v1/auth/token'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => ['Authorization: ApiKey ' . $credential, 'Content-Type: application/json'], CURLOPT_RETURNTRANSFER => true, CURLOPT_FOLLOWLOCATION => false, CURLOPT_PROTOCOLS => CURLPROTO_HTTPS, CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_TIMEOUT => 30, CURLOPT_POSTFIELDS => '{}', ]); $raw = curl_exec($curl); $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE); curl_close($curl); if ($raw === false || $status < 200 || $status >= 300) { throw new RuntimeException('Request failed; HTTP ' . $status); } $result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING); echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT), PHP_EOL;Python
import json import os from urllib.parse import urlsplit import requests base = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/") origin = urlsplit(base) if (origin.scheme != "https" or not origin.hostname or origin.username is not None or origin.path or origin.query or origin.fragment): raise ValueError("SHOPENTLY_SHOP_URL must be an HTTPS origin") credential = os.environ["SHOPENTLY_API_KEY"] if not credential or any(c.isspace() for c in credential): raise ValueError("Invalid credential") response = requests.request( "POST", base + "/api/v1/auth/token", headers={"Authorization": "ApiKey " + credential}, timeout=(5, 30), allow_redirects=False, json={}, ) if not 200 <= response.status_code < 300: raise RuntimeError(f"HTTP {response.status_code}") result = response.json() print(json.dumps(result, ensure_ascii=False, indent=2))回應示例 · HTTP 200
JSON { "data": { "access_token": "EXAMPLE_ACCESS_TOKEN", "expires_at": "2026-01-01T12:00:00Z", "expires_in": 900, "rate_limits": { "auth_per_minute": 10, "read_per_minute": 60, "write_per_minute": 10 }, "token_type": "Bearer" }, "meta": { "request_id": "example" } }回應
data.access_token- 用於 Authorization: Bearer 標頭的權杖。執行獨立範例前,請設定 SHOPENTLY_ACCESS_TOKEN。
data.expires_in- 自簽發起 900 秒,也就是 15 分鐘。傳送請求不會延長有效期限。
data.expires_at- 以 UTC 表示的到期時間。目前的存取限制可能會提早阻擋權杖存取。
data.rate_limits- Engine ≥ 4.143.0. 每次權杖回應都包含核發時商店政策中的 data.rate_limits。所有金鑰共用這些額度;取得新權杖不會重設額度。方案變更可能在權杖到期前生效。
-
檢查與商店的連線
GET/api/v1/context攜帶權杖傳送請求。回應會顯示商店中可用的語言和市場。
請求示例
cURL
: "${SHOPENTLY_SHOP_URL:?}" response=$(curl --disable --globoff --fail-with-body --silent --show-error \ --proto '=https' --connect-timeout 5 --max-time 30 \ --write-out '\n%{http_code}' \ --request GET \ --header "Authorization: Bearer ${SHOPENTLY_ACCESS_TOKEN:?}" \ --url "${SHOPENTLY_SHOP_URL%/}"/api/v1/context) || exit 1 status=$(printf '%s' "$response" | tail -n 1) case "$status" in 2??) printf '%s\n' "$response" | sed '$d' ;; *) printf 'HTTP %s\n' "$status" >&2; exit 1 ;; esacPHP
<?php $base = rtrim(getenv('SHOPENTLY_SHOP_URL') ?: '', '/'); $origin = parse_url($base); if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) || array_intersect(['user', 'pass', 'path', 'query', 'fragment'], array_keys($origin))) { throw new RuntimeException('SHOPENTLY_SHOP_URL must be an HTTPS origin'); } $credential = getenv('SHOPENTLY_ACCESS_TOKEN') ?: ''; if ($credential === '' || preg_match('/\s/', $credential)) { throw new RuntimeException('Invalid credential'); } $curl = curl_init($base . '/api/v1/context'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $credential], CURLOPT_RETURNTRANSFER => true, CURLOPT_FOLLOWLOCATION => false, CURLOPT_PROTOCOLS => CURLPROTO_HTTPS, CURLOPT_CONNECTTIMEOUT => 5, CURLOPT_TIMEOUT => 30, ]); $raw = curl_exec($curl); $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE); curl_close($curl); if ($raw === false || $status < 200 || $status >= 300) { throw new RuntimeException('Request failed; HTTP ' . $status); } $result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING); echo json_encode($result, JSON_THROW_ON_ERROR | JSON_PRETTY_PRINT), PHP_EOL;Python
import json import os from urllib.parse import urlsplit import requests base = os.environ["SHOPENTLY_SHOP_URL"].rstrip("/") origin = urlsplit(base) if (origin.scheme != "https" or not origin.hostname or origin.username is not None 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 any(c.isspace() for c in credential): raise ValueError("Invalid credential") response = requests.request( "GET", base + "/api/v1/context", headers={"Authorization": "Bearer " + credential}, timeout=(5, 30), allow_redirects=False, ) if not 200 <= response.status_code < 300: raise RuntimeError(f"HTTP {response.status_code}") result = response.json() print(json.dumps(result, ensure_ascii=False, indent=2))回應示例 · HTTP 200
JSON { "data": { "base_market_id": "example", "default_locale": "en", "global_enabled": false, "languages": [ { "code": "en", "direction": "ltr", "is_default": true, "name": "English", "native_name": "English", "status": "draft" } ], "markets": [ { "code": "PL", "currency": { "code": "PLN", "minor_units": 2 }, "id": "example", "is_default": true, "name": "Poland", "price_list": null, "status": "draft" } ], "multilingual_enabled": false }, "meta": { "locale": "en", "market_code": "PL", "market_id": "example", "request_id": "example" } }回應
在後續請求中使用傳回的語言和市場識別碼。
如何確認連線成功?
收到包含商店資料的 HTTP 200 回應,即可確認連線正常。
完整程式會在一次執行中取得權杖並讀取商店情境。額外程式碼用於驗證設定、處理傳輸與錯誤。
完整範例
執行範例
你可以在終端機中執行完整範例,也可以使用 PHP 或 Python。
PHP 8.3 (64-bit, ext-curl, JSON) · Python 3.12 + requests · cURL 8 + jq 1.7.
cURL
#!/bin/sh
# POSIX shell, curl 8+, jq 1.7. Credentials stay in environment variables.
set -eu
: "${SHOPENTLY_SHOP_URL:?}"
base=${SHOPENTLY_SHOP_URL%/}
case "$base" in https://*) ;; *) echo 'Use an HTTPS origin' >&2; exit 1;; esac
authority=${base#https://}
case "$authority" in ''|*/*|*\?*|*\#*|*@*) echo 'Use an HTTPS origin' >&2; exit 1;; esac
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT HUP INT TERM
chmod 700 "$work"
encode() { printf '%s' "$1" | jq -sRr @uri; }
api() {
method=$1; path=$2; body=${3-}; key=${4-}
scheme=Bearer; credential=${SHOPENTLY_ACCESS_TOKEN-}
if [ "$path" = /api/v1/auth/token ]; then scheme=ApiKey; credential=${SHOPENTLY_API_KEY-}; fi
[ -n "$credential" ] || { echo 'Missing credential' >&2; return 1; }
set -- --disable --globoff --silent --show-error --proto '=https' --connect-timeout 5 --max-time 30 \
--request "$method" --header "Authorization: $scheme $credential" \
--dump-header "$work/headers" --output "$work/body" --write-out '%{http_code}'
if [ -n "$key" ]; then set -- "$@" --header "Idempotency-Key: $key"; fi
if [ -n "$body" ]; then set -- "$@" --header 'Content-Type: application/json' --data-raw "$body"; fi
status=$(curl "$@" --url "$base$path") || return 1
case "$status" in
2??) if [ -s "$work/body" ]; then jq -e . "$work/body"; else printf 'null\n'; fi ;;
*) printf 'HTTP %s\n' "$status" >&2
jq -c '.error | {code, fields}' "$work/body" >&2 2>/dev/null || true
return 1 ;;
esac
}
token=$(api POST /api/v1/auth/token '{}')
SHOPENTLY_ACCESS_TOKEN=$(printf '%s' "$token" | jq -er '.data.access_token')
export SHOPENTLY_ACCESS_TOKEN
api GET /api/v1/context
PHP
<?php
declare(strict_types=1);
// PHP 8.3+, 64-bit, ext-curl. Credentials stay in environment variables.
function env(string $name): string {
$value = getenv($name);
if ($value === false || $value === '' || strpbrk($value, "\r\n") !== false) {
throw new RuntimeException('Invalid environment variable: ' . $name);
}
return $value;
}
$base = rtrim(env('SHOPENTLY_SHOP_URL'), '/');
$origin = parse_url($base);
if (!$origin || ($origin['scheme'] ?? '') !== 'https' || empty($origin['host']) ||
isset($origin['user']) || isset($origin['pass']) || isset($origin['path']) ||
isset($origin['query']) || isset($origin['fragment']) || PHP_INT_SIZE !== 8) {
throw new RuntimeException('Use a 64-bit PHP runtime and an HTTPS origin');
}
class ApiError extends RuntimeException {
public function __construct(public int $status, public array $headers, public array $error) {
parent::__construct('HTTP ' . $status . '; code=' . ($error['code'] ?? '') .
'; request_id=' . ($headers['x-request-id'] ?? ''));
}
}
function api(string $method, string $path, array $query = [], ?array $body = null, ?string $key = null, bool $apiKey = false): ?array {
global $base;
$credential = env($apiKey ? 'SHOPENTLY_API_KEY' : 'SHOPENTLY_ACCESS_TOKEN');
$headers = ['Authorization: ' . ($apiKey ? 'ApiKey ' : 'Bearer ') . $credential];
if ($key !== null) $headers[] = 'Idempotency-Key: ' . $key;
if ($body !== null) $headers[] = 'Content-Type: application/json';
$url = $base . $path . ($query ? '?' . http_build_query($query, '', '&', PHP_QUERY_RFC3986) : '');
$responseHeaders = [];
$h = curl_init($url);
curl_setopt_array($h, [
CURLOPT_CUSTOMREQUEST => $method, 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 ($h, string $line) use (&$responseHeaders): int {
if (str_contains($line, ':')) {
[$name, $value] = explode(':', $line, 2);
$responseHeaders[strtolower(trim($name))] = trim($value);
}
return strlen($line);
},
]);
if ($body !== null) {
$json = $apiKey && $body === [] ? '{}' : json_encode($body, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
curl_setopt($h, CURLOPT_POSTFIELDS, $json);
}
$raw = curl_exec($h);
$status = curl_getinfo($h, CURLINFO_RESPONSE_CODE);
$error = curl_error($h);
curl_close($h);
if ($raw === false) throw new RuntimeException('Transport error: ' . $error);
if ($status < 200 || $status >= 300) {
$data = json_decode($raw, true);
throw new ApiError($status, $responseHeaders, is_array($data) ? ($data['error'] ?? []) : []);
}
return $raw === '' ? null : json_decode($raw, true, 512, JSON_THROW_ON_ERROR | JSON_BIGINT_AS_STRING);
}
function output(mixed $value): void {
echo json_encode($value, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE), PHP_EOL;
}
$token = api('POST', '/api/v1/auth/token', body: [], apiKey: true)['data'];
putenv('SHOPENTLY_ACCESS_TOKEN=' . $token['access_token']);
output(api('GET', '/api/v1/context'));
Python
"""Run with Python 3.12 and requests. Credentials stay in environment variables."""
import json
import os
import random
import time
from urllib.parse import quote, urlencode, urlsplit
import requests
def env(name):
value = os.environ[name]
if not value or "\r" in value or "\n" in value:
raise ValueError("Invalid environment variable: " + name)
return value
base = env("SHOPENTLY_SHOP_URL").rstrip("/")
origin = urlsplit(base)
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")
class ApiError(RuntimeError):
def __init__(self, response):
self.status = response.status_code
self.request_id = response.headers.get("X-Request-ID", "")
self.retry_after = response.headers.get("Retry-After", "")
try:
self.error = response.json().get("error", {})
except (ValueError, AttributeError):
self.error = {}
super().__init__(f"HTTP {self.status}; code={self.error.get('code', '')}; request_id={self.request_id}")
def api(method, path, *, query=None, body=None, key=None, api_key=False):
credential = env("SHOPENTLY_API_KEY" if api_key else "SHOPENTLY_ACCESS_TOKEN")
headers = {"Authorization": ("ApiKey " if api_key else "Bearer ") + credential}
if key:
headers["Idempotency-Key"] = key
if body is not None:
headers["Content-Type"] = "application/json"
response = requests.request(method, base + path, params=query, headers=headers,
data=json.dumps(body, ensure_ascii=False, allow_nan=False).encode() if body is not None else None,
timeout=(5, 30), allow_redirects=False)
if not 200 <= response.status_code < 300:
raise ApiError(response)
return response.json() if response.content else None
def segment(value):
return quote(value, safe="")
token = api("POST", "/api/v1/auth/token", body={}, api_key=True)["data"]
os.environ["SHOPENTLY_ACCESS_TOKEN"] = token["access_token"]
print(json.dumps(api("GET", "/api/v1/context"), ensure_ascii=False, indent=2))