AdminPlus

어드민플러스 OPEN API Admin

AdminPlus Admin API는 관리자(마스터) 클라이언트를 위한 REST API입니다. 매입처·매출처(셀러) 등 거래처 정보를 조회할 수 있으며, 토큰 발급 후 바로 시작할 수 있습니다.

Admin API는 admin 클라이언트만 호출할 수 있습니다.

기본 정보

엔드포인트와 공통 규칙

모든 요청은 HTTPS로 전송하며, 응답은 항상 application/json 형식입니다.

BASE https://api.adminplus.co.kr
구분내용
프로토콜HTTPS
인증 방식Bearer Token (OAuth 2.0 Client Credentials)
클라이언트 유형admin (관리자) — partner 클라이언트는 호출 불가
요청 본문POST 계열은 application/json (토큰 발급은 x-www-form-urlencoded)
날짜 형식YYYY-MM-DDTHH:ii:ss (예: 2026-07-07T12:00:00)
셀러 식별seller_code — 거래처 API의 매출처 partner_code와 동일. 조회는 선택, 등록·삭제는 필수
인코딩UTF-8

공통 요청 헤더

HTTP
Authorization: Bearer {access_token}
Content-Type: application/json
토큰 발급(/oauth/token) 요청에는 Authorization 헤더가 필요 없습니다. 그 외 모든 /v1/admin/* 엔드포인트는 Bearer 토큰이 필수입니다. seller API의 client_idx는 Admin에서 seller_code로 받습니다.

응답 형식

일관된 JSON 구조

모든 응답은 success, message, data 세 필드로 구성됩니다.

성공 응답

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    // 엔드포인트별 데이터
  }
}

에러 응답

JSON · 4xx / 5xx
{
  "success": false,
  "message": "invalid client",
  "data": {
    "errors": [ /* 검증 실패 시 상세 목록 */ ]
  }
}

페이지네이션

목록 조회는 커서 기반입니다. 응답의 next_cursor를 다음 요청의 cursor 파라미터로 전달하고, has_morefalse가 될 때까지 반복합니다.

필드타입설명
itemsarray결과 목록
next_cursorint|null다음 페이지 커서 (마지막 페이지면 null)
has_moreboolean다음 페이지 존재 여부

에러 & 요청 제한

HTTP 상태 코드

  • 200
    성공 — 요청이 정상 처리되었습니다.
  • 400
    잘못된 요청 — 필수 파라미터 누락, 검증 실패.
  • 401
    인증 실패 — 토큰 누락·만료·유효하지 않음.
  • 403
    권한 없음 — 스코프 부족, admin 아님, 허용되지 않은 IP.
  • 429
    요청 한도 초과 — 분당/일일 호출 제한 초과.
  • 500
    서버 오류 — 내부 처리 중 오류 발생.

Rate Limit

클라이언트별로 분당·일일 호출 한도가 적용되며, 한도 초과 시 429 응답을 반환합니다. IP 화이트리스트가 설정된 경우 등록된 IP에서만 호출할 수 있습니다.

!
한도값은 계약에 따라 다릅니다. 429 too many requests(분당) 또는 429 daily limit exceeded(일일) 메시지로 구분됩니다.

인증

토큰 발급

발급받은 client_idclient_secret으로 액세스 토큰을 발급합니다. 토큰은 30일간 유효하며, 유효한 토큰이 남아 있으면 기존 토큰을 그대로 반환합니다.

POST /oauth/token

요청 파라미터 (form-urlencoded)

파라미터타입설명
client_id필수string발급받은 클라이언트 ID (admin)
client_secret필수string발급받은 클라이언트 시크릿

요청 예시

cURL
curl -X POST https://api.adminplus.co.kr/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "token_type": "Bearer",
    "access_token": "3b1f...9ac2",
    "expires_in": 2592000
  }
}
!
401 invalid client — 아이디/시크릿 불일치, 401 access token expired — 클라이언트 계약 만료. expires_in은 남은 유효 시간(초)입니다.

권한 범위 (Scopes)

엔드포인트별 필요 권한

클라이언트마다 허용된 스코프가 다릅니다. 필요한 스코프가 없거나 admin이 아니면 403 permission denied가 반환됩니다.

product.read
상품·그룹상품·카테고리 목록 조회
product.write
상품·그룹상품·카테고리 등록·수정·삭제
stock.read
재고 목록 조회
stock.write
재고 입·출고·정정·상태수정·전표삭제
order.read
주문 조회·변경분·매칭 조회·택배사 목록·주문서 문의·메모 조회·결제 조회·클레임 조회
order.write
주문 등록, 운송장 등록, 매칭 등록·삭제, 주문서 문의 답글·처리상태, 메모 등록·수정·삭제, 예치금결제처리
order.delete
주문 삭제
partner.read
거래처 목록 조회
partner.write
거래처 등록·수정·삭제
manage_group.read
관리그룹 목록 조회
manage_group.write
관리그룹 등록·수정·삭제
price_group.read
공급가그룹 목록 조회
price_group.write
공급가그룹 등록·수정·삭제

카테고리

카테고리 목록

상품카테고리 트리를 조회합니다. 상품 등록의 category_code·partner_categories[]에는 이 목록의 category_code를 넣습니다. 조회 응답에 parent_category_code라는 별도 식별자는 없고, 상위 코드는 필드로만 내려갑니다.

GET/v1/admin/categories scope product.read

쿼리 파라미터

파라미터타입설명
category_code선택string해당 코드 1건. tree=1이면 하위 포함
parent_category_code선택string이 코드의 바로 아래 하위. 빈 값이면 최상위만
visible선택booleantrue 노출 · false 비노출
keyword선택string카테고리명·코드 부분검색
tree선택string1(기본) 트리 · 0 평탄 목록

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/categories" \
  -H "Authorization: Bearer {access_token}"

# 최상위만
curl "https://api.adminplus.co.kr/v1/admin/categories?parent_category_code=&tree=0" \
  -H "Authorization: Bearer {access_token}"

# 단건 + 하위
curl "https://api.adminplus.co.kr/v1/admin/categories?category_code=001" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "category_code": "001",
        "name": "의류",
        "parent_category_code": null,
        "depth": 1,
        "visible": true,
        "path": "의류",
        "category_type": "product",
        "updated_at": "2026-08-20T10:00:00",
        "children": [
          {
            "category_code": "001001",
            "name": "상의",
            "parent_category_code": "001",
            "depth": 2,
            "visible": true,
            "path": "의류 > 상의",
            "category_type": "product",
            "updated_at": "2026-08-20T10:05:00",
            "children": []
          }
        ]
      }
    ],
    "category_type": "product"
  }
}
상품 등록·수정의 category_code에는 위 category_code 값을 그대로 넣습니다. parent_category_code를 넣으면 안 됩니다.
거래처 노출 분류 partner_categories[]에도 같은 상품카테고리 코드를 넣습니다.
최대 4단계입니다. 삭제된 분류(delflag)는 나오지 않습니다.

카테고리 등록

하위 분류를 생성합니다. parent_category_code가 없으면 최상위입니다. category_code는 자동 발급되며, 응답의 category_code를 상품 등록에 사용합니다.

POST/v1/admin/categories scope product.write

요청 본문

필드타입설명
name필수string카테고리명 (최대 100자)
parent_category_code선택string상위 분류의 category_code. 없으면 최상위. 조회 응답에 이 이름 필드는 식별자가 아닙니다
visible선택boolean노출 여부. 기본 true

요청 예시

JSON
{
  "name": "상의",
  "parent_category_code": "001",
  "visible": true
}

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "category_code": "001001",
    "name": "상의",
    "parent_category_code": "001",
    "depth": 2,
    "visible": true,
    "path": "의류 > 상의",
    "category_type": "product",
    "updated_at": "2026-09-02T12:40:00"
  }
}
!
400 parent_category_code 가 존재하지 않습니다. / 400 카테고리는 최대 4단계까지 생성할 수 있습니다.

카테고리 수정

카테고리명·노출여부를 수정합니다. category_code와 상위 분류는 바꿀 수 없습니다.

POST/v1/admin/categories/update scope product.write

요청 본문

필드타입설명
category_code필수string수정할 분류 코드 (조회 응답의 category_code)
name선택string카테고리명
visible선택boolean노출 여부

요청 예시

JSON
{
  "category_code": "001001",
  "name": "티셔츠",
  "visible": true
}

카테고리 삭제

분류를 삭제합니다. 하위 분류도 함께 삭제됩니다. 상품 또는 거래처노출분류에 쓰이면 409입니다.

POST/v1/admin/categories/delete scope product.write

요청 본문

필드타입설명
category_code필수string삭제할 분류 코드

요청 예시

JSON
{ "category_code": "001001" }
!
400 category_code 가 존재하지 않습니다. / 409 카테고리가 적용된 상품이 있어 삭제할 수 없습니다.

상품

상품 목록 조회

상품 목록을 조회합니다. detail=1 또는 product_code 지정 시 매입처·매출거래처별공급가·그룹공급가·옵션 등 상세 관계가 포함됩니다.

GET/v1/admin/products scope product.read

쿼리 파라미터

파라미터타입설명
product_code선택string|int상품코드 (지정 시 상세 포함)
product_name선택string상품명 부분검색
status선택stringactive · inactive
detail선택string1이면 관계 데이터 포함
cursor선택int페이지네이션
limit선택int1~500, 기본 100

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/products?product_code=10000001&detail=1" \
  -H "Authorization: Bearer {access_token}"

상품 등록

상품을 등록합니다. product_code는 입력하지 않으며 자동 생성됩니다. 상품은 항상 매입·단일상품으로 저장됩니다.

