跳至内容
ShopentlyLearn

获取 — 入库交付

读取“入库交付”的数据。结果取决于此操作的参数。

GET/api/v1/inventory/deliveries/{delivery_id}

身份验证
Bearer
最低套餐
STANDARD
所需权限
inventory.stock_delivery: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/inventory/deliveries/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/inventory/deliveries/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/inventory/deliveries/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",
    "deleted_at": null,
    "delivered_at": "2026-01-01T12:00:00Z",
    "id": "example",
    "increases_stock": true,
    "location_id": "example",
    "notes": "example",
    "quantity": 1,
    "received_at": null,
    "record_status": "active",
    "status": "planned",
    "stock_applied_at": null,
    "target_id": "example",
    "target_type": "product",
    "updated_at": "2026-01-01T12:00:00Z",
    "version": 1,
    "warehouse_id": "example"
  },
  "meta": {
    "request_id": "example"
  }
}

工作原理

  • 交付记录指定产品或变体、仓库、库位、数量、日期和状态。
  • 请明确选择 planned 或 received,并根据预期库存影响设置 increases_stock。
  • 创建已接收交付可能改变库存,因此还必须授予相应的条件性库存权限。
  • 重试同一逻辑交付时保留原始幂等键,避免重复登记。
  • 核对结果时读取 stock_applied_at 和当前库存。

参数

路径参数

delivery_id字符串必填

交付记录标识符。

约束
pattern
"^[a-z0-9][a-z0-9_-]{0,62}$"
示例: "example"

此操作不接受 JSON 请求体。

响应

响应 200

dataDeliveryDetailData 必填

成功响应的数据。

字段 · data
created_at字符串必填

创建时间。

format: "date-time"
deleted_at字符串 null必填

删除时间(如存在)。

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

交付日期和时间。

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

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

increases_stock布尔值必填

接收交付是否增加库存。

location_id字符串必填

仓库库位标识符。

notes字符串 null必填

附加备注。

quantity整数必填

单位数量。

received_at字符串 null必填

接收交付的日期和时间。

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

保存的记录状态。

约束
enum
["active", "deleted"]
status字符串必填

此操作接受的状态。

约束
enum
["planned", "received"]
stock_applied_at字符串 null必填

交付导致的库存变动实际应用的日期和时间。

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

操作影响的产品或变体标识符。

target_type字符串必填

操作针对产品还是变体。

约束
enum
["product", "variant"]
updated_at字符串 null必填

最近更新时间。

字符串:format: "date-time"
version整数必填

用于并发控制的资源版本。

warehouse_id字符串必填

仓库标识符。

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