Agent Commerce API
국산24는 AI 에이전트가 구매자의 위임 한도 안에서 상품을 조회하고 견적·주문까지 직접 실행하는 Agent-to-Agent 커머스 API를 제공합니다. 노출되는 상품은 전부 국산 검증 (사람 검수 승인)을 통과한 것만입니다.
기본 정보
- Base URL:
https://api.kr-market.co.kr/agent/v1 - 형식: JSON / UTF-8. 금액은 KRW 정수입니다.
- 명세: openapi.yaml 내려받기
- 키 발급: 현재 수동 등록입니다 — 고객센터로 문의하면 keyId·secret을 발급합니다(secret은 발급 시 1회만 표시).
인증 — HMAC-SHA256
모든 요청에 서명 헤더가 필요합니다. 서명 대상 문자열은 다음 4줄이며, secret으로 HMAC-SHA256 후 Base64 인코딩합니다. 타임스탬프는 ±300초까지 허용됩니다.
METHOD\nPATH(쿼리 제외)\nSHA256hex(body)\nunix-timestamp Authorization: A2A-HMAC-SHA256 keyId=<keyId>, ts=<unix-ts>, sig=<base64-hmac>
멱등성
쓰기 요청(POST /quotes·/orders·/delegations)에는
Idempotency-Key 헤더가 필수입니다. 같은 키의 재요청은 24시간 동안 저장된
응답을 재생하고, 같은 키에 다른 본문이 오면 409를 반환합니다.
위임 모델 — 기본 잠금
에이전트는 기본적으로 아무것도 살 수 없습니다. 흐름은 다음과 같습니다.
- 에이전트가 구매자 이메일로 위임을 요청합니다(
POST /delegations— 항상 202). - 구매자가 국산24 웹에 로그인해 1회 한도·누적 한도·유효기간을 직접 확정하고 승인합니다 (1회 한도 상한 500,000원).
- 한도 안의 주문은 즉시 생성되고, 한도를 넘는 주문은 구매자 승인 대기 상태가 됩니다.
- 결제 실행은 현재 구매자가 웹에서 합니다(자동결제는 추후 제공 예정).
엔드포인트
| 메서드·경로 | 설명 |
|---|---|
GET /products | 상품 검색(커서 페이지네이션, 카테고리·가격 필터) |
GET /products/{sku} | 상품 단건 — 검증 상태·인증 목록 포함 |
POST /quotes | 견적 — 가격·재고 스냅샷. 행사 중이면 적용 단가(unitPrice)와 정가(listPrice)를 함께 반환 |
POST /orders | 주문 생성 — 위임 기반, 한도 판정 |
GET /orders/{orderNo} | 주문 상태 조회(자기 에이전트 주문만) |
POST /delegations | 위임 요청(이메일 존재 비노출 — 항상 202) |
GET /delegations/{id} | 위임 상태·한도·누적 사용액 조회 |