AdminPlus

어드민플러스 OPEN API

AdminPlus API는 상품 조회부터 주문 등록, 결제 접수, 예치금·적립금 관리까지 커머스 운영에 필요한 모든 기능을 REST 방식으로 제공합니다. 토큰 발급 후 바로 시작할 수 있습니다.

주문 · 결제 흐름

접수부터 완료까지

주문 등록 → 결제 접수 → 결제 완료 순으로 진행됩니다. 결제 수단에 따라 즉시 완료되거나, 입금 확인 후 완료됩니다.

1

주문 등록

상품코드 또는 상품문자열 매칭으로 상품을 지정하고, 주문자·수령자 정보를 입력해 주문을 등록합니다. (상품 목록 · 상품 매칭 · 주문 등록)

2

결제 주문 접수

접수된 주문에 대해 결제를 생성합니다. 예치금·적립금·무통장을 조합할 수 있으며, 결제 금액 합계는 주문 금액과 일치해야 합니다. (결제 접수)

3

결제 완료

결제 수단에 따라 주문 완료 시점이 달라집니다.

예치금 · 적립금 전액 결제 접수와 동시에 주문이 완료됩니다.
무통장 입금 입금이 확인된 뒤 주문이 완료 처리됩니다.
4

진행 상황 조회

이후 배송 상태·운송장 등 주문 진행 상황은 주문 조회로 확인할 수 있습니다. (주문 조회)

기본 정보

엔드포인트와 공통 규칙

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

BASE https://api.adminplus.co.kr
구분내용
프로토콜HTTPS
인증 방식Bearer Token (OAuth 2.0 Client Credentials)
요청 본문POST 계열은 application/json (토큰 발급은 x-www-form-urlencoded)
날짜 형식YYYY-MM-DDTHH:ii:ss (예: 2026-07-07T12:00:00)
인코딩UTF-8 (이모지는 저장 시 자동 제거)

공통 요청 헤더

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

응답 형식

일관된 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_more가 false가 될 때까지 반복합니다.

필드타입설명
items / datas / ordersarray결과 목록
next_cursorstring|int|null다음 페이지 커서 (마지막 페이지면 null)
has_moreboolean다음 페이지 존재 여부

에러 & 요청 제한

HTTP 상태 코드

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

Rate Limit

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

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

인증

토큰 발급

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

POST /oauth/token

요청 파라미터 (form-urlencoded)

파라미터타입설명
client_id필수string발급받은 클라이언트 ID
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)

엔드포인트별 필요 권한

거래처마다 허용된 스코프가 다릅니다. 필요한 스코프가 없으면 403 permission denied가 반환됩니다.

product.read
상품 목록·변경분 조회
order.read
주문 조회·변경분·클레임·매칭 조회
order.write
주문 등록, 매칭 등록·삭제
order.delete
주문 삭제
bank.read
은행계좌(무통장 계좌) 조회
payment.read
결제 대기·결제 조회
payment.delete
결제 삭제
deposit.read
예치금 내역 조회
deposit.write
예치금 충전·예치금 충전 목록 조회
deposit.delete
예치금 충전 취소
point.read
적립금 내역 조회
balance.read
예치금&적립금 잔액조회

상품

상품 목록 조회

거래처에 노출되는 상품 목록을 조회합니다. 거래처별 판매가·옵션·재고·배송정책이 함께 반환됩니다. 기본 정렬은 수정일·idx 오름차순입니다.

GET/v1/seller/products scope product.read

쿼리 파라미터

파라미터타입설명
cursor선택string페이지네이션(이전 응답의 next_cursor)
product_code선택int특정 상품코드로 필터
product_name선택string상품명 부분 검색 (LIKE)
sale_status선택stringselling(판매중) · soldout(품절)
status선택stringactive · inactive · deleted (미지정 시 삭제 제외)
limit선택int1~500, 기본 100

요청 예시

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

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "product_code": 10000195,
        "name": "베이직 코튼 티셔츠",
        "taxable": "과세",
        "price": 10000,
        "image": "https://cdn1.yourlove.co.kr/.../prtimg/xxx.jpg",
        "shipping_origin": "경기 광주",
        "delivery_policy": {
          "shipping_company": "CJ대한통운",
          "policy": "고정배송비",
          "details": "3000원"
        },
        "short_description": "부드러운 코튼 소재",
        "description": "<p>상세설명 HTML</p>",
        "order_cutoff_time": "오후 2시",
        "stock": "unlimited",
        "status": "active",
        "created_date": "2026-07-01T10:22:31",
        "last_updated_date": "2026-07-10T15:40:00",
        "option": [
          { "option_code": 428, "option_name": "블랙/M", "stock": "unlimited" },
          { "option_code": 429, "option_name": "블랙/L", "stock": "soldout" }
        ]
      }
    ],
    "next_cursor": "NzQwfDIwMjYtMDctMTAgMTU6NDA6MDA=",
    "has_more": true
  }
}
✓
stock은 unlimited·soldout 또는 재고 수량(숫자)으로 반환됩니다. status는 active·inactive·deleted입니다. 옵션이 없는 단일 상품은 option 필드가 생략됩니다.

