资源

批量导入

批量导入 的每一个端点，附带它强制要求的作用域、它接受的请求体、一份可读的响应，以及它可能返回的拒绝。

启动异步批量导入。

post/organizations/{organization}/imports
作用域
passports:write
Idempotency-Key
接受
返回
202

路径参数

organizationstring必填

本次请求代为操作的组织。密钥必须已获得该组织的授权。

请求体

rowsarray of objects必填

1 到 500 行。超出上限会以专门的 max_rows 规则拒绝，分批循环正是依据这条拒绝来分支的。行内任何位置出现无法识别的键都算错误，而不会被悄悄丢弃。

categorystring必填

来自 GET /categories 的类别 id。

dataobject必填

护照文档，格式与 POST /passports 所接受的完全一致。

external_idstring可选

您为该行指定的标识符。它会在逐行结果中原样返回，失败的行正是据此对账的。

错误

该端点可能返回的全部拒绝，以及它们所带的 HTTP 状态码。

请求
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "external_id": "SKU-4471-BLK",
      "category": "textile",
      "data": {
        "product_name": "Merino Crew Neck",
        "manufacturer_country": "FR"
      }
    },
    {
      "external_id": "SKU-4471-NVY",
      "category": "textile",
      "data": {
        "product_name": "Merino Crew Neck Navy",
        "manufacturer_country": "FR"
      }
    }
  ]
}'
响应 · 202
{
  "object": "import_job",
  "id": "7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "livemode": true,
  "status": "queued",
  "total_rows": 2,
  "succeeded_rows": 0,
  "failed_rows": 0,
  "pending_rows": 2,
  "attempts": 0,
  "created_at": "2026-08-02T09:50:00.114Z",
  "started_at": null,
  "completed_at": null
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports

列出导入任务。

get/organizations/{organization}/imports
作用域
passports:read
Idempotency-Key
不接受
返回
200

路径参数

organizationstring必填

本次请求代为操作的组织。密钥必须已获得该组织的授权。

查询参数

limitstring可选

返回多少条记录。服务端返回的条数可能更少。

cursorstring可选

上一页返回的 next_cursor。游标会编码签发时所用的筛选条件，改用其他筛选条件发送会被 cursor_invalid 拒绝。

statusstring可选

仅返回处于该状态的任务。

错误

该端点可能返回的全部拒绝，以及它们所带的 HTTP 状态码。

请求
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports?status=completed" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
响应 · 200
{
  "object": "list",
  "data": [
    {
      "object": "import_job",
      "id": "7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "livemode": true,
      "status": "completed",
      "total_rows": 2,
      "succeeded_rows": 1,
      "failed_rows": 1,
      "pending_rows": 0,
      "attempts": 1,
      "created_at": "2026-08-02T09:50:00.114Z",
      "started_at": "2026-08-02T09:50:03.902Z",
      "completed_at": "2026-08-02T09:50:05.441Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports?status=completed

获取单个导入任务及其进度。

get/organizations/{organization}/imports/{id}
作用域
passports:read
Idempotency-Key
不接受
返回
200

路径参数

organizationstring必填

本次请求代为操作的组织。密钥必须已获得该组织的授权。

idstring必填

资源的标识符。请把它当作不可解析的字符串处理。

查询参数

row_limitstring可选

随任务一并返回多少条逐行结果。

after_row_indexstring可选

返回该行序号之后的逐行结果，便于分段遍历大型任务。

错误

该端点可能返回的全部拒绝，以及它们所带的 HTTP 状态码。

请求
curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a?row_limit=50" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"
响应 · 200
{
  "object": "import_job",
  "id": "7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "livemode": true,
  "status": "completed",
  "total_rows": 2,
  "succeeded_rows": 1,
  "failed_rows": 1,
  "pending_rows": 0,
  "attempts": 1,
  "created_at": "2026-08-02T09:50:00.114Z",
  "started_at": "2026-08-02T09:50:03.902Z",
  "completed_at": "2026-08-02T09:50:05.441Z",
  "rows": {
    "object": "list",
    "data": [
      {
        "object": "import_row",
        "row_index": 0,
        "external_id": "SKU-4471-BLK",
        "status": "succeeded",
        "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
        "passport_name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
        "error": null,
        "processed_at": "2026-08-02T09:50:04.771Z"
      },
      {
        "object": "import_row",
        "row_index": 1,
        "external_id": "SKU-4471-NVY",
        "status": "failed",
        "passport_id": null,
        "passport_name": null,
        "error": {
          "code": "unknown_category",
          "detail": null
        },
        "processed_at": "2026-08-02T09:50:05.180Z"
      }
    ],
    "has_more": false,
    "next_after_row_index": null
  }
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a?row_limit=50

批量导入 — PassportCraft API 参考 | PassportCraft