발생한 매출에 대해 마감된 정보를 조회할 수 있습니다.
마감내역은 단말기별 상품별 또는 컬럼별로 집계된 건수·금액을 결제수단별로 제공합니다.
마감의 종류로는 수동마감과 자동마감이 존재합니다.
마감일자 기준 조회와 24시간 구간 조회 두 가지 방식을 지원합니다.company, token이 필요합니다. (API 시작하기 참고)GET, POST 방식을 모두 지원하며, 요청 Body는 사용하지 않습니다.404와 함께 closingList 필드가 제외된 응답이 전달됩니다.GET | POST /closing/{closingType}/{date}
단말기의 마감일자가 요청일자(date)인 거래를 집계하여 조회합니다.
오늘 날짜로 조회하는 경우, 아직 자동마감(23:59:59)이 진행되지 않았으므로 수동마감된 거래만 집계됩니다.
취소된 거래는 집계에서 제외됩니다.
요청에서 필요로 하는 필드는 다음과 같습니다.
| 필드명 | 필수 | 타입 | 설명 | 비고 |
|---|---|---|---|---|
| closingType | Y | String | 집계 유형 (Path) | product: 단말기 + 상품별 집계column: 단말기 + 컬럼별 집계 |
| date | Y | String | 마감일자 (Path) | YYYYMMDD 규격오늘 이후의 일자는 요청 불가 |
const API = axios.create({ baseURL: `http://api.ubcn.co.kr/api`, headers: { "company": "{company}", "token": "{token}", }, // 조회 결과가 없을 때 404가 응답되므로, 404는 정상 응답으로 처리합니다. validateStatus: (status) => status < 500,});
// get, post 모두 지원합니다.// 예시) 2026년 10월 15일 마감내역을 상품별로 조회const res = await API.get("/closing/product/20261015");
// 예시) 2026년 10월 15일 마감내역을 컬럼별로 조회const res2 = await API.get("/closing/column/20261015");
if (res.status === 200) { console.log(res.data.closingList);} else if (res.status === 404) { console.log("조회된 마감내역이 없습니다.");} else { // 요청 오류: code(존재하는 경우), message 를 확인합니다. console.error(res.data.code, res.data.message);}결과 값에 들어 있는 필드는 다음과 같습니다.
| 필드명 | 상세필드명 | 필수 | 타입 | 설명 | 비고 |
|---|---|---|---|---|---|
| type | - | Y | String | API 유형 | closing 고정 |
| message | - | Y | String | 응답 메시지 | 조회 성공: Get ClosingList at {date}결과 없음: No Result |
| closingDate | - | Y | String | 요청일자 | YYYY-MM-DD 형식 |
| decription | - | Y | String | API 상세설명 | 필드명 표기(decription)는 실제 응답 키 그대로입니다. |
| closingList | - | N | Array | 마감내역 리스트 | 객체 리스트 조회 결과가 없으면 필드 자체가 제외됨 |
| closingDate | Y | String | 마감일자 | YYYYMMDD | |
| terminalID | Y | String | 단말기 ID | UBCn 단말기 ID 필드명 대소문자에 유의 ( terminalID) | |
| terminalCode | Y | String | 단말기(자판기) 코드 | 가맹점 관리 단말기 코드 | |
| placeCode | Y | String | 위치코드(점포코드) | 미등록 시 - | |
| placeNo | Y | String | 위치순번(POS번호) | 미등록 시 - | |
| cabNo | Y | int | 머신기 캐비넷 번호 | column 집계 시 제공캐비넷 구분이 없거나 product 집계 시 0 | |
| colNo | Y | int | 머신기 컬럼번호 | column 집계 시 제공product 집계 시 0 | |
| productCode | N | String | 상품코드 | - | |
| productName | N | String | 상품명 | 상품 미등록 시 null | |
| productBarcode | Y | String | 상품 바코드 | 미등록 시 - | |
| totCnt | Y | int | 전체 매출수량 | 모든 결제수단 합계 | |
| totAmt | Y | int | 전체 매출금액 | 모든 결제수단 합계 | |
| cashCnt | Y | int | 현금 매출수량 | - | |
| cashAmt | Y | int | 현금 매출금액 | - | |
| cardCnt | Y | int | 신용카드 매출수량 | - | |
| cardAmt | Y | int | 신용카드 매출금액 | - | |
| tmnCnt | Y | int | 티머니 매출수량 | 선불카드 | |
| tmnAmt | Y | int | 티머니 매출금액 | 선불카드 | |
| csbCnt | Y | int | 이즐(캐시비) 매출수량 | 선불카드 | |
| csbAmt | Y | int | 이즐(캐시비) 매출금액 | 선불카드 | |
| mybCnt | Y | int | 마이비 매출수량 | 선불카드 | |
| mybAmt | Y | int | 마이비 매출금액 | 선불카드 | |
| krpCnt | Y | int | 레일플러스 매출수량 | 선불카드 | |
| krpAmt | Y | int | 레일플러스 매출금액 | 선불카드 | |
| npcCnt | Y | int | 페이코 매출수량 | 간편결제 | |
| npcAmt | Y | int | 페이코 매출금액 | 간편결제 | |
| kkpCnt | Y | int | 카카오페이 매출수량 | 간편결제 | |
| kkpAmt | Y | int | 카카오페이 매출금액 | 간편결제 |
아래 값은 이해를 돕기 위한 예시입니다. (상품별 집계, HTTP 200)
{ "type": "closing", "message": "Get ClosingList at 20261015", "closingDate": "2026-10-15", "decription": "단말기 마감일 기준으로 판매된 데이터를 추출합니다. 오늘날짜 조회의 경우, 수동 마감 이외에는 데이터가 추출되지 않습니다.", "closingList": [ { "closingDate": "20261015", "terminalID": "1000000001", "terminalCode": "VM-001", "placeCode": "S001", "placeNo": "0001", "cabNo": 0, "colNo": 0, "productCode": "P0001", "productName": "생수 500ml", "productBarcode": "8801234567890", "totCnt": 12, "totAmt": 12000, "cashCnt": 2, "cashAmt": 2000, "cardCnt": 7, "cardAmt": 7000, "tmnCnt": 1, "tmnAmt": 1000, "csbCnt": 0, "csbAmt": 0, "mybCnt": 0, "mybAmt": 0, "krpCnt": 0, "krpAmt": 0, "npcCnt": 1, "npcAmt": 1000, "kkpCnt": 1, "kkpAmt": 1000 } ]}조회 결과가 없는 경우 (HTTP 404)
{ "type": "closing", "message": "No Result", "closingDate": "2026-10-15", "decription": "단말기 마감일 기준으로 판매된 데이터를 추출합니다. 오늘날짜 조회의 경우, 수동 마감 이외에는 데이터가 추출되지 않습니다."}GET | POST /closing/{closingType}/{date}/{time}
마감 여부와 관계없이, 요청일자 전일의 time부터 요청일자의 time 직전까지 24시간 동안 발생한 거래를 집계하여 조회합니다.
가맹점의 정산 기준 시각이 자정이 아닌 경우(예: 매일 18시 기준)에 사용합니다.
요청에서 필요로 하는 필드는 다음과 같습니다.
| 필드명 | 필수 | 타입 | 설명 | 비고 |
|---|---|---|---|---|
| closingType | Y | String | 집계 유형 (Path) | product: 단말기 + 상품별 집계column: 단말기 + 컬럼별 집계 |
| date | Y | String | 기준일자 (Path) | YYYYMMDD 규격오늘 이후의 일자는 요청 불가 |
| time | Y | String | 기준시간 (Path) | HHMISS 규격 (24시간제) |
// get, post 모두 지원합니다.// 예시) /20261015/180000 입력 시// 2026-10-14 18:00:00 부터 2026-10-15 17:59:59 까지 발생한 거래를 상품별로 집계합니다.const res = await API.get("/closing/product/20261015/180000");closingList.closingDate에는 요청한 기준일자(date)가 전달됩니다.000000부터 time 직전까지의 거래만 집계됩니다.totCnt, totAmt는 모든 결제수단의 합계입니다. 결제수단별 항목에 포함되지 않는 결제수단(예: 그 외 간편결제)이 있을 수 있으므로, 결제수단별 합계와 일치하지 않을 수 있습니다.column 집계 시 컬럼번호가 4자리인 머신기는 앞 2자리가 colNo, 뒤 2자리가 cabNo로 전달됩니다.column 집계는 단말기 + 컬럼 + 상품 단위로 집계되므로, 동일 컬럼에서 판매 상품이 변경된 경우 여러 행으로 나뉘어 전달될 수 있습니다.요청이 정상적으로 처리되지 않은 경우 아래와 같은 형식으로 응답됩니다.
code가 포함된 형식으로 응답됩니다. 코드 전체 목록은 응답코드 정리를 참고해 주세요.
| HTTP 상태 | code | description | 발생 조건 |
|---|---|---|---|
| 400 | ERR_101 | token 데이터 누락 | 헤더에 token이 없는 경우 |
| ERR_102 | company 데이터 누락 | 헤더에 company가 없는 경우 | |
| ERR_103 | token 과 company 미일치(인증 실패) | token이 company에 대해 발급된 값이 아닌 경우 | |
| ERR_105 | 유효하지 않은 company | API 사용 권한이 등록되지 않은 company인 경우 |
{ "type": "closing", "code": "ERR_103", "description": "token 과 company 미일치(인증 실패)", "message": "필수 데이터가 누락되었습니다."}code 없이 type, message만 응답됩니다. (HTTP 400)
| message | 발생 조건 |
|---|---|
| closingType이 명확하지 않습니다. | closingType이 product, column이 아닌 경우 |
| 오늘 날짜 이후의 시간은 요청이 불가능합니다. | date가 오늘 이후인 경우 |
{ "type": "closing", "message": "closingType이 명확하지 않습니다."}