상품 변경분 조회

특정 시각 이후 수정된 상품만 조회합니다. 전체 동기화 이후 증분 반영에 사용합니다. 응답 필드는 상품 목록과 동일합니다.

GET/v1/seller/products/changed scope product.read

쿼리 파라미터

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

요청 예시

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

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "product_code": 10000195,
        "name": "베이직 코튼 티셔츠",
        "taxable": "과세",
        "price": 10000,
        "image": "https://cdn1.yourlove.co.kr/.../prtimg/xxx.jpg",
        "shipping_origin": "경기 광주",
        "delivery_policy": {
          "shipping_company": "CJ대한통운",
          "policy": "고정배송비",
          "details": "3000원"
        },
        "short_description": "부드러운 코튼 소재",
        "description": "<p>상세설명 HTML</p>",
        "order_cutoff_time": "오후 2시",
        "stock": "unlimited",
        "status": "active",
        "created_date": "2026-07-01T10:22:31",
        "last_updated_date": "2026-07-10T15:40:00",
        "option": [
          { "option_code": 428, "option_name": "블랙/M", "stock": "unlimited" },
          { "option_code": 429, "option_name": "블랙/L", "stock": "soldout" }
        ]
      }
    ],
    "next_cursor": "NzQwfDIwMjYtMDctMTAgMTU6NDA6MDA=",
    "has_more": true
  }
}
✓
삭제된 상품(status: deleted)도 변경분에 포함될 수 있습니다. has_more가 true이면 next_cursor로 다음 페이지를 요청하세요.

상품 매칭

매칭 등록

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

POST/v1/seller/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로 매칭된 문자열을 알려주어 검토에 활용할 수 있습니다. 상품을 아직 정하지 않았다면 매칭 등록(임시)를 사용하세요.

매칭 등록 (임시)

매칭 문자열과 메모만으로 임시 등록합니다. 상품·옵션은 비워 두며, 주문 자동매칭에는 사용되지 않습니다. 등록 후 협력사 계정 메뉴 OPEN API > 상품문자열 매칭내역에서 수기로 상품을 매칭할 수 있습니다.

POST/v1/seller/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"
      }
    ]
  }
}
✓
수기 매칭 안내 — API로 임시 등록한 뒤, 협력사(어드민플러스) 계정에서 OPEN API > 상품문자열 매칭내역 메뉴로 이동해 해당 문자열에 상품·옵션을 지정하세요. 수기 매칭이 완료되면 주문 등록 시 자동 매칭에 사용됩니다.
등록 가능한 건은 저장하고, 중복·오류 건만 data.errors[]에 담아 함께 반환합니다. (이미 상품 매칭됨 / 이미 임시등록됨 등)
요청 전체가 실패한 경우에만 400 validation failed가 반환됩니다.

매칭 조회

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

GET/v1/seller/product_matches scope order.read

쿼리 파라미터

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

응답 예시

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-07 10:00:00", "moddate": "2026-07-07 10:00:00" },
          { "match_id": 102, "product_code": 10000196, "option_code": null, "qty": 1, "regdate": "2026-07-07 10:00:00", "moddate": "2026-07-07 10: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-07 10:00:00", "moddate": "2026-07-07 10:00:00" }
        ]
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
✓
is_temp가 true이면 수기 매칭 대기 상태입니다. is_one_to_many는 상품이 2개 이상이거나 수량(qty)이 1보다 큰 경우 true입니다. 페이지 경계에서 같은 문자열이 잘리지 않도록 그룹 단위로 잘립니다.

매칭 삭제

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

POST/v1/seller/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로 주문·상품·수취인 정보를 통합 검색할 수 있으며, 상품별 배송 상태·운송장 정보가 함께 반환됩니다. 최대 조회기간은 1년이며, 등록일(regdate) 기준 최근 1년 이내 주문만 조회됩니다. 같은 경로에 POST하면 주문 등록이 됩니다. 수정일 기준 증분 조회는 주문 변경분을 사용하세요.