POST/v1/admin/products scope product.write

안내사항

!
자체공급과 옵션지정은 권장하지 않는 방식입니다. 상품 등록 API는 매입·단일상품만 지원합니다.

요청 필드

파라미터타입설명
name필수string상품명.
order_name선택string발주서 상품명. 발주서에 표기될 이름. 없으면 name
category_code필수string관리 카테고리 코드. 카테고리 목록category_code
status선택stringactive(기본) · inactive
taxable선택boolean과세 여부. 기본 true
consumer_price선택int소비자가. 권장판매가격. 기본 0
price필수int기본공급가. 실제 제공되는 가격
weight선택number무게(kg). 소수점 첫째 자리까지. 기본 0
shipping_policy_code선택int매출 배송비정책 코드
short_description선택string짧은 설명
description선택string상세 설명 (HTML 가능)
origin선택string원산지
order_cutoff_time선택string주문 마감시간 (예: 14:00)
shipping_origin선택string출고지
remote_unship선택boolean도서산간 미배송. 기본 false
use_group_price선택boolean그룹별 공급가 사용. 기본 false
use_gift선택boolean사은품 사용. 기본 false
use_supplies_biz_grp선택boolean노출/숨김 거래처그룹 사용. 기본 false
supplies_groups선택object공급가그룹코드 → show/hide. use_supplies_biz_grp=true일 때 저장
erp_code선택stringERP 코드.
barcode선택string바코드. 단일상품 옵션으로 저장
stock_mode선택stringunlimited(기본) · tracked · soldout
purchasers[]필수array매입처지정. 1개 이상, 기본매입처(is_default) 정확히 1개
└ partner_code필수int매입거래처 코드
└ cost선택int매입 공급가
└ shipping_policy_code선택int매입 배송비정책 코드
└ is_default조건부boolean기본매입처. 배열 중 정확히 1개만 true
seller_prices[]선택array매출거래처별 공급가
└ partner_code필수int매출거래처 코드
└ price선택int거래처 공급가
└ shipping_policy_code선택int거래처 배송비정책 코드
group_prices[]선택array그룹별 공급가
└ price_group_code필수int공급가그룹 코드
└ price선택int그룹 공급가. write_price=true일 때 사용
└ shipping_policy_code선택int그룹 배송비정책 코드
└ write_price선택boolean공급가 직접입력 여부
gifts[]선택array사은품. use_gift=true일 때 저장
└ product_code필수int사은품 상품코드
└ option_code선택int사은품 옵션코드
└ buy_qty선택int구매 수량 조건. 기본 1
└ gift_qty선택int지급 수량. 기본 1
partner_categories[]선택array거래처 노출 카테고리. 상품카테고리 category_code 배열
supplies_partners선택object노출/숨김 거래처. 거래처마다 노출·미노출을 따로 지정하지 않고, mode 하나가 지정 거래처 전체에 적용됩니다. 지정 거래처가 없으면 모든 거래처에 노출됩니다
└ mode선택string지정 거래처 전체에 적용. show(이 거래처만 노출) · hide(이 거래처만 숨김, 기본)
└ partner_codes[]선택array대상 매출거래처 코드

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/products" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "베이직 티셔츠",
    "order_name": "베이직 티셔츠 발주서명",
    "category_code": "001",
    "status": "active",
    "taxable": true,
    "consumer_price": 15000,
    "price": 10000,
    "weight": 0.4,
    "shipping_policy_code": 1,
    "short_description": "면 100% 베이직 티셔츠",
    "description": "<p>상세설명</p>",
    "origin": "대한민국",
    "order_cutoff_time": "14:00",
    "shipping_origin": "서울",
    "remote_unship": false,
    "use_group_price": true,
    "use_gift": true,
    "use_supplies_biz_grp": true,
    "supplies_groups": {
      "3": "show"
    },
    "erp_code": "A001",
    "barcode": "8800000000000",
    "stock_mode": "unlimited",
    "purchasers": [
      { "partner_code": 10, "cost": 5000, "shipping_policy_code": 2, "is_default": true }
    ],
    "seller_prices": [
      { "partner_code": 100, "price": 9000, "shipping_policy_code": 1 }
    ],
    "group_prices": [
      { "price_group_code": 3, "price": 9500, "shipping_policy_code": 1, "write_price": true }
    ],
    "gifts": [
      { "product_code": 10000002, "option_code": 428, "buy_qty": 1, "gift_qty": 1 }
    ],
    "partner_categories": ["001"],
    "supplies_partners": {
      "mode": "show",
      "partner_codes": [100, 101]
    }
  }'
공급가 우선순위는 관리자 화면과 동일합니다: 거래처별 > 그룹 > 기본공급가.
product_code를 보내도 무시되고 항상 새로 발급됩니다. 응답의 product_code를 사용하세요.
category_code카테고리 목록에서 받은 값만 허용합니다. 없거나 삭제된 코드면 400입니다.
상품은 항상 매입으로 저장되며 supply_type은 받지 않습니다. purchasers는 필수이며 1개 이상 + 기본매입처(is_default) 정확히 1개가 필요합니다.
option_type은 받지 않으며 항상 단일상품(none)입니다. erp_code, barcode, stock_mode는 최상위 필드로 받고 단일 옵션으로 저장합니다. image, single_option, options, option_titles, text_options, set_items, search_tags, product_url, cost, cost_currency는 사용하지 않습니다.
supplies_partners는 거래처별 노출/숨김이 아닙니다. mode 하나가 partner_codes 전체에 적용됩니다. 지정 거래처가 없으면 모든 거래처에 노출됩니다. '노출/숨김 거래처'는 '노출/숨김 거래처그룹'보다 우선합니다.

상품 수정

상품을 수정합니다. name, price 같은 기본 필드는 전달한 항목만 변경됩니다. 아래 관계 배열을 넣으면 부분 수정이 아니라 전체 교체입니다.

POST/v1/admin/products/update scope product.write
!
주의 — 관계 필드는 기존 데이터를 전부 지운 뒤 요청값으로 다시 만듭니다.
예: 매출거래처별 공급가가 10개인 상품에 seller_prices를 1건만 보내면, 그 1건만 남고 나머지 9건은 삭제됩니다. 1건만 고치려면 GET /v1/admin/products?product_code=…&detail=1로 전체를 받은 뒤, 수정한 목록을 그대로 다시 보내야 합니다.

필드가 요청에 있으면(빈 배열 [] 포함) 해당 관계는 교체됩니다. 건드리지 않으려면 키 자체를 빼세요.
· seller_prices — 매출거래처별 공급가 전체 삭제 후 재구성
· group_prices — 그룹별 공급가 전체 삭제 후 재구성
· purchasers — 매입처지정 전체 삭제 후 재구성. 등록 시 필수이며, 수정 시 키를 보내면 교체됩니다
· erp_code / barcode / stock_mode — 하나라도 있으면 단일 옵션을 교체합니다. 보내지 않은 항목은 기존 값을 유지합니다. single_option, options, option_titles, text_options, set_items, option_type은 받지 않습니다
· gifts — 사은품 전체 삭제 후 재구성
· partner_categories / supplies_partners / supplies_groups — 동일하게 전체 교체
· image, search_tags는 받지 않습니다. 이미지는 기존 값을 유지합니다
· 미노출(status=inactive)이거나 상품명을 바꾸면 관리자 매칭과 주문문자열 매칭이 정리됩니다. 셀러가 등록한 매칭도 포함합니다. 1:N이면 그 상품이 들어 있는 문자열 매칭이 통째로 삭제됩니다. supplies_partners / supplies_groups에서 숨긴 거래처·그룹의 관리자 매칭도 함께 정리됩니다

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/products/update" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_code": 10000001,
    "name": "베이직 티셔츠(수정)",
    "price": 11000
  }'
이름·가격만 바꿀 때는 관계 배열을 넣지 마세요. 위 예시처럼 기본 필드만 보내면 매입처·공급가·옵션·사은품은 그대로입니다.

상품 삭제

상품을 soft delete 합니다. 관리자 매칭과 주문문자열 매칭(상품 매칭, 셀러 등록분 포함), 공급가·옵션 등 관련 데이터도 함께 정리됩니다. 1:N 매칭이면 해당 상품이 들어 있는 문자열 그룹을 통째로 삭제합니다.

POST/v1/admin/products/delete scope product.write

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/products/delete" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
          -d '{"product_code": 10000001}'

그룹상품

그룹상품 목록

여러 개별 상품을 하나로 묶어 노출하는 그룹상품을 조회합니다. 일반 상품 목록(상품)에는 나오지 않습니다. 구성 상품·노출설정이 항상 포함됩니다.

GET/v1/admin/product_groups scope product.read

쿼리 파라미터

파라미터타입설명
product_group_code선택string|int그룹상품 코드. 있으면 해당 건 + 구성상품
keyword선택string그룹상품명 부분검색
status선택stringall · active(노출) · inactive(미노출)
category_code선택string거래처노출 분류 접두. 카테고리category_code
cursor선택int페이지네이션
limit선택int1~500, 기본 100

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/product_groups?limit=20" \
  -H "Authorization: Bearer {access_token}"

