Sales-order request

Endpoint

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

Authentication

Store the Customer API key issued in Integration Management as a server secret and send it as Bearer authentication. Customer keys have no selectable or new scopes.

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

Sales-order request

Only fields grounded in the existing RegistContract schema and vendor/item code lookup are accepted. Missing mappings fail explicitly.

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

Own-mall order-created backend

Call this Node.js/Axios function once, immediately after the order database commit succeeds. Never expose the key to a browser, app, public repository, or order database.

// 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 };

Operational rules

• Idempotency-Key is required, but no new ledger guarantees persistent replay or concurrency-safe deduplication.
• After a timeout or 5xx, confirm MES creation before any manual resend.
• Limits: 100 items and 256 KiB per request; one request/second per IP with burst 10.