GET/v1/seller/orders scope order.read

쿼리 파라미터

파라미터타입설명
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/seller/orders?keyword=이수령" \
  -H "Authorization: Bearer {access_token}"

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

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "orders": [
      {
        "order_code": "2607062329371272790002",
        "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,
            "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
  }
}
✓
상품 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(기타)

주문 변경분 조회

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

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

쿼리 파라미터

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

요청 예시

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

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "orders": [
      {
        "order_code": "2607062329371272790002",
        "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,
            "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
  }
}
✓
주문 status는 active / deleted입니다. 삭제된 주문의 상품 status는 deleted입니다. payment_status는 주문 조회와 동일하게 paid / unpaid입니다.

주문 등록

한 번에 최대 100건의 주문을 등록합니다. POST /v1/seller/orders로 호출합니다(GET은 주문 조회). 각 상품은 product_code 또는 product_string 중 하나만 입력합니다. product_string을 넣으면 미리 등록한 매칭 규칙으로 자동 매칭·1:N 확장됩니다.

POST/v1/seller/orders scope order.write

요청 본문

필드타입설명
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/seller/orders" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
  "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
{
  "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[]에 항목별 사유(주문번호 누락, product_code/product_string 동시 입력, 매칭 실패, 품절 등)가 담깁니다.

주문 삭제

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

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

요청 본문

필드타입설명
order_key필수string주문 등록 응답의 order_key

요청 / 응답 예시

JSON
// 요청
{ "order_key": "66a4b1c2e9f3d" }

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

결제

결제 대기 조회

API로 등록되어 아직 결제되지 않은 주문(결제 대기) 목록을 조회합니다. 결제 접수·결제 조회는 /v1/seller/payments를 사용하세요.

GET/v1/seller/payments/pending scope payment.read

쿼리 파라미터

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

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "datas": [
      {
        "tmep_idx": 5521,
        "regdate": "2026-07-07T12:00:00",
        "total_amount": 23000,
        "order_key": "66a4b1c2e9f3d"
      }
    ],
    "next_cursor": 5521,
    "has_more": false
  }
}

결제 조회

결제가 접수·완료된 내역을 조회합니다. GET /v1/seller/payments로 호출합니다(POST는 결제 접수). 결제 수단별(예치금·적립금·무통장) 상세와 현금영수증 정보를 포함합니다.

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

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

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