curl "https://api.adminplus.co.kr/v1/admin/product_groups?product_group_code=10000099" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "product_group_code": 10000099,
        "name": "마스크 세트",
        "short_description": "",
        "description": "",
        "status": "active",
        "image": "https://.../img/prtimg/set.jpg",
        "show_item_thumbs": false,
        "use_supplies_biz_grp": false,
        "item_count": 2,
        "created_at": "2026-09-02T13:00:00",
        "items": [
          {"product_code": 10000001, "name": "마스크A", "status": "active", "image": null},
          {"product_code": 10000002, "name": "마스크B", "status": "active", "image": null}
        ],
        "partner_categories": ["001"],
        "supplies_partners": {"mode": null, "partner_codes": []},
        "supplies_groups": {}
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
그룹으로 묶이면 구성 상품은 개별 노출되지 않고 그룹만 노출됩니다. 그룹을 미노출하면 구성이 풀려 개별 노출됩니다.
item_count는 노출 중(active)인 구성 상품 수입니다.

그룹상품 등록

그룹상품을 등록합니다. product_group_code는 자동 발급됩니다. 구성 상품은 일반 상품의 product_code를 넣습니다.

POST/v1/admin/product_groups scope product.write

요청 본문

필드타입설명
name필수string그룹상품명
items선택array구성 상품코드 배열. 일반 상품의 product_code
status선택stringactive(기본) · inactive
partner_categories[]array거래처노출 분류. 카테고리category_code
short_description / descriptionstring짧은 설명 / 상세
show_item_thumbsboolean상세페이지 개별 썸네일 노출
use_supplies_biz_grpboolean노출/숨김 거래처그룹 사용
supplies_partnersobject노출/숨김 거래처. mode 하나가 partner_codes[] 전체에 적용. 거래처별 개별 지정 아님
supplies_groupsobject공급가그룹코드 → show/hide. 구성 상품에도 같이 적용
apply_status_to_itemsboolean구성 상품 노출여부도 같이 변경

요청 예시

JSON
{
  "name": "마스크 세트",
  "items": [10000001, 10000002],
  "partner_categories": ["001"],
  "status": "active",
  "show_item_thumbs": false
}
!
400 존재하지 않는 상품코드입니다. — 구성 상품이 없거나 이미 삭제된 경우. 그룹상품은 구성으로 넣을 수 없습니다.
image는 등록·수정에서 받지 않습니다. 등록 시 noimage.jpg로 저장되고, 수정 시 기존 이미지를 유지합니다.

그룹상품 수정

그룹상품을 수정합니다. items를 보내면 구성 상품을 교체합니다.

POST/v1/admin/product_groups/update scope product.write

요청 본문

필드타입설명
product_group_code필수string|int그룹상품 코드
name / status / items등록과 동일. 보낸 항목만 변경
apply_status_to_itemsboolean구성 상품 노출여부도 같이 변경. 미노출 시 구성 상품 매칭도 삭제

요청 예시

JSON
{
  "product_group_code": 10000099,
  "name": "마스크 세트(수정)",
  "status": "inactive",
  "apply_status_to_items": true
}

그룹상품 삭제

그룹상품을 삭제합니다. 구성 연결·관리자 매칭·주문문자열 매칭(셀러 등록분 포함)·노출설정도 함께 지웁니다. 1:N 매칭이면 해당 그룹상품이 들어 있는 문자열 그룹을 통째로 삭제합니다. 구성 상품 자체는 삭제되지 않습니다.

POST/v1/admin/product_groups/delete scope product.write

요청 예시

JSON
{ "product_group_code": 10000099 }

재고

재고 목록 조회

옵션 단위 재고 현황을 조회합니다. 행 식별자는 option_code이며, 페이지네이션 cursor도 옵션 idx입니다. 관리자 상품(wgrant=admin)만 반환됩니다.

GET/v1/admin/stocks scope stock.read

쿼리 파라미터

파라미터타입설명
product_code선택string|int상품코드
option_code선택int옵션코드
search선택string숫자면 상품코드·옵션코드, 아니면 상품명·ERP코드 부분검색
category_code선택string관리 카테고리 접두 검색
soldout선택string1이면 품절 재고만
date_from / date_to선택string입·출고 합계 기간 (YYYY-MM-DD)
cursor선택int페이지네이션 (option_code)
limit선택int1~500, 기본 100

응답 필드

필드설명
stock_modeunlimited · tracked · soldout
warehouse_qty창고재고
available_qty가용재고
hold_qty창고재고 − 가용재고
inbound_qty / outbound_qty기간 입·출고 합계 (기간 없으면 전체)

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/stocks?product_code=10000001&soldout=1" \
  -H "Authorization: Bearer {access_token}"

입·출고·정정

재고 전표를 등록합니다. type=adjust이면 qty는 증감이 아니라 목표 창고수량입니다. 응답의 stock_batch_no로 전표를 삭제할 수 있습니다.

POST/v1/admin/stocks scope stock.write

요청 본문

필드타입설명
type필수stringin(입고) · out(출고) · adjust(정정)
occurred_at필수string발생일자 YYYY-MM-DD
items필수array대상 옵션 배열 (1개 이상)
└ option_code필수int옵션코드
└ qty필수int입고/출고 수량, 정정 시 목표 창고수량
└ product_code선택string|int있으면 옵션과 일치해야 함
memo선택string메모
order_code선택string발주코드. 있으면 입고완료 처리

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/stocks" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "in",
    "occurred_at": "2026-09-01",
    "memo": "입고",
    "items": [
      {"product_code": 10000001, "option_code": 428, "qty": 10}
    ]
  }'
출고(out)는 수량이 음수로 저장됩니다. 정정(adjust)은 현재 창고수량과 목표값이 같으면 해당 행은 건너뜁니다. 기존 클라이언트는 stock.write 스코프가 필요합니다.

재고 상태 수정

선택한 옵션의 재고 상태와 판매제한을 수정합니다.

POST/v1/admin/stocks/status scope stock.write

요청 본문

필드타입설명
option_codes필수array옵션코드 배열
stock_mode필수stringunlimited · tracked · soldout
sell_limit선택int0이면 제한 해제. 1 이상이면 판매제한 수량
sell_limit_day선택int판매제한 일수 (sell_limit 1 이상일 때)
sell_limit_range선택string0 셀러당수량제한(기본) · 1 전체주문수량제한. sell_limit이 1 이상일 때만 저장

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/stocks/status" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"option_codes":[428,429],"stock_mode":"soldout","sell_limit":0}'

재고 전표 삭제

입·출고·정정 전표를 삭제합니다. stock_batch_no 또는 stock_id 중 하나를 보냅니다.

POST/v1/admin/stocks/delete scope stock.write

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/stocks/delete" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{"stock_batch_no":"20260901120000123"}'

상품 매칭

매칭 등록

상품문자열과 실제 상품을 매핑합니다. POST /v1/admin/product_matches로 호출합니다(GET매칭 조회). 하나의 문자열에 여러 상품(1:N)을 매핑할 수 있으며, 동일 문자열은 교체 방식(기존 삭제 후 재등록)으로 저장됩니다.

POST/v1/admin/product_matches scope order.write

요청 본문

필드타입설명
matches필수array매칭 배열 (1~500)
└ match_string필수string매칭 문자열 (255자 이하)
└ memo선택string메모
└ products필수array매핑할 상품 목록 (1건 이상)
   · product_code필수int상품코드
   · option_code선택int옵션코드 (옵션 상품은 필수)
   · qty선택int수량 (1 이상, 기본 1)

요청 예시

JSON
{
  "matches": [
    {
      "match_string": "청바지세트",
      "memo": "상하의 세트",
      "products": [
        { "product_code": 10000195, "option_code": 428, "qty": 2 },
        { "product_code": 10000196, "qty": 1 }
      ]
    },
    {
      "match_string": "양말",
      "products": [
        { "product_code": 10000197 }
      ]
    }
  ]
}

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "saved_count": 3,
    "matches": [
      {
        "match_string": "청바지세트",
        "product_count": 2,
        "removed_count": 0,
        "products": [
          { "match_id": 101, "product_code": 10000195, "option_code": 428, "qty": 2, "action": "created" },
          { "match_id": 102, "product_code": 10000196, "option_code": null, "qty": 1, "action": "created" }
        ]
      },
      {
        "match_string": "양말",
        "product_count": 1,
        "removed_count": 0,
        "products": [
          { "match_id": 103, "product_code": 10000197, "option_code": null, "qty": 1, "action": "created" }
        ]
      }
    ],
    "one_to_many_or_multi_qty": [
      {
        "match_string": "청바지세트",
        "is_one_to_many": true,
        "product_count": 2,
        "has_qty_over_1": true,
        "max_qty": 2,
        "products": [
          { "match_id": 101, "product_code": 10000195, "option_code": 428, "qty": 2 },
          { "match_id": 102, "product_code": 10000196, "option_code": null, "qty": 1 }
        ]
      }
    ]
  }
}
같은 문자열 안에서는 상품·옵션 중복 입력이 허용됩니다. one_to_many_or_multi_qty는 1:N 또는 수량>1로 매칭된 문자열을 알려주어 검토에 활용할 수 있습니다. 상품을 아직 정하지 않았다면 매칭 등록(임시)를 사용하세요.

매칭 등록 (임시)

매칭 문자열과 메모만으로 임시 등록합니다. 상품·옵션은 비워 두며, 주문 자동매칭에는 사용되지 않습니다.

POST/v1/admin/product_matches/temp scope order.write

요청 본문

필드타입설명
matches필수array임시 매칭 배열 (1~500)
└ match_string필수string매칭 문자열 (255자 이하)
└ memo선택string메모 (255자 이하)

요청 예시

