읽기 전용 API와
데이터 해석 기준
공개 자료를 실제 조건과 함께 읽도록 만든 작은 API입니다. 현재 비교와 참고 자료를 구별하고, 모르는 수수료나 시간을 만들어 채우지 않습니다.
인증 없이 공개 열람합니다. 쓰기·업체 수정·개인 보유노트·상품권 코드·운영 설정은 제공하지 않습니다. 브라우저의 다른 출처에서 사용할 CORS는 기본적으로 열지 않습니다.
구현된 경로
아래 링크는 실제 JSON 응답을 반환합니다. 출시 전에 서버의 주소 연결을 확인하세요.
/api/v1/은 status와 같습니다. 알 수 없는 리소스는 404, 잘못된 입력은 400, GET·HEAD 외 요청은 405를 반환합니다.
입력 범위
| 항목 | 사용 경로 | 허용 범위 |
|---|---|---|
q | catalog, quotes | 단일 문자열 최대 80자. 상품권·업체·조건 검색. |
card | catalog, quotes | catalog에 실제 존재하는 slug. 예: shinsegae. |
amount | quotes | 원 단위 정수 1~100,000,000. 기본 100,000. |
direction | quotes | all, sell(이용자 팔기·업체 매입), buy(이용자 구매·업체 판매). 기본 all. |
state | quotes | all, current, stale, unverified, missing_source, unknown_fee. 기본 all. 누락 원문·시각 행은 quotes 공개에서 제외하므로 해당 필터가 빈 결과일 수 있습니다. |
limit | catalog, quotes | 1~100. 기본 50. |
offset | catalog, quotes | 0~10,000. 기본 0. total은 페이지 분리 전 조건에 맞는 공개 행 수입니다. |
목록에 없는 입력, 배열 형태의 입력, 중복 항목, 범위 밖 값은 400입니다. resource는 예약 항목이며 URL 검색 인수로 지정할 수 없습니다. status·coverage·version에는 검색 인수를 받지 않습니다. 제한 상품권은 사전에 표시할 수 있지만 가격행은 공개 견적에서 제외합니다.
호출과 응답 예시
실제 가격을 흉내 낸 예시값을 제공하지 않습니다.
GET /api/v1/quotes/?card=shinsegae&direction=sell&amount=100000&limit=20 Accept: application/json
{
"meta": {
"api_version": "1.0"
},
"amount_krw": 100000,
"current": [],
"reference": [],
"note": "빈 배열도 정상 응답입니다. 예시 가격을 채우지 않습니다."
}실제 응답에는 total·limit·offset과 자료 범위가 추가됩니다. current와 reference는 같은 페이지의 행을 상태별로 나눈 배열입니다. 두 배열을 합친 개수는 해당 페이지의 반환 행 수입니다.
가격 필드를 읽는 방법
| 필드 | 의미·한계 |
|---|---|
rate_percent | 원문에 저장된 비율. 액면 대비 비율이며 실제 지급 보증이 아닙니다. |
quoted_amount_krw | 입력 액면 × 저장 비율을 원 단위로 내림한 참고 추정. 권종·금액 범위의 적용 여부를 자동 해석하지 않습니다. |
fee_krw / fee_known | 명시된 매입 수수료가 있을 때만 정수/true. 없음과 미확인은 다릅니다. 미확인은 null/false. |
net_receipt_krw | 이용자 팔기의 참고 수령액. 수수료 미확인 또는 구매 방향이면 null. 오래된 행의 계산은 참고이며 현재 추천에 쓰지 않습니다. |
total_purchase_cost_krw | 현재 자료에는 구매 수수료가 별도 구조화되지 않아 null. 원문 판매가를 총지출로 바꾸지 않습니다. |
checked_at | 기존 저장 자료의 확인시각, ISO 8601 한국 시간대. 별도 수집 관찰시각인지 원문 기준시각인지 추정하지 않습니다. |
price_basis_at / observed_at / reviewed_at | 별도 기록이 있을 때만 실제 저장된 ISO 8601 시각을 반환합니다. 기존 행에 독립 시각이 없으면 null이며 checked_at에서 추정하지 않습니다. reviewed_at은 실제 운영자 검토 기록의 시각이며 가격을 새로 확인한 시각을 뜻하지 않습니다. |
condition / source_url | 길이를 제한한 일반 텍스트 조건과 공개 HTTPS 원문. 원문 HTML·내부 설정을 반환하지 않습니다. |
상태는 네 가지 축으로 구별합니다
source_type · 자료 경로
collected_public은 자동 수집, stored_public은 기존 공개 기록, operator_recorded는 운영자 직접 기록입니다. 실제 제휴나 안전 인증을 뜻하지 않습니다.
verification_status · 기본 검사
basic_valid는 비율·업체명·HTTPS 원문·확인시각의 기본 형식 검사, operator_reviewed는 운영자 검토 기록도 있는 상태입니다. 수수료와 최신성은 별도 축이며 거래 안전성을 뜻하지 않습니다.
publication_status · 사용 범위
current_comparison은 현재 형식 기준과 명시 수수료를 함께 충족한 행, reference는 오래되거나 수수료가 미확인인 참고 행입니다. 제외 자료는 quotes에서 보내지 않습니다.
temporal_state · 시간 상태
최근 3일 이내를 current, 지난 자료는 stale로 구별합니다. 미래와 미확인 시각은 현재 비교와 공개 견적에서 제외합니다. 상태 기준은 status의 methodology로 확인하세요.
갱신 확인·오류·이용 조건
- 응답은 JSON UTF-8이며 특수 HTML 문자를 안전하게 인코딩합니다. 값은 HTML 문자열로 삽입하지 말고 텍스트로 출력하세요.
- 200 응답에는 ETag가 있습니다. 다음 요청의 If-None-Match가 일치하면 본문 없이 304를 반환합니다. HEAD도 GET과 같은 상태·헤더이며 본문이 없습니다.
- 현재 상태는 시간이 지나면 바뀔 수 있습니다. 캐시를 재검증하고 data_checked_latest 및 행별 checked_at과 temporal_state를 함께 확인하세요.
- 불필요한 반복 호출은 피하고 로컬 캐시와 조건부 요청을 사용하세요. 이 버전은 공개 열람 API이며 무제한 제공 또는 서비스 수준을 약속하지 않습니다.
- 상업적 재배포·원자료 판매·제삼자 서비스에 대한 권리를 자동으로 부여하지 않습니다. 원자료 제공자의 조건과 별도 협의 필요성을 확인하세요.
- 상덱스 관찰 범위를 전국 시장 전체의 평균이나 거래 안전 등급으로 표현하지 마세요. 출처·시점·표본·수수료 누락을 함께 설명하세요.
- 개인 상품권 코드, 바코드, 신분증, 개인 보유노트를 API에 보내지 마세요. 쓰기와 개인 자료 업로드 기능은 없습니다.
리소스 경로, 상품권 이름, 공개 원문, 문제 항목을 함께 알려주세요. 비밀키나 개인 거래 자료는 보내지 마세요.