写真プリント API 連携 — 技術仕様

canonical = HTTPメソッド + "\n"
          + パス（クエリを含まない） + "\n"
          + タイムスタンプ + "\n"
          + hex(sha256(リクエストボディ))

signature = hex(hmac_sha256(シークレット, canonical))

{
  "external_order_id": "SO-2026-000123",
  "size": "L",
  "paper": "standard",
  "border": false,
  "shipping_method": "nekopos",
  …
}

{
  "combinations": [
    {
      "size": "L",
      "paper": "standard",
      "border": false,
      "intake_px": { "short": 1075, "long": 1524 },
      "shipping": [
        { "method": "nekopos",   "max_quantity": 300 },
        { "method": "takkyubin", "max_quantity": 5000 }
      ]
    }
  ]
}

{
  "external_order_id": "SO-2026-000123",
  "size": "L",
  "paper": "standard",
  "border": false,
  "shipping_method": "nekopos",
  "recipient": {
    "name": "山田 太郎",
    "postal_code": "1000001",
    "prefecture": "東京都",
    "city": "千代田区",
    "address_line1": "千代田1-1-1",
    "address_line2": "サンプルマンション101",
    "phone": "0312345678"
  },
  "photos": [
    {
      "index": 1,
      "quantity": 2,
      "width": 1075,
      "height": 1524,
      "byte_size": 812345,
      "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    }
  ]
}

{
  "intake_id": "itk_01K3XQ8ZP4M2",
  "status": "awaiting_upload",
  "expires_at": "2026-08-05T01:22:33Z",
  "uploads": [
    {
      "index": 1,
      "method": "PUT",
      "url": "https://...署名付き...",
      "headers": { "Content-Type": "image/jpeg" },
      "expires_at": "2026-08-05T01:22:33Z"
    }
  ]
}

curl -sS -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @001.jpg

import { readFile } from 'node:fs/promises'

async function upload(u: { url: string; headers: Record<string, string> }, file: string) {
  const res = await fetch(u.url, {
    method: 'PUT',
    headers: u.headers,
    body: await readFile(file),
  })
  if (!res.ok) throw new Error(`upload failed: ${res.status}`)
}

// 並列度は 8 程度を推奨（多すぎても速くなりません）
const intake = await call('POST', '/partner/v1/intakes', order)
await Promise.all(intake.uploads.map((u) => upload(u, `${u.index}.jpg`)))
await call('POST', `/partner/v1/intakes/${intake.intake_id}/commit`)

import urllib.request

def upload(u, path):
    with open(path, "rb") as f:
        req = urllib.request.Request(u["url"], data=f.read(), method="PUT", headers=u["headers"])
        with urllib.request.urlopen(req) as r:
            if r.status not in (200, 201):
                raise RuntimeError(f"upload failed: {r.status}")

intake = call("POST", "/partner/v1/intakes", order)
for u in intake["uploads"]:
    upload(u, f"{u['index']}.jpg")
call("POST", f"/partner/v1/intakes/{intake['intake_id']}/commit")

{
  "intake_id": "itk_01K3XQ8ZP4M2",
  "external_order_id": "SO-2026-000123",
  "status": "accepted",
  "accepted_at": "2026-08-04T02:41:10Z"
}

{
  "intake_id": "itk_01K3XQ8ZP4M2",
  "external_order_id": "SO-2026-000123",
  "status": "shipped",
  "shipping_method": "nekopos",
  "tracking_number": "123456789012",
  "shipped_at": "2026-08-05T08:15:00Z"
}

{
  "events": [
    {
      "event_id": "evt_01K3XR2A7Q",
      "type": "intake.shipped",
      "created_at": "2026-08-05T08:15:00Z",
      "data": {
        "intake_id": "itk_01K3XQ8ZP4M2",
        "external_order_id": "SO-2026-000123",
        "shipping_method": "nekopos",
        "tracking_number": "123456789012"
      }
    }
  ],
  "next_cursor": "evt_01K3XR2A7Q",
  "has_more": false
}

# 前回の続きから取得する。cursor は自社側で保存しておく。
CURSOR=$(cat ./cursor.txt 2>/dev/null)
REQ_PATH="/partner/v1/events"

# 署名にクエリ文字列は含めません（パスのみ）
TS=$(date +%s)
BODY_HASH=$(printf '' | openssl dgst -sha256 -hex | awk '{print $NF}')
CANON=$(printf 'GET\n%s\n%s\n%s' "$REQ_PATH" "$TS" "$BODY_HASH")
SIG=$(printf '%s' "$CANON" | openssl dgst -sha256 -hmac "$TOKUPURI_API_SECRET" -hex | awk '{print $NF}')

curl -sS "$TOKUPURI_ORIGIN$REQ_PATH?since=$CURSOR&limit=100" \
  -H "X-Tokupuri-Key: $TOKUPURI_API_KEY" \
  -H "X-Tokupuri-Timestamp: $TS" \
  -H "X-Tokupuri-Signature: $SIG"

// cursor は自社の DB などに永続化してください。
async function poll(cursor?: string) {
  let next = cursor

  for (;;) {
    const qs = next ? `?since=${encodeURIComponent(next)}&limit=100` : '?limit=100'
    // 署名にクエリ文字列は含めないため、パスだけを渡します
    const page = await call('GET', '/partner/v1/events', undefined, qs)

    for (const ev of page.events) {
      if (await alreadyHandled(ev.event_id)) continue
      await handle(ev)              // 発送通知の処理
      await markHandled(ev.event_id)
    }

    // ⚠️ 処理し終えてからカーソルを進める
    next = page.next_cursor
    await saveCursor(next)

    if (!page.has_more) return next
  }
}

# cursor は自社の DB などに永続化してください。
def poll(cursor=None):
    nxt = cursor

    while True:
        qs = f"?since={nxt}&limit=100" if nxt else "?limit=100"
        # 署名にクエリ文字列は含めないため、パスだけを渡します
        page = call("GET", "/partner/v1/events", query=qs)

        for ev in page["events"]:
            if already_handled(ev["event_id"]):
                continue
            handle(ev)                 # 発送通知の処理
            mark_handled(ev["event_id"])

        # ⚠️ 処理し終えてからカーソルを進める
        nxt = page["next_cursor"]
        save_cursor(nxt)

        if not page["has_more"]:
            return nxt

{
  "event_id": "evt_01K3XR2A7Q",
  "type": "intake.shipped",
  "created_at": "2026-08-05T08:15:00Z",
  "data": {
    "intake_id": "itk_01K3XQ8ZP4M2",
    "external_order_id": "SO-2026-000123",
    "shipping_method": "nekopos",
    "tracking_number": "123456789012"
  }
}

# canonical = タイムスタンプ + "\n" + hex(sha256(受信したボディ))
# signature = hex(hmac_sha256(webhook_secret, canonical))
#
# 送られるヘッダ:
#   X-Tokupuri-Timestamp: 1785808500
#   X-Tokupuri-Signature: 3f2a...

import { createHash, createHmac, timingSafeEqual } from 'node:crypto'

export function verify(rawBody: Buffer, ts: string, sig: string, secret: string) {
  // 5分より古いものは再送攻撃として捨てる
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false

  const canonical = ts + '\n' + createHash('sha256').update(rawBody).digest('hex')
  const expected = createHmac('sha256', secret).update(canonical).digest('hex')

  const a = Buffer.from(expected, 'hex')
  const b = Buffer.from(sig, 'hex')
  return a.length === b.length && timingSafeEqual(a, b)
}

// ⚠️ rawBody は JSON パース前の生バイト列を渡すこと。
//    パース後に再シリアライズすると検証は必ず失敗します。

import hashlib, hmac, time

def verify(raw_body: bytes, ts: str, sig: str, secret: str) -> bool:
    # 5分より古いものは再送攻撃として捨てる
    if abs(time.time() - int(ts)) > 300:
        return False

    canonical = (ts + "\n" + hashlib.sha256(raw_body).hexdigest()).encode("utf-8")
    expected = hmac.new(secret.encode("utf-8"), canonical, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

# ⚠️ raw_body は JSON パース前の生バイト列を渡すこと。
#    パース後に再シリアライズすると検証は必ず失敗します。

{
  "code": "INTAKE_VALIDATION_FAILED",
  "message": "3 枚目の寸法が規定と一致しません",
  "retryable": true,
  "photos": [
    {
      "index": 3,
      "code": "DIMENSION_MISMATCH",
      "expected": "1075x1524",
      "actual": "1080x1440"
    }
  ]
}