JSON
{
  "matches": [
    { "match_string": "청바지세트", "memo": "추후 수기매칭" },
    { "match_string": "양말" }
  ]
}

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "saved_count": 2,
    "matches": [
      {
        "match_id": 201,
        "match_string": "청바지세트",
        "memo": "추후 수기매칭",
        "is_temp": true,
        "action": "created"
      },
      {
        "match_id": 202,
        "match_string": "양말",
        "memo": "",
        "is_temp": true,
        "action": "created"
      }
    ]
  }
}
등록 가능한 건은 저장하고, 중복·오류 건만 data.errors[]에 담아 함께 반환합니다. (이미 상품 매칭됨 / 이미 임시등록됨 등)
요청 전체가 실패한 경우에만 400 validation failed가 반환됩니다.

매칭 조회

상품문자열 매칭 목록을 조회합니다. 같은 문자열은 하나의 그룹(products 배열)으로 묶여 반환됩니다. 임시등록 건은 is_temp: true로 표시됩니다. 같은 경로에 POST하면 매칭 등록이 됩니다.

GET/v1/admin/product_matches scope order.read

쿼리 파라미터

파라미터타입설명
match_string선택string문자열 부분 검색
product_code선택int상품코드 필터
cursor선택int페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/product_matches?match_string=청바지&limit=100" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "match_string": "청바지세트",
        "memo": "상하의 세트",
        "is_temp": false,
        "product_count": 2,
        "is_one_to_many": true,
        "products": [
          { "match_id": 101, "product_code": 10000195, "option_code": 428, "qty": 2, "regdate": "2026-07-07T10:00:00", "moddate": "2026-07-07T10:00:00" },
          { "match_id": 102, "product_code": 10000196, "option_code": null, "qty": 1, "regdate": "2026-07-07T10:00:00", "moddate": "2026-07-07T10:00:00" }
        ]
      },
      {
        "match_string": "양말",
        "memo": "추후 수기매칭",
        "is_temp": true,
        "product_count": 0,
        "is_one_to_many": false,
        "products": [
          { "match_id": 201, "product_code": 0, "option_code": null, "qty": 1, "regdate": "2026-07-07T10:00:00", "moddate": "2026-07-07T10:00:00" }
        ]
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
is_temptrue이면 수기 매칭 대기 상태입니다. is_one_to_many는 상품이 2개 이상이거나 수량(qty)이 1보다 큰 경우 true입니다. 페이지 경계에서 같은 문자열이 잘리지 않도록 그룹 단위로 잘립니다.

매칭 삭제

match_ids 또는 match_strings로 매칭 정보를 삭제(soft delete)합니다.

POST/v1/admin/product_matches/delete scope order.write

요청 본문 (둘 중 하나 필수)

필드타입설명
match_idsint[]매칭 ID 배열
match_stringsstring[]매칭 문자열 배열

요청 / 응답 예시

JSON
// 요청
{ "match_ids": [101, 102] }
// 또는
{ "match_strings": ["청바지세트"] }

// 응답 200 OK
{
  "success": true,
  "message": "success",
  "data": { "deleted_count": 2 }
}

주문

주문 조회

주문코드·주문상품코드·키워드로 주문을 조회합니다. keyword로 주문·상품·수취인 정보를 통합 검색할 수 있으며, 상품별 배송 상태·운송장 정보가 함께 반환됩니다. seller_code로 특정 셀러만 조회할 수 있고, 생략하면 전체 셀러 주문이 반환됩니다. 최대 조회기간은 1년이며, 등록일(regdate) 기준 최근 1년 이내 주문만 조회됩니다. 같은 경로에 POST하면 주문 등록이 됩니다. 수정일 기준 증분 조회는 주문 변경분을 사용하세요.

GET/v1/admin/orders scope order.read

쿼리 파라미터

파라미터타입설명
seller_code선택int매출처(셀러) 코드. 거래처 목록의 partner_code(partner_type=seller)와 동일
order_code선택string어드민플러스 주문코드(정확 일치)
order_product_code선택string어드민플러스 주문상품코드(정확 일치)
keyword선택string통합 검색어 (아래 검색 규칙 참고)
cursor선택string페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100
keyword 검색 규칙 — 필터 없이 호출하면 최근 1년 이내 주문을 페이지네이션합니다. 정렬은 상품 수정일 오름차순(moddate ASC)입니다.

형식 {숫자10자리이상}-{숫자} (예: 2607062329371272790002-34288) — 주문상품코드 검색(정확 일치)
숫자만 — 주문코드, 고객주문번호, 운송장번호, 상품코드, 수취인 연락처(정확 일치)
한글 포함 — 수취인명, 구매자명, 상품명(부분 일치)
그 외 텍스트 — 고객주문번호(정확 일치)

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/orders?keyword=이수령" \
  -H "Authorization: Bearer {access_token}"

curl "https://api.adminplus.co.kr/v1/admin/orders?seller_code=123&order_code=2607062329371272790002" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "orders": [
      {
        "order_code": "2607062329371272790002",
        "seller_code": 123,
        "seller_name": "테스트셀러",
        "order_producs": [
          {
            "order_product_code": "2607062329371272790002-55123",
            "customer_order_code": "ORD-20260707-001",
            "created_date": "2026-07-01T12:00:00",
            "last_updated_date": "2026-07-03T14:20:00",
            "product_code": "10000195",
            "product_name": "베이직 코튼 티셔츠",
            "option": "블랙/M",
            "price": 10000,
            "quantity": 2,
            "total_price": 20000,
            "purchaser_code": 45,
            "purchaser_name": "테스트매입처",
            "status": "delivered",
            "is_delivered": true,
            "shipping_company": "CJ대한통운",
            "tracking_number": "123456789012",
            "shipping_date": "2026-07-02T09:00:00",
            "delivered_date": "2026-07-03T14:20:00"
          }
        ],
        "orderer_name": "김주문",
        "orderer_hp": "01011112222",
        "orderer_tel": "0211112222",
        "orderer_address": "서울 강남구 테헤란로 100",
        "receiver_name": "이수령",
        "receiver_hp": "01033334444",
        "receiver_tel": "01033334444",
        "receiver_zipcode": "06236",
        "receiver_address": "서울 강남구 테헤란로 123 4층",
        "delivery_fee": 3000,
        "total_payment": 23000,
        "payment_method": "bank",
        "payment_status": "paid",
        "payment_date": "2026-07-01T12:30:00",
        "status": "active"
      }
    ],
    "next_cursor": "NTUxMjN8MjAyNi0wNy0wMyAxNDoyMDowMA==",
    "has_more": false
  }
}

응답 필드

필드타입설명
order_codestring어드민플러스 주문코드
seller_codeint|null매출처(셀러) 코드
seller_namestring|null매출처(셀러)명
order_producs[]array주문 상품. order_code 없이 조회해도 주문별 전체 상품이 포함됩니다
└ order_product_codestring주문상품코드
└ customer_order_codestring고객 주문번호
└ created_datedatetime상품 등록일시
└ last_updated_datedatetime상품 수정일시
└ product_codestring상품코드
└ product_namestring상품명
└ optionstring옵션명
└ priceint단가
└ quantityint수량
└ total_priceint상품 합계
└ purchaser_codeint|null매입처 코드. 없으면 null
└ purchaser_namestring|null매입처명. 없으면 null
└ statusstring상품 배송·클레임 상태 (아래 참고)
└ is_deliveredboolean운송장 등록 여부
└ shipping_companystring택배사명
└ tracking_numberstring운송장번호
└ shipping_datedatetime발송일시
└ delivered_datedatetime배송완료일시
orderer_namestring주문자명
orderer_hpstring주문자 휴대폰
orderer_telstring주문자 전화
orderer_addressstring주문자 주소
receiver_namestring수령인명
receiver_hpstring수령인 휴대폰
receiver_telstring수령인 전화
receiver_zipcodestring수령인 우편번호
receiver_addressstring수령인 주소
delivery_feeint배송비
total_paymentint결제 합계
payment_methodstring결제수단 (아래 참고)
payment_statusstringpaid · unpaid
payment_datedatetime입금확인일시
statusstring주문 상태. 기본 조회는 active
상품 status: awaiting_payment(입금대기) · order_received(주문접수) · paid(결제완료) · preparing_shipment(배송준비중) · shipping(배송중) · delivered(배송완료) · completed(거래완료) · purchased(발주완료) · cancelled(주문취소) · refunded(환불) · exchange(교환) · returned(반품) · draft(임시주문)
payment_status: paid(결제완료) · unpaid(미결제)
payment_method: bank(무통장입금) · deposit(예치금) · point(적립금) · card(신용카드) · virtual_account(가상계좌) · account_transfer(계좌이체) · mobile_payment(휴대폰결제) · free(무료) · other(기타)
매입처가 없으면 purchaser_code / purchaser_namenull입니다. 필터 없이 호출해도 order_code 단건과 같은 필드가 반환됩니다.

주문 변경분 조회

특정 시각 이후 수정된 주문만 조회합니다. 전체 동기화 이후 증분 반영에 사용합니다. 삭제된 주문(status: deleted)도 포함됩니다. seller_code는 선택입니다. 최대 조회기간은 1년이며, 등록일(regdate) 기준 최근 1년 이내 주문만 조회됩니다. 응답 필드는 주문 조회와 동일합니다.

GET/v1/admin/orders/changed scope order.read

쿼리 파라미터

