변경 이력

호환성 약속

1.x 안에서는 추가만 합니다: 엔드포인트 삭제, 필수화, 기존 필드 의미 변경은 없습니다. 그중 하나라도 필요하면 2.0으로 올리고 1.x는 12개월 더 유지합니다.

• 변경MCP 는 이제 43 개 엔드포인트를 그대로 노출하는 대신 **업무 동작**을 제공합니다: check_stock, find_products, get_statement, quote_order / place_order / cancel_order, quote_dropship / place_dropship / release_dropship. 하나의 동작이 내부적으로 여러 호출을 엮고, 결과로 답(부족분, 금액, 생성된 문서 번호)을 돌려줍니다. 없어진 것은 없습니다: list_endpoints 와 call_endpoint 로 모든 엔드포인트에 동일한 권한으로 접근할 수 있습니다.

• 추가그동안 없던 대사 기능이 추가되었습니다: GET /api/v1/balances, /transactions(거래 후 잔액 포함), /bills, /refunds, /freight-bills. 지금까지는 OMS 웹사이트에서만 볼 수 있어 월말 대사를 수작업으로 해야 했습니다.

• 추가대행 주문에 2단계 흐름이 추가되었습니다: POST /api/v1/dropship-orders/allocation-preview 가 건별로 배정 가능 수량·부족분·입고일·결제 금액을 알려주고, 확인 후 POST /api/v1/dropship-orders/submit 합니다. 미리보기는 재고를 잡아 두므로 제출하지 않기로 했다면 DELETE /api/v1/dropship-orders/{dropship_order_id}/allocation 로 해제하세요.
• 추가도매 주문에도 동일한 조합이 생겼습니다: POST /api/v1/orders/{order_id}/allocation-preview 와 /submit. 결제 수단은 balance / invoice / wechat / alipay 중 선택하며 기본값은 청구서 결제입니다.
• 추가취소 추가: DELETE /api/v1/orders/{order_id} 와 DELETE /api/v1/dropship-orders/{dropship_order_id} — 잡고 있던 재고도 함께 해제합니다(이미 출고된 문서는 취소 불가).
• 변경OMS 계정으로 로그인하면 도매·대행 주문 생성이 OMS 프런트 체인을 따릅니다(판매 가능 카탈로그로 명세를 검증하고, 판매 금지 SKU 는 즉시 거부). 채널 시크릿 로그인은 그대로입니다.

• 추가토큰 교환에 grant_type=password 가 추가되었습니다: OMS 웹사이트 로그인 계정과 비밀번호({username, password})로 토큰을 받고, 권한은 OMS 계정을 따릅니다. 업스트림 세션은 게이트웨이 안에 암호화되어 머뭅니다. 채널 코드 + 시크릿 방식은 그대로입니다.
• 추가GET /api/v1/me 추가: 이 토큰이 누구인지 — 계정, 채널, 사용 가능한 창고, 권한, 업무 스위치.

• 변경전체 인터페이스가 /api/v1/* 로 이동했습니다. 27개 엔드포인트를 하나의 명명 규칙으로 재정의 — 소문자 케밥 복수 명사, 소속 관계는 경로에 (/warehouses/{warehouse_code}/stock), 파라미터·필드는 snake_case, 개념당 이름 하나(용어 사전). 구 /Api/* 경로는 모두 410 과 함께 error.hint 에 새 주소를 돌려줍니다.
• 변경응답 봉투가 성공 시 {data, …}, 실패 시 {error: {code, message, hint, request_id, doc_url}} 로 바뀌었습니다. 성공 여부는 HTTP 상태 코드만 봅니다 — code / result / msg 없음, "sucesss" 없음.
• 변경토큰 교환은 POST /api/v1/auth/token 이며 {client_id, client_secret} 을 본문으로 보냅니다 — 자격 증명이 URL 이나 접근 로그에 남지 않습니다. /api/v1/* 에서는 ?token= 을 더 이상 받지 않고 Authorization: Bearer 만 인정합니다.
• 추가창고 마스터 GET /api/v1/warehouses: 실제 ERP 코드(AUSYD2 / AUSYD1 / CHNZJ1) 와 회사 단위 합계 뷰 두 개(AU / CN). AuStock / SydrhStock 같은 게이트웨이 임의 별칭은 사라졌습니다. 창고 허용 목록은 warehouse_code 를 담은 모든 요청에 적용됩니다.
• 변경재고 필드 이름 변경: sku / product_code / quantity_on_hand / quantity_available / price_wholesale / price_retail / currency, 모든 행에 warehouse_code 포함. 창고 전체·스타일별(?product_code=)·SKU별(?sku=) 조회가 GET /api/v1/warehouses/{warehouse_code}/stock 하나로 합쳐졌습니다.
• 변경주문·예약·장바구니는 lines[{sku, quantity}] (장바구니는 items) 를 사용하고, 드롭쉬핑 주문은 SKU 하나(sku + quantity)이며 수취인은 recipient{name, phone, address, country_code, state, city, postal_code} 객체, 배송 방식은 shipping_method: normal / express 입니다. 요청과 응답의 형태가 같습니다.
• 변경조회는 모두 GET: 주문 / 드롭쉬핑 / 출고 / 예약 목록은 ?start_date=&end_date=; 페이지네이션은 page / page_size 와 응답의 has_more; 드롭쉬핑의 고객 주문번호 / 일련번호 조회는 GET /api/v1/dropship-orders?client_order_number= / ?serial_number= 입니다.
• 변경상태는 실제 ERP 데이터로 확인한 읽기 쉬운 열거형입니다: 도매 주문 draft / confirmed / cancelled, 예약 reserved / cancelled / confirmed, 출고 shipped, 드롭쉬핑 pending / shipped / intercepted / cancelled; 원래 코드는 status_raw 에 남고, 드롭쉬핑 결제는 paid 불리언입니다. 쿼리의 status 도 같은 단어를 씁니다.
• 추가재고 증분 동기화 GET /api/v1/warehouses/{warehouse_code}/stock/changes: 커서 이후 변경된 행만 반환. 응답 {data, version, since, latest, has_more, needs_full_sync}, 커서는 X-Stock-Version 헤더에도 담깁니다.
• 추가Webhook stock.changed / order.created: 페이로드 {event_id, type, channel_code, occurred_at, data}, X-Ever-Signature 서명. 실패 시 30초→2분→10분→1시간→6시간 재시도, 6회 후 데드레터.
• 추가쓰기 엔드포인트가 Idempotency-Key 헤더를 지원하며, 모든 응답에 X-API-Version / X-Request-Id 가 포함됩니다.
• 추가원격 MCP POST /mcp, CLI ever (ever login --sandbox, ever stock changes AU --since 0), AI용 /llms.txt 와 모든 페이지의 Markdown. 도구 이름은 어디서나 resource_action (stock_list, order_create …) 입니다.
• 변경속도 제한은 포인트 기준: 기본 600포인트/분. 창고 전체 조회 60(페이지 시 5), 상품 목록 30, 증분 동기화는 실제 반환 건수(최신 상태면 1), 쓰기 2.
• 지원 종료구 게이트웨이에서 발급한 토큰은 2026-11-30까지 인정되며, 이후에는 이 사이트의 시크릿으로 교환한 토큰만 인정됩니다.