Ninjabuy 로고Business
영업팀에 문의
카탈로그 API2026-11프리뷰

동기화 규칙

중국 판매자가 가격을 바꾸거나 품절될 때 내 상품에 일어나는 일.
  • 주문이 들어올 때와 정기 일정에 따라 상품을 다시 읽어요. 각 상품의 last_checked_at에 마지막으로 읽은 시각이 있어요. 상품 동기화는 무료예요.
  • 저희가 조치한 모든 변경은 이벤트로도 발생해요: product.cost_changed와 product.out_of_stock.
엔드포인트

Sync rule 객체

idstring
rule_로 시작해요. 기본 규칙은 rule_default예요.
applies_tostring
기본 규칙이면 all, 개별 규칙이면 상품 ID.
on_cost_increase.actionstring
마진을 지키도록 가격 변경, 상품 일시 중지, 또는 알림만.
on_cost_increase.keep_margin_percentstring
reprice일 때: 판매 가격 대비 지킬 마진.
on_cost_increase.max_increase_percentstring|null
reprice일 때: 한 번에 올릴 수 있는 최대 가격 인상. 넘으면 above_max가 적용돼요: pause 또는 notify.
on_cost_decreasestring
keep_price 또는 같은 마진까지 가격 인하.
on_out_of_stockstring
항상 zero_stock: 품절된 SKU는 채널에서 0으로 표시돼요.
on_back_in_stockstring
restock 또는 재개할 때까지 stay_paused.
round_tostring|null
가격 변경 시 끝자리(.99, .00 등).
sync_rule
{
  "id": "rule_default",
  "applies_to": "all",
  "on_cost_increase": {
    "action": "reprice",
    "keep_margin_percent": "30",
    "max_increase_percent": "15",
    "above_max": "pause"
  },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "restock",
  "round_to": ".99",
  "updated_at": "2026-11-02T08:00:00Z"
}

동기화 규칙 목록

GET/v1/sync_rules

기본 규칙 먼저, 그다음 상품별 개별 규칙 전체.

범위products:read

curl "https://www.ninjabuy.com/api/v1/sync_rules" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "data": [
    {
      "id": "rule_default",
      "applies_to": "all",
      "on_cost_increase": {
        "action": "reprice",
        "keep_margin_percent": "30",
        "max_increase_percent": "15",
        "above_max": "pause"
      },
      "on_cost_decrease": "keep_price",
      "on_out_of_stock": "zero_stock",
      "on_back_in_stock": "restock",
      "round_to": ".99",
      "updated_at": "2026-11-02T08:00:00Z"
    },
    {
      "id": "rule_9p3e",
      "applies_to": "prd_1x0a",
      "on_cost_increase": { "action": "pause" },
      "on_cost_decrease": "keep_price",
      "on_out_of_stock": "zero_stock",
      "on_back_in_stock": "stay_paused",
      "round_to": null,
      "updated_at": "2026-11-03T10:14:00Z"
    }
  ],
  "has_more": false,
  "cursor": null
}

동기화 규칙 조회

GET/v1/sync_rules/{id}

규칙 하나.

범위products:read

경로 매개변수

idstring필수
규칙 ID.

오류

상태유형시점
404not-found이 계정에 해당 규칙이 없어요.
curl "https://www.ninjabuy.com/api/v1/sync_rules/rule_default" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{
  "id": "rule_default",
  "applies_to": "all",
  "on_cost_increase": {
    "action": "reprice",
    "keep_margin_percent": "30",
    "max_increase_percent": "15",
    "above_max": "pause"
  },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "restock",
  "round_to": ".99",
  "updated_at": "2026-11-02T08:00:00Z"
}

상품별 개별 규칙

POST/v1/sync_rules

개별 규칙이 있는 상품은 기본 규칙 대신 그 규칙을 따라요. 생략한 필드는 기본 규칙 값을 사용해요.

범위products:write

본문