파라미터타입설명
updated_since필수datetime수정일 기준 (YYYY-MM-DDTHH:ii:ss)
seller_code선택int매출처(셀러) 코드
cursor선택string페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/orders/changed?updated_since=2026-07-01T00:00:00&seller_code=123&limit=100" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "orders": [
      {
        "order_code": "2607062329371272790002",
        "seller_code": 123,
        "seller_name": "테스트셀러",
        "order_producs": [
          {
            "order_product_code": "2607062329371272790002-55123",
            "customer_order_code": "ORD-20260707-001",
            "created_date": "2026-07-01T12:00:00",
            "last_updated_date": "2026-07-10T15:40:00",
            "product_code": "10000195",
            "product_name": "베이직 코튼 티셔츠",
            "option": "블랙/M",
            "price": 10000,
            "quantity": 2,
            "total_price": 20000,
            "purchaser_code": 45,
            "purchaser_name": "테스트매입처",
            "status": "delivered",
            "is_delivered": true,
            "shipping_company": "CJ대한통운",
            "tracking_number": "123456789012",
            "shipping_date": "2026-07-02T09:00:00",
            "delivered_date": "2026-07-03T14:20:00"
          }
        ],
        "orderer_name": "김주문",
        "orderer_hp": "01011112222",
        "orderer_tel": "0211112222",
        "orderer_address": "서울 강남구 테헤란로 100",
        "receiver_name": "이수령",
        "receiver_hp": "01033334444",
        "receiver_tel": "01033334444",
        "receiver_zipcode": "06236",
        "receiver_address": "서울 강남구 테헤란로 123 4층",
        "delivery_fee": 3000,
        "total_payment": 23000,
        "payment_method": "bank",
        "payment_status": "paid",
        "payment_date": "2026-07-01T12:30:00",
        "status": "active"
      }
    ],
    "next_cursor": "MjYwNzA2MjMyOTM3MTI3Mjc5MDAwMnwyMDI2LTA3LTEwIDE1OjQwOjAw",
    "has_more": true
  }
}
주문 statusactive / deleted입니다. 삭제된 주문의 상품 statusdeleted입니다. payment_status는 주문 조회와 동일하게 paid / unpaid입니다.

주문 등록

한 번에 최대 100건의 주문을 등록합니다. POST /v1/admin/orders로 호출합니다(GET주문 조회). seller_code필수이며, 해당 셀러 기준으로 상품문자열 매칭·판매가가 적용됩니다. 각 상품은 product_code 또는 product_string하나만 입력합니다. product_string을 넣으면 미리 등록한 매칭 규칙으로 자동 매칭·1:N 확장됩니다.

POST/v1/admin/orders scope order.write

요청 본문

필드타입설명
seller_code필수int매출처(셀러) 코드. 거래처 목록의 partner_code(partner_type=seller)와 동일
orders필수array주문 배열 (1~100)
└ customer_order_code필수string고객 주문번호 (거래처 내 고유)
└ receiver_name필수string수령인 이름
└ receiver_tel필수string수령인 연락처
└ receiver_addr1필수string수령인 주소
└ receiver_addr2선택string수령인 상세주소
└ receiver_zipcode선택string수령인 우편번호
└ receiver_hp필수string수령인 휴대폰
└ orderer_name / orderer_hp / orderer_tel선택string주문자 정보. 미입력 시 각각 receiver_name / receiver_hp / receiver_tel로 대체
└ orderer_zipcode / addr1 / addr2선택string주문자 주소
└ delivery_msg선택string배송 메시지
└ items필수array주문 상품 목록
   · product_code택1int상품코드 (product_string과 동시 입력 불가)
   · product_string택1string자동 매칭용 상품문자열 (product_code과 동시 입력 불가)
   · option_code선택int옵션코드 (product_code 사용 시, 옵션 상품은 필수·단일상품은 생략 시 자동 부여)
   · qty필수int수량 (1 이상)

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/orders" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
  "seller_code": 123,
  "orders": [
    {
      "customer_order_code": "ORD-20260707-001",
      "orderer_name": "김주문",
      "orderer_hp": "010-1111-2222",
      "receiver_name": "이수령",
      "receiver_hp": "010-3333-4444",
      "receiver_tel": "010-3333-4444",
      "receiver_zipcode": "06236",
      "receiver_addr1": "서울 강남구 테헤란로 123",
      "receiver_addr2": "4층",
      "delivery_msg": "부재 시 문 앞",
      "items": [
        { "product_code": 10000195, "option_code": 428, "qty": 2 },
        { "product_string": "양말세트", "qty": 1 },
        { "product_string": "상품 문자열 매치 테스트", "qty": 2 }
      ]
    }
  ]
}'

요청 예시 · 주문자 생략

orderer_name / orderer_hp / orderer_tel을 생략하면 수령인 정보로 자동 대체됩니다.

JSON
{
  "seller_code": 123,
  "orders": [
    {
      "customer_order_code": "ORD-20260707-002",
      "receiver_name": "이수령",
      "receiver_hp": "010-3333-4444",
      "receiver_tel": "010-3333-4444",
      "receiver_zipcode": "06236",
      "receiver_addr1": "서울 강남구 테헤란로 123",
      "receiver_addr2": "4층",
      "items": [
        { "product_code": 10000195, "option_code": 428, "qty": 1 }
      ]
    }
  ]
}

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "order_key": "66a4b1c2e9f3d",
    "total_amount": 23000,
    "dlv_amount": 3000,
    "order_count": 1,
    "orders": [
      {
        "customer_order_code": "ORD-20260707-001",
        "adminplus_order_code": "2607062329371272790002"
      }
    ]
  }
}
주문자(orderer_name / orderer_hp / orderer_tel) 미입력 시 각각 수령인(receiver_name / receiver_hp / receiver_tel)으로 대체됩니다. 품절·재고 부족 시 검증 오류가 반환됩니다. 응답의 실질 식별자는 order_key이며, 주문 삭제 시 사용합니다.
!
검증 실패 시 400 validation failed와 함께 data.errors[]에 항목별 사유가 담깁니다. seller_code가 없거나 매출처가 아니면 400 seller_code 값이 잘못되었습니다.

택배사 목록

운송장 등록에 사용하는 택배사 코드를 조회합니다. 운송장 등록shipping_company_code를 넣습니다.

GET/v1/admin/orders/shipping_companies scope order.read

쿼리 파라미터

별도의 파라미터가 없습니다. 전체 목록을 반환합니다.

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/orders/shipping_companies" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      { "shipping_company_code": 2, "name": "CJ대한통운" },
      { "shipping_company_code": 27, "name": "직배송" }
    ]
  }
}
shipping_company_code를 운송장 등록에 사용합니다. 27(직배송)은 운송장번호를 생략할 수 있습니다.

운송장 등록

주문상품 단위로 운송장을 등록합니다. 대상은 order_product_code만 받습니다. seller_code는 받지 않습니다. 한 번에 최대 500건이며 행 단위로 부분 성공합니다. 택배사 코드는 택배사 목록shipping_company_code를 사용하세요.

POST/v1/admin/orders/tracking scope order.write

요청 본문

필드타입설명
items필수array운송장 배열 (1~500)
└ order_product_code필수string주문상품코드
└ shipping_company_code필수int택배사 코드 (택배사 목록)
└ tracking_number조건부string운송장번호. 직배송(27)이 아니면 필수. 숫자만
└ related_trackings선택array관련 운송장. 키는 해당 행의 order_product_code
   · shipping_company_code필수int관련 운송장 택배사 코드
   · tracking_number필수string관련 운송장번호

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/orders/tracking" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
  "items": [
    {
      "order_product_code": "2607062329371272790002-55123",
      "shipping_company_code": 4,
      "tracking_number": "123456789012",
      "related_trackings": [
        { "shipping_company_code": 4, "tracking_number": "999888777666" }
      ]
    }
  ]
}'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "total": 3,
    "success": 2,
    "failed": 1,
    "errors": ["주문번호 : 2607062329371272790002  주문취소된 주문입니다."]
  }
}
취소·교환·반품 상품은 등록되지 않습니다. 이미 배송중이면 운송장·택배사가 다를 때만 갱신합니다. 직배송(27)은 운송장번호 없이 배송완료로 처리됩니다. 전부 실패해도 HTTP 200이며 failederrors로 확인합니다.
!
items가 없거나 100건을 넘으면 400입니다.

주문 삭제

등록한 주문을 삭제합니다. 배송준비중(처리 이력 없음) 상태이며 결제가 접수되지 않은 주문만 삭제할 수 있습니다. seller_code는 필수입니다.

POST/v1/admin/orders/delete scope order.delete

요청 본문

필드타입설명
seller_code필수int매출처(셀러) 코드
order_key필수string주문 등록 응답의 order_key

요청 / 응답 예시

JSON
// 요청
{ "seller_code": 123, "order_key": "66a4b1c2e9f3d" }

// 응답 200 OK
{
  "success": true,
  "message": "success",
  "data": { "message": "주문 데이터가 삭제되었습니다." }
}
!
400 처리 이력이 있는 주문은 삭제할 수 없습니다. / 400 결제 접수된 주문은 삭제할 수 없습니다.

결제

결제 대기 조회

API로 등록되어 아직 결제되지 않은 주문(결제 대기) 목록을 조회합니다. seller_code로 특정 셀러만 조회할 수 있고, 생략하면 전체 셀러가 반환됩니다. 결제 조회는 GET /v1/admin/payments, 예치금 강제 결제는 예치금결제처리를 사용하세요.

GET/v1/admin/payments/pending scope order.read

쿼리 파라미터

파라미터타입설명
seller_code선택int매출처(셀러) 코드
order_key선택string주문 등록 응답의 order_key (결제 대기 배치 키)
cursor선택int페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/payments/pending?seller_code=123&limit=100" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "datas": [
      {
        "temp_idx": 5521,
        "regdate": "2026-07-07T12:00:00",
        "total_amount": 23000,
        "order_key": "66a4b1c2e9f3d",
        "seller_code": 123,
        "seller_name": "테스트셀러"
      }
    ],
    "next_cursor": 5521,
    "has_more": false
  }
}

결제 조회

