스킵하기
마감내역 요청
마감된 거래와 관련된 API 기능을 제공합니다.

발생한 매출에 대해 마감된 정보를 조회할 수 있습니다.
마감내역은 단말기별 상품별 또는 컬럼별로 집계된 건수·금액을 결제수단별로 제공합니다.
마감의 종류로는 수동마감과 자동마감이 존재합니다.

  • 수동마감
    • 머신기 또는 단말기에서 직접 마감을 진행하는 경우
    • 특정 시간에 마감을 진행하는 경우(예: 17:45:00) - (단말기 펌웨어를 통해 제어)
  • 자동마감
    • 시스템에서 자동으로 마감을 진행하는 경우(23:59:59 고정)
마감내역 조회는 마감일자 기준 조회와 24시간 구간 조회 두 가지 방식을 지원합니다.
  • 모든 요청은 헤더에 company, token이 필요합니다. (API 시작하기 참고)
  • GET, POST 방식을 모두 지원하며, 요청 Body는 사용하지 않습니다.
  • 조회 결과가 없는 경우 HTTP 상태코드 404와 함께 closingList 필드가 제외된 응답이 전달됩니다.

GET | POST /closing/{closingType}/{date}

단말기의 마감일자가 요청일자(date)인 거래를 집계하여 조회합니다.
오늘 날짜로 조회하는 경우, 아직 자동마감(23:59:59)이 진행되지 않았으므로 수동마감된 거래만 집계됩니다.
취소된 거래는 집계에서 제외됩니다.

요청에서 필요로 하는 필드는 다음과 같습니다.

필드명필수타입설명비고
closingTypeYString집계 유형 (Path)product: 단말기 + 상품별 집계
column: 단말기 + 컬럼별 집계
dateYString마감일자 (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-YStringAPI 유형closing 고정
message-YString응답 메시지조회 성공: Get ClosingList at {date}
결과 없음: No Result
closingDate-YString요청일자YYYY-MM-DD 형식
decription-YStringAPI 상세설명필드명 표기(decription)는 실제 응답 키 그대로입니다.
closingList-NArray마감내역 리스트객체 리스트
조회 결과가 없으면 필드 자체가 제외됨
closingDateYString마감일자YYYYMMDD
terminalIDYString단말기 IDUBCn 단말기 ID
필드명 대소문자에 유의 (terminalID)
terminalCodeYString단말기(자판기) 코드가맹점 관리 단말기 코드
placeCodeYString위치코드(점포코드)미등록 시 -
placeNoYString위치순번(POS번호)미등록 시 -
cabNoYint머신기 캐비넷 번호column 집계 시 제공
캐비넷 구분이 없거나 product 집계 시 0
colNoYint머신기 컬럼번호column 집계 시 제공
product 집계 시 0
productCodeNString상품코드-
productNameNString상품명상품 미등록 시 null
productBarcodeYString상품 바코드미등록 시 -
totCntYint전체 매출수량모든 결제수단 합계
totAmtYint전체 매출금액모든 결제수단 합계
cashCntYint현금 매출수량-
cashAmtYint현금 매출금액-
cardCntYint신용카드 매출수량-
cardAmtYint신용카드 매출금액-
tmnCntYint티머니 매출수량선불카드
tmnAmtYint티머니 매출금액선불카드
csbCntYint이즐(캐시비) 매출수량선불카드
csbAmtYint이즐(캐시비) 매출금액선불카드
mybCntYint마이비 매출수량선불카드
mybAmtYint마이비 매출금액선불카드
krpCntYint레일플러스 매출수량선불카드
krpAmtYint레일플러스 매출금액선불카드
npcCntYint페이코 매출수량간편결제
npcAmtYint페이코 매출금액간편결제
kkpCntYint카카오페이 매출수량간편결제
kkpAmtYint카카오페이 매출금액간편결제

아래 값은 이해를 돕기 위한 예시입니다. (상품별 집계, 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시 기준)에 사용합니다.

요청에서 필요로 하는 필드는 다음과 같습니다.

필드명필수타입설명비고
closingTypeYString집계 유형 (Path)product: 단말기 + 상품별 집계
column: 단말기 + 컬럼별 집계
dateYString기준일자 (Path)YYYYMMDD 규격
오늘 이후의 일자는 요청 불가
timeYString기준시간 (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)가 전달됩니다.
  • 매월 1일에 호출하는 경우, 전일 데이터는 포함되지 않고 기준일자 000000부터 time 직전까지의 거래만 집계됩니다.
※ 응답 규격 및 예시는 상단의 [마감일자 기준 조회]와 동일합니다.

  • totCnt, totAmt는 모든 결제수단의 합계입니다. 결제수단별 항목에 포함되지 않는 결제수단(예: 그 외 간편결제)이 있을 수 있으므로, 결제수단별 합계와 일치하지 않을 수 있습니다.
  • column 집계 시 컬럼번호가 4자리인 머신기는 앞 2자리가 colNo, 뒤 2자리가 cabNo로 전달됩니다.
  • column 집계는 단말기 + 컬럼 + 상품 단위로 집계되므로, 동일 컬럼에서 판매 상품이 변경된 경우 여러 행으로 나뉘어 전달될 수 있습니다.
  • 응답 필드의 순서는 보장되지 않습니다. 필드명으로 값을 참조해 주세요.

요청이 정상적으로 처리되지 않은 경우 아래와 같은 형식으로 응답됩니다.

code가 포함된 형식으로 응답됩니다. 코드 전체 목록은 응답코드 정리를 참고해 주세요.

HTTP 상태codedescription발생 조건
400ERR_101token 데이터 누락헤더에 token이 없는 경우
ERR_102company 데이터 누락헤더에 company가 없는 경우
ERR_103token 과 company 미일치(인증 실패)token이 company에 대해 발급된 값이 아닌 경우
ERR_105유효하지 않은 companyAPI 사용 권한이 등록되지 않은 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이 명확하지 않습니다."
}