수주 등록 요청

Endpoint

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

인증

연동관리에서 발급한 Customer API key를 서버 secret으로 저장하고 Bearer header로 전달합니다. 고객 key에는 선택형 또는 신규 scope가 없습니다.

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

수주 등록 요청

기존 RegistContract schema와 거래처·품목 코드 lookup으로 근거 있게 변환할 수 있는 필드만 받습니다. 미등록 코드는 명시적으로 실패합니다.

{
  "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
    }
  ]
}

자사몰 주문 생성 backend

주문 DB commit 성공 직후 아래 Node.js/Axios 함수를 한 번 호출합니다. API key를 browser, 앱, 공개 저장소 또는 주문 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는 필수지만 신규 ledger가 없어 영속 replay와 동시 중복 방지를 보장하지 않습니다.
• timeout/5xx 후 자동 재전송하지 말고 MES 생성 여부를 먼저 확인합니다.
• 요청당 품목 100개, body 256 KiB, IP당 초당 1요청(burst 10)으로 제한합니다.