결제가 접수·완료된 내역을 조회합니다. 결제 수단별(예치금·적립금·무통장) 상세와 현금영수증 정보를 포함합니다. seller_code로 특정 셀러만 조회할 수 있고, 생략하면 전체 셀러가 반환됩니다.

현금영수증 안내 — 현금영수증은 해당 기능을 지원하는 운영업체에 한해 제공됩니다. 지원하지 않는 경우 값이 없거나 비어 있을 수 있습니다.
GET/v1/admin/payments scope order.read

쿼리 파라미터 (updated_since 또는 payment_key 중 하나 필수)

파라미터타입설명
updated_sincedatetime수정일 기준 (YYYY-MM-DDTHH:ii:ss). payment_key가 없으면 필수
payment_key선택string특정 결제키 필터 (updated_since 없이도 단건 조회 가능)
seller_code선택int매출처(셀러) 코드
cursor선택int페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/payments?updated_since=2026-07-01T00:00:00" \
  -H "Authorization: Bearer {access_token}"

curl "https://api.adminplus.co.kr/v1/admin/payments?payment_key=17203948821234587&seller_code=123" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "datas": [
      {
        "payment_idx": 8801,
        "payment_key": "17203948821234587",
        "seller_code": 123,
        "seller_name": "테스트셀러",
        "payment_status": "completed",
        "total_amount": 23000,
        "required_payment_amount": 20000,
        "paid_amount": 20000,
        "payments": [
          { "method": "deposit", "amount": 3000 },
          { "method": "point", "amount": 0 },
          {
            "method": "bank",
            "amount": 20000,
            "bank_name": "국민은행",
            "account_number": "123-456-789",
            "depositor": "홍길동",
            "deposit_status": "completed",
            "deposited_at": "2026-07-07T13:00:00",
            "cash_receipt": {
              "applied": true,
              "type": "BUSINESS",
              "number": "8803200824",
              "amount": 20000
            }
          }
        ]
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
payment_status·deposit_status: completed(입금확인) 또는 wait(입금대기). payments[].methoddeposit(예치금) · point(적립금) · bank(무통장입금)입니다. payment_key만으로도 단건 조회할 수 있습니다.

예치금결제처리

미결제 주문을 예치금으로만 즉시 결제 완료합니다. POST /v1/admin/payments로 호출합니다(GET결제 조회). 주문 금액 전액이 예치금으로 처리되며, 적립금·무통장은 사용할 수 없습니다. API의 예치금결제처리는 시스템 내 셀러계정별 마이너스 예치금 사용 여부에 상관없이 처리됩니다.

POST/v1/admin/payments scope order.write

요청 본문

필드타입설명
order_key필수string / string[]주문키. 단건 문자열 또는 배열 (최대 20개). 주문 등록 응답의 order_key
결제 금액은 주문 합계로 자동 계산합니다. payments를 보내도 예치금(deposit)만 허용되며, 다른 수단은 400입니다.

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/payments" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
  "order_key": ["66a4b1c2e9f3d", "66a45fade6589"]
}'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "payment_key": "17203948821234587",
    "total_amount": 23000,
    "payment_status": "completed",
    "deposit_balance_before": 5000,
    "deposit_balance_after": -18000,
    "forced": true
  }
}
deposit_balance_before는 결제 전, deposit_balance_after는 결제 후 잔액입니다. forced는 처리 전 예치금이 주문 금액보다 적을 때 true입니다. 접수와 동시에 결제 완료(completed)됩니다. 대상 주문은 결제 대기 조회order_key를 사용하세요.
!
400 관리자는 예치금(deposit)으로만 결제할 수 있습니다. / 409 이미 결제주문내역이 존재하는 주문키값이 있습니다.

주문서 문의

문의 조회

거래처가 등록한 주문서 문의 목록을 조회합니다. 각 문의에 관리자·협력사 답글(replies[])이 포함됩니다. inquiry_id를 주면 해당 문의 1건과 답글만 반환합니다. 삭제된 글은 조회되지 않습니다. 같은 경로에 POST하면 문의 답글이 됩니다.

GET/v1/admin/order_inquiries scope order.read

쿼리 파라미터

파라미터타입설명
start_date선택date시작일 (YYYY-MM-DD). 둘 다 없으면 최근 6개월
end_date선택date종료일 (YYYY-MM-DD). 하나만 넣으면 안 됩니다
status선택stringall · pending · completed (기본 all)
category선택stringall · product · shipping · return_cancel · other
keyword선택string문의 내용·주문번호 부분검색
order_code선택string주문번호 정확 일치
seller_code선택int매출거래처(셀러) 코드
inquiry_id선택int문의 단건 + 답글. 있으면 기간·필터 없이 해당 건만 반환
cursor선택string페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100
status / category 값
pending · 처리전completed · 처리완료product · 상품shipping · 배송return_cancel · 반품/취소other · 기타

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/order_inquiries?status=all&limit=20" \
  -H "Authorization: Bearer {access_token}"

# 단건 + 답글
curl "https://api.adminplus.co.kr/v1/admin/order_inquiries?inquiry_id=101" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "inquiry_id": 101,
        "order_code": "2608070017358544650002",
        "category": "product",
        "content": "배송 일정 문의합니다.",
        "reply_count": 1,
        "status": "pending",
        "created_at": "2026-08-20T10:27:36",
        "writer_name": "API테스트업체",
        "writer_type": "partner",
        "seller_code": 123,
        "seller_name": "API테스트업체",
        "replies": [
          {
            "inquiry_id": 500,
            "order_code": "2608070017358544650002",
            "category": "other",
            "content": "확인 후 안내드리겠습니다.",
            "created_at": "2026-08-20T10:56:43",
            "writer_name": "플랜비",
            "writer_type": "admin"
          }
        ]
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
writer_type: partner(협력사) · admin(관리자)
협력사 답글에는 depth가 추가됩니다. 관리자 답글에는 depth가 없습니다.
목록·단건은 거래처 원글(thread=0, isadmin!=1)만 반환합니다. 답글은 replies[]에 포함됩니다.
조회 응답에는 parent_inquiry_id 필드가 없습니다. 원글·답글 모두 식별자는 inquiry_id입니다. 답글을 달 때는 이 값을 답글 등록 요청의 parent_inquiry_id에 넣습니다.
관리자 메모(isadmin=1, thread=0)는 이 API가 아니라 주문서 메모에서 조회합니다.
삭제된 글(delflag / isdeleted)은 목록·단건·답글 모두에서 제외됩니다.

문의 답글

거래처 문의에 관리자 답글을 등록합니다. POST /v1/admin/order_inquiries로 호출합니다(GET문의 조회). parent_inquiry_idcontent가 필요합니다. parent_inquiry_id는 조회 응답에 있는 필드가 아닙니다. 문의 조회inquiry_id(원글 또는 replies[].inquiry_id)를 그대로 넣습니다. 신규 문의 생성은 지원하지 않으며, 관리자 새 글은 메모 등록을 사용합니다.

POST/v1/admin/order_inquiries scope order.write

요청 본문

필드타입설명
content필수string답글 내용 (최대 5000자)
parent_inquiry_id필수int답글을 달 대상의 inquiry_id. 조회 응답에는 이 이름 필드가 없고, 요청할 때만 씁니다. 원글 inquiry_id 또는 replies[].inquiry_id 값을 넣습니다

요청 예시

JSON
{
  "content": "확인 후 안내드리겠습니다.",
  "parent_inquiry_id": 101
}

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "inquiry_id": 503,
    "order_code": "2608070017358544650002",
    "category": "product",
    "content": "확인 후 안내드리겠습니다.",
    "reply_count": 0,
    "status": "pending",
    "created_at": "2026-08-20T11:30:00",
    "writer_type": "admin",
    "parent_inquiry_id": 101
  }
}
parent_inquiry_id는 등록 요청·등록 응답에만 있습니다. 이후 조회(GET)에는 나오지 않고, 답글은 부모의 replies[]inquiry_id로 붙습니다.
예: 목록의 inquiry_id=101에 답글 → {"parent_inquiry_id": 101}. replies[]inquiry_id=500에 다시 답글 → {"parent_inquiry_id": 500}.
주문번호·카테고리·공개여부는 부모 글을 따릅니다. 등록 후 스레드 참여자(협력사)에게 알림이 생성됩니다.
!
400 parent_inquiry_id 는 필수입니다. / 400 부모 문의가 존재하지 않습니다.

처리상태 변경

거래처 문의의 처리상태를 변경합니다. 관리자 글은 변경할 수 없습니다.

POST/v1/admin/order_inquiries/status scope order.write

요청 본문

필드타입설명
inquiry_id필수int문의 ID
status필수stringpending · completed

요청 / 응답 예시

JSON
// 요청
{ "inquiry_id": 101, "status": "completed" }

// 응답 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "inquiry_id": 101,
    "status": "completed"
  }
}
!
400 존재하지 않는 문의이거나 권한이 없습니다. / 400 거래처 문의만 처리상태를 변경할 수 있습니다.

문의 답글 삭제

본인이 등록한 관리자 답글을 삭제합니다. 답글이 없으면 삭제 처리되고, 답글이 있으면 내용이 “삭제된 메모 입니다”로 바뀝니다. 어느 쪽이든 이후 조회에는 나오지 않습니다. 거래처 글이나 다른 관리자 글은 삭제할 수 없습니다.

POST/v1/admin/order_inquiries/delete scope order.write

요청 본문

필드타입설명
inquiry_id필수int삭제할 답글 ID

요청 / 응답 예시

JSON
// 요청
{ "inquiry_id": 503 }