요청 예시

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

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

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "datas": [
      {
        "payment_idx": 8801,
        "payment_key": "17203948821234587",
        "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[].method는 deposit(예치금) · point(적립금) · bank(무통장입금)입니다. payment_key만으로도 단건 조회할 수 있습니다.

결제 접수

여러 주문(order_key)을 묶어 결제를 접수합니다. POST /v1/seller/payments로 호출합니다(GET은 결제 조회). 결제 수단은 예치금·적립금·무통장을 조합할 수 있으며, 결제 금액 합계가 주문 금액과 정확히 일치해야 합니다.

POST/v1/seller/payments Bearer 필요

요청 본문

필드타입설명
order_key필수string[]주문키 배열 (최대 20개)
payments필수array결제 수단 목록
└ method필수stringdeposit(예치금) · point(적립금) · bank(무통장)
└ amount필수int해당 수단으로 결제할 금액
└ depositorbank 필수string입금자명
└ account_codebank 필수string무통장 계좌 코드 (은행계좌 조회)
└ cash_receipt조건부object현금영수증 정보. method가 bank일 때만 전달. 가맹 설정에 따라 필수/선택/불가 (아래 안내)
  └ issue선택stringY(발행) · N(미발행). 기본 N
  └ type발행 시 필수stringPERSONAL(개인·휴대폰) · BUSINESS(사업자)
  └ number발행 시 필수stringPERSONAL: 휴대폰 10~11자리 / BUSINESS: 사업자번호 10자리

요청 예시 · 예치금 + 무통장 조합

cURL
curl -X POST "https://api.adminplus.co.kr/v1/seller/payments" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
  "order_key": ["66a4b1c2e9f3d", "66a45fade6589"],
  "payments": [
    { "method": "deposit", "amount": 3000 },
    { "method": "point", "amount": 0 },
    {
      "method": "bank",
      "amount": 20000,
      "account_code": "5",
      "depositor": "홍길동",
      "cash_receipt": {
        "issue": "Y",
        "type": "BUSINESS",
        "number": "8803200824"
      }
    }
  ]
}'

요청 예시 · 예치금 전액

예치금으로 주문 금액을 전액 결제합니다. 접수와 동시에 결제가 완료됩니다. (강제 현금영수증 가맹은 아래 예시 참고)

JSON
{
  "order_key": ["6a7022e9cebb7"],
  "payments": [
    { "method": "deposit", "amount": 32000 },
    { "method": "point", "amount": 0 }
  ]
}

요청 예시 · 예치금 전액 + 강제 현금영수증

강제 현금영수증 발행 가맹에서는 예치금 전액 결제이어도 method: "bank"로 현금영수증 정보를 함께 보내야 합니다. 무통장 금액은 0으로 두고, 실제 결제 금액은 예치금에 넣습니다.

JSON
{
  "order_key": ["6a7022e9cebb7"],
  "payments": [
    { "method": "deposit", "amount": 32000 },
    { "method": "point", "amount": 0 },
    {
      "method": "bank",
      "amount": 0,
      "account_code": "5",
      "depositor": "홍길동",
      "cash_receipt": {
        "issue": "Y",
        "type": "BUSINESS",
        "number": "8803200824"
      }
    }
  ]
}

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": { "payment_key": "1720394882123458" }
}
※
현금영수증 안내 — 운영업체 설정에 따라 동작이 달라집니다. 현금영수증은 method: "bank"의 cash_receipt로만 전달합니다.
· 미지원 가맹: 발행 정보(issue:"Y" 등)를 보내면 400 현금영수증 발행가맹점이 아닙니다
· 강제 발행 가맹: issue:"Y" + type + number 필수. 없으면 400 강제 현금영수증 발행 가맹점입니다. 예치금·적립금 전액 결제이어도 발행을 위해 bank 수단을 포함하고 현금영수증을 입력해야 합니다 (위 예시 참고)
· 선택 발행 가맹: 미발행은 생략 또는 {"issue":"N"}. 발행 시 type은 PERSONAL(휴대폰 10~11자리) 또는 BUSINESS(사업자 10자리)
!
금액 불일치 시 400 결제금액이 주문금액과 일치하지 않습니다.. 존재하지 않는 order_key 또는 이미 결제된 order_key는 409가 반환됩니다. 예치금·적립금 부족 시에도 400이 반환됩니다.

결제 삭제

접수된 결제를 삭제합니다. 입금이 확인된 결제 대기내역은 삭제할 수 없습니다.

POST/v1/seller/payments/delete scope payment.delete

요청 / 응답 예시

JSON
// 요청
{ "payment_key": "1720394882123458" }

// 응답 200 OK
{
  "success": true,
  "message": "success",
  "data": { "message": "결제 데이터가 삭제되었습니다." }
}
!
400 입금내역이 확인되어 삭제할 수 없습니다.

예치금 & 적립금

예치금 충전

무통장 입금으로 예치금을 충전 접수합니다. POST /v1/seller/deposits로 호출합니다(GET은 예치금 충전 목록). 응답으로 입금할 계좌 정보와 charge_key를 반환합니다.

POST/v1/seller/deposits scope deposit.write

요청 본문

필드타입설명
account_code필수int무통장 계좌 코드 (은행계좌 조회)
deposit_amount필수int충전(입금) 금액
depositor필수string입금자명

요청 예시

cURL
curl -X POST "https://api.adminplus.co.kr/v1/seller/deposits" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "account_code": 5, "deposit_amount": 100000, "depositor": "홍길동" }'

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "charge_key": "17203948821234",
    "bank_name": "국민은행",
    "account_number": "123-456-789",
    "account_holder": "(주)어드민플러스",
    "depositor": "홍길동",
    "amount": "100000"
  }
}

예치금 충전 목록

예치금 충전 접수 목록을 조회합니다. GET /v1/seller/deposits로 호출합니다(POST는 예치금 충전). charge_key가 없으면 전체 목록, 있으면 해당 건만 반환합니다.

GET/v1/seller/deposits scope deposit.write

쿼리 파라미터

파라미터타입설명
charge_key선택string충전 접수 시 받은 charge_key (지정 시 해당 건만 조회)
cursor선택int페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100

요청 예시

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

