API 문서 — api.midam.top

인증

API 콘솔에서 발급한 토큰을 HTTP 헤더에 넣어 호출합니다. 토큰 원문은 발급 시 한 번만 표시됩니다.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

항목	설명
일일 한도	회원별 설정 (기본 500회/일, KST 01:00 초기화)
차감 기준	상품 조회를 실제 시도한 경우 1회 차감 (인증 실패·파라미터 오류·한도 초과는 미차감)
토큰 발급	로그인 후 API 콘솔에서 발급

상품 상세 조회

getProductInfo

상품의 상세 정보(상품명, SKU, 가격, 재고, 이미지 등)를 조회합니다. 숫자 offerId, 상품 URL, openOfferId(키워드 검색 등에서 받은 암호화 ID)로 조회할 수 있습니다. 호출 시 일일 사용량에서 1회 차감됩니다.

POST /v1/apis/getProductInfo Bearer API 토큰

요청 헤더

헤더	값	필수
`Authorization`	`Bearer <API 토큰>`	필수
`Content-Type`	`application/json`	필수

요청 본문 (JSON)

POST 로 전달합니다. Content-Type: application/json

이름	타입	필수	기본값	설명
`offerId`	string	선택	—	숫자 상품 ID 또는 상품 상세 URL입니다. URL을 넣으면 경로 /offer/{id}.html 에서 id만 추출해 조회합니다. openOfferId와 함께 넣을 경우 openOfferId가 우선합니다. 예: `900331543129`
`openOfferId`	string	선택	—	1688 암호화 상품 ID입니다. keywordSearch 결과의 openOfferId를 그대로 넣을 수 있습니다. offerId와 둘 중 하나는 필수입니다. 예: `Wcv2w970KoL1BCpJGQp3vwKvcBThOPlpHnUtkK3T0n4=`
`channel`	string	선택	`other`	유통 채널 식별자입니다. 별도 값이 없으면 other 를 사용합니다. 예: `other`

요청 예시

offerId에는 숫자 상품 ID 또는 상품 상세 URL 중 하나를 넣습니다.

상품 ID (숫자)

{
  "offerId": "900331543129",
  "channel": "other"
}

상품 URL

{
  "offerId": "https://shop.example.com/offer/900331543129.html",
  "channel": "other"
}

openOfferId (암호화 ID)

{
  "openOfferId": "Wcv2w970KoL1BCpJGQp3vwKvcBThOPlpHnUtkK3T0n4=",
  "channel": "other"
}

성공 응답

HTTP 200 · success: true

{
  "success": true,
  "api": "getProductInfo",
  "data": {
    "raw": {
      "success": true,
      "productInfo": {}
    }
  },
  "usage": {
    "dailyLimit": 500,
    "usedToday": 1,
    "remainingToday": 499
  }
}

오류 응답

HTTP	code	message	비고
`400`	`INVALID_PARAMETER`	offerId(숫자 ID·상품 URL) 또는 openOfferId(암호화 ID) 중 하나는 필수입니다.	offerId·openOfferId 모두 누락
`401`	`INVALID_API_TOKEN`	유효한 Bearer 토큰이 필요합니다.	—
`401`	`TOKEN_DISABLED`	비활성화된 API 토큰입니다.	—
`401`	`TOKEN_EXPIRED`	만료된 API 토큰입니다.	—
`429`	`DAILY_LIMIT_EXCEEDED`	일일 API 호출 한도를 초과했습니다.	응답에 dailyLimit, usedToday, remainingToday 포함
`502`	`UPSTREAM_ERROR`	관리자에게 문의하세요.	detail.message 동일

cURL 예시

curl -X POST 'https://api.midam.top/v1/apis/getProductInfo' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"offerId":"900331543129","channel":"other"}'

키워드 검색 (중문)

keywordSearch

중문 키워드로 1688 상품을 검색합니다. 한중 번역 없이 입력한 keywords를 그대로 1688 product.keyword.search API에 전달합니다. 호출 시 일일 사용량에서 1회 차감됩니다.

POST /v1/apis/keywordSearch Bearer API 토큰

요청 헤더

헤더	값	필수
`Authorization`	`Bearer <API 토큰>`	필수
`Content-Type`	`application/json`	필수

요청 본문 (JSON)

POST 로 전달합니다. Content-Type: application/json

이름	타입	필수	기본값	설명
`keywords`	string	필수	—	중문 검색 키워드입니다. 한글·번역 변환 없이 그대로 전달됩니다. 예: `女装`
`pageNum`	number	선택	`1`	페이지 번호입니다. 예: `1`
`pageSize`	number	선택	`24`	페이지당 결과 수입니다. 최대 60입니다. 예: `24`

요청 예시

offerId에는 숫자 상품 ID 또는 상품 상세 URL 중 하나를 넣습니다.

기본 검색

{
  "keywords": "女装",
  "pageNum": 1,
  "pageSize": 24
}

다음 페이지

{
  "keywords": "女装",
  "pageNum": 2,
  "pageSize": 20
}

성공 응답

HTTP 200 · success: true

{
  "success": true,
  "api": "keywordSearch",
  "data": {
    "raw": {
      "success": true,
      "result": []
    }
  },
  "usage": {
    "dailyLimit": 500,
    "usedToday": 1,
    "remainingToday": 499
  }
}

오류 응답

HTTP	code	message	비고
`400`	`INVALID_PARAMETER`	keywords(중문 검색어)는 필수입니다.	keywords 누락·공백
`401`	`INVALID_API_TOKEN`	유효한 Bearer 토큰이 필요합니다.	—
`401`	`TOKEN_DISABLED`	비활성화된 API 토큰입니다.	—
`401`	`TOKEN_EXPIRED`	만료된 API 토큰입니다.	—
`429`	`DAILY_LIMIT_EXCEEDED`	일일 API 호출 한도를 초과했습니다.	응답에 dailyLimit, usedToday, remainingToday 포함
`502`	`UPSTREAM_ERROR`	관리자에게 문의하세요.	detail.message 동일

cURL 예시

curl -X POST 'https://api.midam.top/v1/apis/keywordSearch' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"keywords":"女装","pageNum":1,"pageSize":24}'

보조 API

계정·사용량 확인용 GET 엔드포인트입니다. 요청 본문 없이 Bearer 토큰만 필요합니다.

GET /v1/me 토큰에 연결된 회원 정보
GET /v1/me/tokens 내 API 토큰 목록(마스킹)
GET /v1/me/usage 오늘 사용량·남은 호출 수