// 응답 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "inquiry_id": 503,
    "deleted": true
  }
}
!
400 존재하지 않는 문의이거나 권한이 없습니다. / 403 삭제 권한이 없습니다.

주문서 메모

메모 조회

관리자가 등록한 주문서 상담 메모 목록을 조회합니다. memo_id를 주면 해당 메모 1건만 반환합니다. 삭제된 글은 조회되지 않습니다. 같은 경로에 POST하면 메모 등록이 됩니다.

GET/v1/admin/order_memos scope order.read

쿼리 파라미터

파라미터타입설명
start_date선택date시작일 (YYYY-MM-DD). 둘 다 없으면 최근 6개월
end_date선택date종료일 (YYYY-MM-DD). 하나만 넣으면 안 됩니다
keyword선택string메모 내용·주문번호 부분검색
order_code선택string주문번호 정확 일치
seller_code선택int매출거래처(셀러) 코드
memo_id선택int메모 단건. 있으면 기간·필터 없이 해당 건만 반환
cursor선택string페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/order_memos?limit=20" \
  -H "Authorization: Bearer {access_token}"

# 단건
curl "https://api.adminplus.co.kr/v1/admin/order_memos?memo_id=201" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "memo_id": 201,
        "order_code": "2608070017358544650002",
        "category": "other",
        "content": "내부 확인 메모",
        "visible_to_seller": false,
        "created_at": "2026-08-20T11:00:00",
        "writer_name": "admin_api",
        "writer_type": "admin",
        "seller_code": 123,
        "seller_name": "API테스트업체"
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
visible_to_sellertrue이면 협력업체 계정에 노출됩니다.
거래처 문의는 주문서 문의에서 조회합니다.

메모 등록

주문서에 관리자 상담 메모를 등록합니다. POST /v1/admin/order_memos로 호출합니다(GET메모 조회). 기본은 비공개이며, visible_to_sellertrue로 주면 협력업체에 노출됩니다.

POST/v1/admin/order_memos scope order.write

요청 본문

필드타입설명
order_code필수string주문번호
content필수string메모 내용 (최대 5000자)
category선택stringproduct · shipping · return_cancel · other (기본 other)
visible_to_seller선택bool협력업체 노출 여부. 기본 false
seller_code선택int넣으면 해당 매출처 주문인지 검증

요청 예시

JSON
{
  "order_code": "2608070017358544650002",
  "content": "내부 확인 메모",
  "category": "other",
  "visible_to_seller": false
}

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "memo_id": 201,
    "order_code": "2608070017358544650002",
    "category": "other",
    "content": "내부 확인 메모",
    "visible_to_seller": false,
    "created_at": "2026-08-20T11:00:00",
    "writer_name": "admin_api",
    "writer_type": "admin",
    "seller_code": 123,
    "seller_name": "API테스트업체"
  }
}
!
400 존재하지 않는 주문이거나 권한이 없습니다.

메모 수정

본인이 등록한 관리자 메모의 본문·분류·공개여부를 수정합니다. content, category, visible_to_seller 중 하나 이상 필요합니다. 루트 메모의 공개여부를 바꾸면 하위 답글에도 반영됩니다.

POST/v1/admin/order_memos/update scope order.write

요청 본문

필드타입설명
memo_id필수int수정할 메모 ID
content선택string메모 내용 (최대 5000자)
category선택stringproduct · shipping · return_cancel · other
visible_to_seller선택bool협력업체 노출 여부

요청 / 응답 예시

JSON
// 요청
{
  "memo_id": 201,
  "content": "수정된 메모",
  "visible_to_seller": true
}

// 응답 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "memo_id": 201,
    "order_code": "2608070017358544650002",
    "category": "other",
    "content": "수정된 메모",
    "visible_to_seller": true,
    "updated": true
  }
}
!
400 존재하지 않는 메모이거나 권한이 없습니다. / 403 수정 권한이 없습니다.

메모 삭제

본인이 등록한 관리자 메모를 삭제합니다. 답글이 없으면 삭제 처리되고, 답글이 있으면 내용이 “삭제된 메모 입니다”로 바뀝니다. 어느 쪽이든 이후 조회에는 나오지 않습니다.

POST/v1/admin/order_memos/delete scope order.write

요청 본문

필드타입설명
memo_id필수int삭제할 메모 ID

요청 / 응답 예시

JSON
// 요청
{ "memo_id": 201 }

// 응답 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "memo_id": 201,
    "deleted": true
  }
}
!
400 존재하지 않는 메모이거나 권한이 없습니다. / 403 삭제 권한이 없습니다.

클레임

클레임 조회

취소·반품·교환 클레임을 수정일 기준으로 조회합니다. 환불 금액, 클레임 상태, 대상 상품이 함께 반환되며, 교환은 교환 상품 목록(claim_exchange_products)도 포함됩니다. 삭제된 클레임(status: deleted)도 포함됩니다. seller_code로 특정 셀러만 조회할 수 있고, 생략하면 전체 셀러가 반환됩니다. 최대 조회기간은 1년이며, 등록일(regdate) 기준 최근 1년 이내 클레임만 조회됩니다.

GET/v1/admin/claims scope order.read

쿼리 파라미터

파라미터타입설명
claim_type필수string클레임 유형 — cancel · return · exchange
updated_since필수datetime수정일 기준 (YYYY-MM-DDTHH:ii:ss)
seller_code선택int매출처(셀러) 코드
order_code선택string주문번호 정확 일치
cursor선택string페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100
claim_type 값
cancel · 취소return · 반품exchange · 교환

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/claims?claim_type=return&updated_since=2026-07-01T00:00:00&limit=100" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "orders": [
      {
        "claim_no": 3021,
        "claim_type": "return",
        "claim_status": "completed",
        "seller_code": 123,
        "seller_name": "테스트셀러",
        "order_code": "2607062329371272790002",
        "order_amount": 23000,
        "refund_product_amount": 20000,
        "refund_shipping_amount": 3000,
        "refund_total_amount": 23000,
        "refund_status": "completed",
        "refund_date": "2026-07-05T11:00:00",
        "cancel_reason": "단순 변심",
        "request_date": "2026-07-04T09:00:00",
        "complete_date": "2026-07-05T11:00:00",
        "last_updated_date": "2026-07-05T11:00:00",
        "status": "active",
        "claim_products": [
          {
            "customer_order_code": "ORD-20260707-001",
            "product_code": "10000195",
            "product_name": "베이직 코튼 티셔츠",
            "option_name": "블랙/M",
            "quantity": 2,
            "price": 20000,
            "cancel_quantity": 2
          }
        ]
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
claim_status: received(접수) · completed(완료) · on_hold(보류) · rejected(불가) · reviewing(확인중)
refund_status: completed(완료) · pending(미처리)
status: active / deleted
claim_type=exchange이면 claim_exchange_products[]가 추가됩니다. 교환 처리 완료 시 항목에 order_product_code가 포함됩니다.

거래처

거래처 목록 조회

매입처·매출처(셀러) 거래처 목록을 조회합니다. partner_type 값으로 유형을 구분하며, 삭제되지 않은 거래처만 반환됩니다. 기본 정렬은 partner_code 내림차순입니다.

GET/v1/admin/partners scope partner.read

쿼리 파라미터

파라미터타입설명
partner_type필수stringpurchaser(매입처) · seller(매출처/셀러)
cursor선택int페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100
partner_type 값
purchaser · 매입처seller · 매출처(셀러)

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/partners?partner_type=seller&limit=100" \
  -H "Authorization: Bearer {access_token}"

응답 예시 (partner_type=seller · 예치금 사용)

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "partner_code": 2594,
        "partner_type": "seller",
        "registered_at": "2024-03-12T10:20:00",
        "business_number": "123-45-67890",
        "company_name": "테스트셀러",
        "business_type": "도소매",
        "business_item": "의류",
        "ceo_name": "홍길동",
        "tel": "02-1234-5678",
        "mobile": "010-1234-5678",
        "fax": "02-1234-5679",
        "order_email": "order@example.com",
        "statement_email": "statement@example.com",
        "tax_invoice_email": "tax@example.com",
        "zip": "06236",
        "address1": "서울시 강남구 테헤란로 1",
        "address2": "101호",
        "address": "서울시 강남구 테헤란로 1 101호",
        "memo": "",
        "account_id": "seller01",
        "account_enabled": true,
        "status": "active",
        "manage_group_code": 1,
        "manage_group": "기본그룹",
        "price_group_code": 3,
        "price_group": "A그룹",
        "point_balance": 12000,
        "deposit_balance": 150000
      }
    ],
    "next_cursor": 2594,
    "has_more": true
  }
}

응답 필드

필드타입설명
partner_codeint거래처 고유번호
partner_typestringpurchaser · seller
registered_atdatetime등록일시
business_numberstring사업자번호
company_namestring거래처명
business_typestring업태
business_itemstring종목
ceo_namestring대표자
telstring전화
mobilestring휴대폰
faxstring팩스
order_emailstring주문서 수신 이메일
statement_emailstring거래명세표 수신 이메일
tax_invoice_emailstring세금계산서 수신 이메일
zipstring우편번호
address1string주소
address2string상세주소
addressstring주소 전체(address1 + address2)
memostring메모
account_idstring|null계정 아이디 (미사용 시 null)
account_enabledboolean계정 사용 여부
statusstringinactive · active · pending
manage_group_codeint|null관리그룹 코드
manage_groupstring|null관리그룹명
price_group_codeint|null공급가그룹 코드 — seller만
price_groupstring|null공급가그룹명 — seller만
point_balanceint적립금 잔액 — seller만
deposit_balanceint예치금 잔액 — seller + 예치금 사용 시에만
status: inactive(미사용) · active(사용) · pending(인증대기)
account_enabledfalse이면 account_idnull입니다.
예치금(deposit_balance)은 사이트 설정(use_deposit)이 켜져 있을 때만 매출처(partner_type=seller) 응답에 포함됩니다.
!
400partner_type 값이 purchaser/seller가 아님. 403 — 스코프 부족 또는 admin 클라이언트가 아님.

