受注登録request

Endpoint

POST https://open-api.orca.partners/v1/sales-orders

認証

連携管理で発行したCustomer API keyをserver secretに保存し、Bearer headerで送信します。Customer keyに新しいscopeはありません。

• Authorization: Bearer <customer-api-key>
• Idempotency-Key: <external-order-derived-key>
• Content-Type: application/json

受注登録request

既存RegistContract schemaと取引先・品目code lookupで変換できるfieldのみ受け付けます。未登録codeは明示的に失敗します。

{
  "source_type": "own_mall",
  "source_channel_id": "42",
  "external_order_id": "ORDER-2026-00042",
  "order_name": "Own mall ORDER-2026-00042",
  "ordered_at": "2026-08-18T00:00:00Z",
  "expected_delivery_at": "2026-08-22T00:00:00Z",
  "vendor_code": "ONLINE-CUSTOMER",
  "currency": "KRW",
  "shipping_address": "110 Sejong-daero, Seoul",
  "items": [
    {
      "item_code": "FINISHED-001",
      "quantity": 2,
      "unit_price": 12000
    }
  ]
}

自社EC注文作成backend

注文DB commit成功直後にNode.js/Axios関数を一度だけ呼び出します。keyをbrowser、app、公開repository、注文DBに保存しないでください。

// Node.js backend only — run after the order DB commit.
const axios = require("axios");
const { createHash } = require("crypto");

async function sendCommittedOrderToOrca(order) {
  const apiKey = process.env.ORCA_API_KEY;
  const sourceChannelId = process.env.ORCA_SOURCE_CHANNEL_ID;
  if (!apiKey || !sourceChannelId) {
    throw new Error(
      "ORCA_CONFIG_ERROR: ORCA_API_KEY and ORCA_SOURCE_CHANNEL_ID are required"
    );
  }

  const startedAt = Date.now();
  const idempotencyKey = `own-mall:${createHash("sha256")
    .update(String(order.id))
    .digest("hex")}`;
  const payload = {
    source_type: "own_mall",
    source_channel_id: sourceChannelId,
    external_order_id: String(order.id),
    order_name: `Own mall ${order.id}`,
    ordered_at: order.orderedDate,
    expected_delivery_at: order.expectedDeliveryDate,
    vendor_code: order.orcaVendorCode,
    currency: order.currency,
    shipping_address: order.deliveryAddress || undefined,
    items: order.items.map((item) => ({
      item_code: item.orcaItemCode,
      quantity: item.quantity,
      unit_price: item.unitPrice,
    })),
  };

  try {
    const response = await axios.post(
      "https://open-api.orca.partners/v1/sales-orders",
      payload,
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Idempotency-Key": idempotencyKey,
          "Content-Type": "application/json",
        },
        timeout: 10000,
      }
    );
    return response.data;
  } catch (error) {
    const status = error.response?.status ?? null;
    const code =
      error.response?.data?.err?.errorCode ??
      (error.code === "ECONNABORTED"
        ? "ORCA_TIMEOUT"
        : "ORCA_REQUEST_FAILED");
    const failure = new Error(
      `ORCA_ORDER_CREATE_FAILED stage=post-commit status=${status ?? "none"} ` +
        `code=${code} elapsed_ms=${Date.now() - startedAt}`
    );
    failure.cause = error;
    throw failure;
  }
}

module.exports = { sendCommittedOrderToOrca };

運用ルール

• Idempotency-Keyは必須ですが、永続replayと同時重複防止は保証されません。
• timeout/5xx後は再送前にMES作成結果を確認します。
• 1 requestあたり100 items、256 KiB、IPごとに1 request/秒（burst 10）です。