주문은 넣고, 송장은 바로 받고

1. 01
   키 만들기

   담칸 고객 화면 → 연동 → API·웹훅에서 키를 만듭니다. (회사 관리자, 'API·웹훅' 기능)

2. 02
   키 확인

   GET /me 를 불러 회사·권한이 맞는지 봅니다.

3. 03
   주문 넣고 송장 받기

   POST /orders 로 주문을 넣고, 웹훅이나 GET /orders 로 송장을 받습니다.

curl https://damkan.com/api/v1/me \
  -H "Authorization: Bearer dk_live_…"

모든 요청·응답은 UTF-8 JSON 입니다. 성공하면 { "data": … }, 실패하면 { "error": { "code", "message" } } — message 는 사람이 읽는 한국어 설명입니다. 시각은 ISO 8601(UTC), 날짜는 YYYY-MM-DD 입니다.

머리글 Authorization: Bearer dk_live_… 로 보냅니다. 키는 만들 때 한 번만 보이고 담칸은 원문을 저장하지 않습니다. 새거나 쓸모없어진 키는 고객 화면에서 바로 끄면 그 순간부터 막힙니다.

• read조회 — 주문·입고·재고·품목·창고·택배사를 읽습니다.
• orders주문 등록·취소 — 출고 주문을 넣고, 작업 전 주문을 취소합니다.
• inbounds입고 예정 등록 — 들어올 물건(입고 예정)을 미리 알려 줍니다.
• items품목 등록·수정 — 품목 코드(SKU) 기준으로 새로 넣거나 고칩니다.

3PL(물류 대행) 은 화주사마다 키를 따로 만들 수 있습니다. 화주사 키는 그 화주사 주문·재고만 보이고 shipperCode 를 보내지 않아도 됩니다. 회사 전체 키는 주문·입고·품목마다 shipperCode 를 넣습니다. 자사 물류 회사는 화주사 코드가 필요 없습니다.

여러 쇼핑몰 주문을 한 곳에 모으는 프로그램을 쓰신다면, 그 프로그램이 주문을 담칸으로 넘기고 송장을 돌려받게 하면 됩니다.

1. 1. 그 프로그램의 외부 창고(WMS·3PL) 연동 메뉴나 연동 담당에게 이 문서 주소(https://damkan.com/developers)와 키를 전달합니다.
2. 2. 주문은 POST /orders — 그쪽 주문번호를 orderNo 로 넣으면 같은 주문이 두 번 들어가지 않습니다.
3. 3. 송장은 웹훅 order.shipped 로 바로 받거나, GET /orders?status=shipped&since=… 로 가져갑니다.
4. 4. 쇼핑몰 재고는 GET /stocks 의 available 로 맞춥니다.

담칸은 위 회사들과 별도 제휴 관계가 아니며, 각 회사 이름은 연결 방법을 설명하려고만 씁니다. 그쪽에 외부 창고 연동 기능이 없으면 주문 내보내기·Make·n8n 같은 중간 연결 서비스로 이 API 를 부를 수 있습니다. 직접 연결이 어려우면 지금처럼 엑셀 올리기도 그대로 됩니다.

• order.shipped출고 확정 — 택배사·송장 번호가 함께 갑니다. 쇼핑몰·통합 관리 프로그램에 송장을 넣을 때 씁니다.
• order.received주문 접수 — API·엑셀·직접 등록 등 어떤 길로든 출고 주문이 새로 들어왔을 때.
• order.canceled주문 취소 — 창고나 API 로 주문이 취소됐을 때.
• order.short재고 부족 — 출고 준비를 하려는데 재고가 모자라 멈췄을 때.
• inbound.done입고 완료 — 검수·적치가 끝나 재고가 늘었을 때. 들어온 수량·불량 수량이 함께 갑니다.

POST https://받는-주소
Content-Type: application/json
X-Damkan-Event: order.shipped
X-Damkan-Delivery: whd_…
X-Damkan-Signature: t=1760859660,v1=5f2c…

{
  "id": "whd_…",
  "event": "order.shipped",
  "createdAt": "2026-10-19T07:41:00.000Z",
  "company": { "slug": "hanbit", "name": "한빛로지스" },
  "data": {
    "no": "OUT-261019-0012",
    "orderNo": "SB-20261019-0001",
    "status": "shipped",
    "carrier": { "code": "CJ", "name": "CJ대한통운" },
    "trackingNo": "6012345678901",
    "shippedAt": "2026-10-19T07:41:00.000Z",
    "lines": [ { "sku": "BREW-200", "name": "콜드브루 200ml", "qty": 2 } ]
  }
}

• 받는 쪽이 10초 안에 2xx 로 답하면 성공입니다. 아니면 1분·5분·30분·2시간·6시간 뒤 다시 보내고, 연속 20번 실패하면 그 웹훅을 끄고 고객 화면에 알립니다.
• 다른 주소로 넘기기(3xx)는 따라가지 않습니다. 회사 내부망·사설 IP 로는 보내지 않습니다.
• 같은 알림이 두 번 갈 수 있으니 본문의 id 로 한 번만 처리해 주세요. 순서는 꼭 맞지 않을 수 있어 data.changedAt 을 함께 보세요.
• 주문 알림의 data 는 GET /orders/{번호} 와 같은 모양입니다 (받는 분은 이름만).

서명 확인

X-Damkan-Signature: t=초,v1=서명 — 서명은 웹훅 비밀값(whsec_…)으로 "초.본문" 을 HMAC-SHA256 한 16진수입니다.

// Node.js (Express) — 받은 알림이 담칸에서 온 것인지 확인
app.post("/damkan", express.raw({ type: "application/json" }), (req, res) => {
  const raw = req.body.toString("utf8");
  const [t, v1] = req.get("x-damkan-signature").split(",").map((p) => p.split("=")[1]);
  const mine = crypto.createHmac("sha256", process.env.DAMKAN_WEBHOOK_SECRET).update(`${t}.${raw}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300; // 5분 넘은 것은 버림
  if (!fresh || !crypto.timingSafeEqual(Buffer.from(mine), Buffer.from(v1))) return res.sendStatus(401);
  const evt = JSON.parse(raw);
  // 같은 알림이 두 번 올 수 있습니다 — evt.id 로 한 번만 처리하세요
  res.sendStatus(200);
});

키 하나에 1분 120번까지 부를 수 있습니다. 한 번에 주문 100건 · 입고 50건 · 품목 500건까지, 본문은 1MB 까지입니다. 여러 건을 보낼 때 하나라도 틀리면 아무것도 들어가지 않고, message 에 몇 번째가 왜 틀렸는지 나옵니다. 모든 호출은 고객 화면의 호출 기록에 30일 남습니다.

버전 v1 · 2026-10-19 처음 공개. 항목을 더할 때는 기존 항목을 바꾸지 않고 덧붙입니다. 궁금한 점은 문의하기로 알려 주세요.