거래처 등록

매입처·매출처 거래처를 등록합니다. 계정 사용 시 account_id·account_password가 필수입니다.

POST/v1/admin/partners scope partner.write

요청 본문

파라미터타입설명
partner_type필수stringpurchaser · seller
company_name필수string거래처명
business_number선택string사업자번호
business_type선택string업태
business_item선택string종목
ceo_name선택string대표자
tel / mobile / fax선택string연락처
order_email / statement_email / tax_invoice_email선택string수신 이메일
zip / address1 / address2선택string주소
memo선택string메모
status선택string기본 active
manage_group_code선택int관리그룹 코드
price_group_code선택int공급가그룹 코드 — seller만
account_enabled선택boolean계정 사용 여부, 기본 false
account_id조건부string계정 사용 시 필수 (최대 20자)
account_password조건부string계정 사용 시 필수 (최대 20자)

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/partners" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_type": "seller",
    "company_name": "테스트셀러",
    "business_number": "123-45-67890",
    "ceo_name": "홍길동",
    "mobile": "010-1234-5678",
    "order_email": "order@example.com",
    "zip": "06236",
    "address1": "서울시 강남구 테헤란로 1",
    "address2": "101호",
    "status": "active",
    "price_group_code": 3,
    "account_enabled": true,
    "account_id": "seller01",
    "account_password": "pass1234"
  }'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "partner_code": 2595,
    "partner_type": "seller",
    "company_name": "테스트셀러",
    "status": "active",
    "price_group_code": 3,
    "account_enabled": true,
    "account_id": "seller01"
  }
}
!
409 — 계정 아이디 중복. 400 — 필수값 누락 또는 그룹 코드 오류.

거래처 수정

기존 거래처 정보를 수정합니다. 전달하지 않은 필드는 기존 값을 유지합니다. partner_type은 변경할 수 없습니다.

POST/v1/admin/partners/update scope partner.write

요청 본문

파라미터타입설명
partner_code필수int수정할 거래처 코드
company_name선택mixed등록 API와 동일한 수정 가능 필드
account_password선택string전달 시에만 변경

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/partners/update" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_code": 2595,
    "company_name": "테스트셀러(수정)",
    "price_group_code": 3,
    "status": "active"
  }'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "partner_code": 2595,
    "partner_type": "seller",
    "company_name": "테스트셀러(수정)",
    "status": "active"
  }
}
!
404 — 존재하지 않거나 삭제된 거래처. 409 — 계정 아이디 중복.

거래처 삭제

거래처를 삭제(soft delete)합니다. 주문 이력이 있는 거래처는 삭제되지 않습니다.

POST/v1/admin/partners/delete scope partner.write

요청 본문

파라미터타입설명
partner_code필수int삭제할 거래처 코드

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/partners/delete" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_code": 2595
  }'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "partner_code": 2595,
    "company_name": "테스트셀러",
    "partner_type": "seller",
    "deleted": true
  }
}

주문 이력 존재 시 삭제 실패 예시

JSON · 409 Conflict
{
  "success": false,
  "message": "주문 이력이 있는 거래처는 삭제할 수 없습니다.",
  "data": {
    "partner_code": 2595,
    "order_count": 42
  }
}
!
404 — 존재하지 않거나 이미 삭제된 거래처. 409 — 주문 이력이 있어 삭제 불가.

관리그룹

관리그룹 목록 조회

거래처 관리그룹 목록을 조회합니다. partner_type으로 매입처/매출처 그룹을 구분하며, 삭제되지 않은 그룹만 반환됩니다.

GET/v1/admin/manage_groups scope manage_group.read

쿼리 파라미터

파라미터타입설명
partner_type필수stringpurchaser(매입처) · seller(매출처)
keyword선택string그룹명 부분 검색 (LIKE)
cursor선택int페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/manage_groups?partner_type=seller&limit=100" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "manage_group_code": 1,
        "manage_group": "기본그룹",
        "partner_type": "seller",
        "created_at": "2026-05-01T10:00:00"
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}

관리그룹 등록

관리그룹을 새로 등록합니다. 동일 partner_type 내 그룹명 중복 시 409를 반환합니다.

POST/v1/admin/manage_groups scope manage_group.write

요청 본문

파라미터타입설명
partner_type필수stringpurchaser · seller
manage_group필수string그룹명

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/manage_groups" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_type": "seller",
    "manage_group": "기본그룹"
  }'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "manage_group_code": 1,
    "manage_group": "기본그룹",
    "partner_type": "seller"
  }
}
!
409 — 동일 partner_type 내 그룹명 중복.

관리그룹 수정

관리그룹명을 수정합니다. partner_type은 변경할 수 없습니다.

POST/v1/admin/manage_groups/update scope manage_group.write

요청 본문

파라미터타입설명
manage_group_code필수int수정할 관리그룹 코드
manage_group필수string그룹명

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/manage_groups/update" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "manage_group_code": 1,
    "manage_group": "VIP그룹"
  }'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "manage_group_code": 1,
    "manage_group": "VIP그룹",
    "partner_type": "seller"
  }
}

관리그룹 삭제

관리그룹을 삭제(soft delete)합니다. 해당 그룹이 적용된 거래처가 있으면 삭제되지 않습니다.

POST/v1/admin/manage_groups/delete scope manage_group.write

요청 본문

파라미터타입설명
manage_group_code필수int삭제할 관리그룹 코드

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/manage_groups/delete" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "manage_group_code": 1
  }'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "manage_group_code": 1,
    "manage_group": "VIP그룹",
    "partner_type": "seller",
    "deleted": true
  }
}

거래처 적용 중 삭제 실패 예시

JSON · 409 Conflict
{
  "success": false,
  "message": "관리그룹이 적용된 거래처가 있어 삭제할 수 없습니다.",
  "data": {
    "manage_group_code": 1,
    "partner_count": 8
  }
}
!
404 — 존재하지 않거나 이미 삭제된 그룹. 409 — 적용된 거래처가 있어 삭제 불가.

공급가그룹

공급가그룹 목록 조회

매출처(셀러)에 적용하는 공급가그룹 목록을 조회합니다. 삭제되지 않은 그룹만 반환되며, 기본 정렬은 price_group_code 내림차순입니다.

GET/v1/admin/price_groups scope price_group.read

쿼리 파라미터

파라미터타입설명
keyword선택string그룹명 부분 검색 (LIKE)
cursor선택int페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/admin/price_groups?limit=100" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "price_group_code": 3,
        "price_group": "A그룹",
        "sell_rate": 95,
        "description": "",
        "created_at": "2026-05-31T23:05:27"
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}

응답 필드

필드타입설명
price_group_codeint공급가그룹 코드
price_groupstring그룹명
sell_rateint공급율(0~100, %)
descriptionstring설명
created_atdatetime등록일시

공급가그룹 등록

공급가그룹을 새로 등록합니다. 동일 그룹명이 이미 있으면 409를 반환합니다.

POST/v1/admin/price_groups scope price_group.write

요청 본문

파라미터타입설명
price_group필수string그룹명
sell_rate필수int공급율 (0~100)
description선택string설명

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/price_groups" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "price_group": "A그룹",
    "sell_rate": 95,
    "description": ""
  }'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "price_group_code": 4,
    "price_group": "A그룹",
    "sell_rate": 95,
    "description": ""
  }
}
!
409 — 동일 그룹명 중복. 400 — 필수값 누락 또는 sell_rate 범위 오류.

공급가그룹 수정

기존 공급가그룹을 수정합니다. 전달하지 않은 필드는 기존 값을 유지합니다.

POST/v1/admin/price_groups/update scope price_group.write

요청 본문

파라미터타입설명
price_group_code필수int수정할 공급가그룹 코드
price_group선택string그룹명
sell_rate선택int공급율 (0~100)
description선택string설명

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/price_groups/update" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "price_group_code": 3,
    "price_group": "A그룹",
    "sell_rate": 98
  }'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "price_group_code": 3,
    "price_group": "A그룹",
    "sell_rate": 98,
    "description": ""
  }
}
!
404 — 존재하지 않거나 삭제된 그룹. 409 — 동일 그룹명 중복.

공급가그룹 삭제

공급가그룹을 삭제(soft delete)합니다. 해당 그룹이 적용된 거래처가 하나라도 있으면 삭제되지 않습니다.

POST/v1/admin/price_groups/delete scope price_group.write

요청 본문

파라미터타입설명
price_group_code필수int삭제할 공급가그룹 코드

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/admin/price_groups/delete" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "price_group_code": 3
  }'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "price_group_code": 3,
    "price_group": "A그룹",
    "deleted": true
  }
}

거래처 적용 중 삭제 실패 예시

JSON · 409 Conflict
{
  "success": false,
  "message": "공급가그룹이 적용된 거래처가 있어 삭제할 수 없습니다.",
  "data": {
    "price_group_code": 3,
    "partner_count": 12
  }
}
!
404 — 존재하지 않거나 이미 삭제된 그룹. 409 — 적용된 거래처가 있어 삭제 불가 (partner_count에 적용 거래처 수 포함).
어드민플러스 Open API (Admin)
문의: yatta78@gmail.com · URL: https://www.adminplus.co.kr