curl "https://api.adminplus.co.kr/v1/seller/deposits?charge_key=17203948821234" \
  -H "Authorization: Bearer {access_token}"

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "datas": [
      {
        "charge_idx": 1201,
        "charge_key": "17203948821234",
        "bank_name": "국민은행",
        "account_number": "123-456-789",
        "depositor": "홍길동",
        "amount": "100000",
        "paid": false,
        "paid_at": "0000-00-00 00:00:00",
        "created_at": "2026-07-07 13:00:00"
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
✓
paid가 true이면 입금 확인 완료입니다. 존재하지 않는 charge_key를 지정하면 400이 반환됩니다.

예치금 충전 취소

아직 입금되지 않은 예치금 충전 접수를 취소합니다. 입금이 확인된 건은 취소할 수 없습니다.

POST/v1/seller/deposits/delete scope deposit.delete

요청 / 응답 예시

JSON
// 요청
{ "charge_key": "17203948821234" }

// 응답 200 OK
{
  "success": true,
  "message": "success",
  "data": { "message": "예치금 충전 데이터가 삭제되었습니다." }
}

예치금 내역

예치금 충전·사용 내역과 잔액을 조회합니다.

GET/v1/seller/deposits/history scope deposit.read

쿼리 파라미터

파라미터타입설명
updated_since선택datetime등록일 기준 필터 (YYYY-MM-DDTHH:ii:ss)
cursor선택int페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "datas": [
      {
        "deposit_idx": 771,
        "type": "CHARGE",
        "amount": 100000,
        "balance": 150000,
        "memo": "예치금 충전",
        "created_at": "2026-07-07T13:00:00"
      },
      {
        "deposit_idx": 770,
        "type": "USE",
        "amount": -3000,
        "balance": 50000,
        "memo": "주문결제",
        "created_at": "2026-07-07T12:30:00"
      }
    ],
    "next_cursor": null,
    "has_more": false
  }
}
✓
type은 CHARGE(충전, amount 양수) 또는 USE(사용, amount 음수)입니다. balance는 해당 시점 잔액입니다.

적립금 내역

적립금 적립·사용 내역과 잔액을 조회합니다. 구조는 예치금 내역과 동일하며 point_idx 필드를 사용합니다.

GET/v1/seller/points/history scope point.read

쿼리 파라미터

파라미터타입설명
updated_since선택datetime등록일 기준 필터 (YYYY-MM-DDTHH:ii:ss)
cursor선택int페이지네이션(이전 응답의 next_cursor)
limit선택int1~500, 기본 100

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "datas": [
      {
        "point_idx": 512,
        "type": "CHARGE",
        "amount": 5000,
        "balance": 12000,
        "memo": "적립",
        "created_at": "2026-07-07T13:00:00"
      }
    ],
    "next_cursor": 512,
    "has_more": false
  }
}

예치금&적립금 잔액조회

사용가능한 예치금(deposit)·적립금(point) 잔액을 조회합니다. 별도 파라미터 없이 토큰 소유 거래처의 잔액을 반환합니다.

GET/v1/seller/balance scope balance.read

요청 예시

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

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "point_balance": 12000,
    "deposit_balance": 150000
  }
}
✓
point_balance는 적립금, deposit_balance는 예치금 잔액(원)입니다. 거래처 정보가 없으면 404가 반환됩니다.

클레임

클레임 조회

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

GET/v1/seller/claims scope order.read

쿼리 파라미터

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

요청 예시

cURL
curl "https://api.adminplus.co.kr/v1/seller/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",
        "order_code": "AP20260707001",
        "order_amount": 23000,
        "refund_product_amount": 20000,
        "refund_shipping_amount": 3000,
        "refund_total_amount": 23000,
        "refund_status": "completed",
        "refund_date": "2026-07-05 11:00:00",
        "cancel_reason": "단순 변심",
        "request_date": "2026-07-04 09:00:00",
        "complete_date": "2026-07-05 11:00:00",
        "last_updated_date": "2026-07-05 11: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가 포함됩니다.

은행계좌

은행계좌 조회

거래처에 등록된 무통장(은행) 계좌 목록을 조회합니다. 응답의 account_code는 예치금 충전·결제 접수(무통장) 요청 시 사용하는 계좌 코드입니다.

GET/v1/seller/banks scope bank.read

쿼리 파라미터

별도의 파라미터가 없습니다. 입금가능한 계좌 전체를 반환합니다.

요청 예시

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

응답 예시

JSON · 200 OK
{
  "success": true,
  "message": "success",
  "data": {
    "items": [
      {
        "account_code": 5,
        "bank_name": "국민은행",
        "account_number": "123-456-789",
        "account_holder": "(주)어드민플러스"
      }
    ]
  }
}
✓
account_code를 예치금 충전·결제 접수의 account_code 값으로 전달하세요.
어드민플러스 Open API
문의: yatta78@gmail.com · URL: https://www.adminplus.co.kr