applies_tostring필수
기본 규칙이면 all, 개별 규칙이면 상품 ID.
on_cost_increase.actionstring
마진을 지키도록 가격 변경, 상품 일시 중지, 또는 알림만.
on_cost_increase.keep_margin_percentstring
reprice일 때: 판매 가격 대비 지킬 마진.
on_cost_increase.max_increase_percentstring|null
reprice일 때: 한 번에 올릴 수 있는 최대 가격 인상. 넘으면 above_max가 적용돼요: pause 또는 notify.
on_cost_decreasestring
keep_price 또는 같은 마진까지 가격 인하.
on_out_of_stockstring
항상 zero_stock: 품절된 SKU는 채널에서 0으로 표시돼요.
on_back_in_stockstring
restock 또는 재개할 때까지 stay_paused.
round_tostring|null
가격 변경 시 끝자리(.99, .00 등).

오류

상태유형시점
404not-found이 계정에 해당 상품이 없어요.
409invalid-state상품에 이미 개별 규칙이 있어요. 그것을 교체하세요.
curl -X POST "https://www.ninjabuy.com/api/v1/sync_rules" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "applies_to": "prd_1x0a",
    "on_cost_increase": { "action": "pause" },
    "on_back_in_stock": "stay_paused"
  }'
Response 201
HTTP/2 201 Created

{
  "id": "rule_9p3e",
  "applies_to": "prd_1x0a",
  "on_cost_increase": { "action": "pause" },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "stay_paused",
  "round_to": null,
  "updated_at": "2026-11-03T10:14:00Z"
}

동기화 규칙 교체

PUT/v1/sync_rules/{id}

규칙 전체를 보내세요. 각 상품을 다음에 읽을 때부터 적용돼요.

범위products:write

경로 매개변수

idstring필수
규칙 ID.

본문

on_cost_increase.actionstring
마진을 지키도록 가격 변경, 상품 일시 중지, 또는 알림만.
on_cost_increase.keep_margin_percentstring
reprice일 때: 판매 가격 대비 지킬 마진.
on_cost_increase.max_increase_percentstring|null
reprice일 때: 한 번에 올릴 수 있는 최대 가격 인상. 넘으면 above_max가 적용돼요: pause 또는 notify.
on_cost_decreasestring
keep_price 또는 같은 마진까지 가격 인하.
on_out_of_stockstring
항상 zero_stock: 품절된 SKU는 채널에서 0으로 표시돼요.
on_back_in_stockstring
restock 또는 재개할 때까지 stay_paused.
round_tostring|null
가격 변경 시 끝자리(.99, .00 등).

오류

상태유형시점
404not-found이 계정에 해당 규칙이 없어요.
curl -X PUT "https://www.ninjabuy.com/api/v1/sync_rules/rule_default" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11" \
  -H "Content-Type: application/json" \
  -d '{
    "on_cost_increase": { "action": "notify" },
    "on_cost_decrease": "keep_price",
    "on_out_of_stock": "zero_stock",
    "on_back_in_stock": "restock",
    "round_to": ".99"
  }'
Response 200
HTTP/2 200 OK

{
  "id": "rule_default",
  "applies_to": "all",
  "on_cost_increase": { "action": "notify" },
  "on_cost_decrease": "keep_price",
  "on_out_of_stock": "zero_stock",
  "on_back_in_stock": "restock",
  "round_to": ".99",
  "updated_at": "2026-11-02T08:00:00Z"
}

개별 규칙 삭제

DELETE/v1/sync_rules/{id}

상품이 다시 기본 규칙을 따라요. rule_default 자체는 삭제할 수 없어요.

범위products:write

경로 매개변수

idstring필수
규칙 ID.

오류

상태유형시점
409invalid-staterule_default는 삭제할 수 없어요.
curl -X DELETE "https://www.ninjabuy.com/api/v1/sync_rules/rule_9p3e" \
  -H "Authorization: Bearer $NINJABUY_API_KEY" \
  -H "NinjaBuy-Version: 2026-11"
Response 200
HTTP/2 200 OK

{ "id": "rule_9p3e", "deleted": true }