단말기에서 발생한 매출의 거래내역을 조회할 수 있습니다.
거래내역은 승인·취소 건별로 결제수단, 카드/VAN/매입사 코드, 상품 정보, 매입·입금 예정일 등의 상세 정보를 제공합니다.
일 단위 전체 조회와 시간 구간 조회(최대 60분) 두 가지 방식을 지원합니다.company, token이 필요합니다. (API 시작하기 참고)GET, POST 방식을 모두 지원하며, 요청 Body는 사용하지 않습니다.404와 함께 salesList 필드가 제외된 응답이 전달됩니다.GET | POST /sales/{date}
요청일자(date)에 발생한 거래내역 전체를 조회합니다.
승인 건은 거래일자 기준, 취소 건은 취소일자 기준으로 포함됩니다.
요청에서 필요로 하는 필드는 다음과 같습니다.
| 필드명 | 필수 | 타입 | 설명 | 비고 |
|---|---|---|---|---|
| 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("/sales/20261015");
if (res.status === 200) { console.log(res.data.salesList);} else if (res.status === 404) { console.log("조회된 거래내역이 없습니다.");} else { // 요청 오류: code(존재하는 경우), message 를 확인합니다. console.error(res.data.code, res.data.message);}결과 값에 들어 있는 필드는 다음과 같습니다.
| 필드명 | 상세필드명 | 필수 | 타입 | 설명 | 비고 |
|---|---|---|---|---|---|
| type | - | Y | String | API 유형 | sales 고정 |
| message | - | Y | String | 응답 메시지 | 조회 성공: Get SalesList at {date}결과 없음: No Result |
| salesDate | - | Y | String | 요청일자 | YYYYMMDD |
| decription | - | Y | String | API 상세설명 | 필드명 표기(decription)는 실제 응답 키 그대로입니다. |
| salesList | - | N | Array | 거래내역 리스트 | 객체 리스트 조회 결과가 없으면 필드 자체가 제외됨 |
| transactionDate | Y | String | 매출일자 | YYYYMMDD 취소 건은 취소일자 | |
| transactionNo | Y | String | 거래고유번호 | UBCn 거래번호 | |
| terminalId | Y | String | 단말기 ID | UBCn 단말기 ID | |
| terminalCode | Y | String | 단말기(자판기) 코드 | 가맹점 관리 단말기 코드 | |
| placeCode | Y | String | 위치코드(점포코드) | 미등록 시 - | |
| placeNo | Y | String | 위치순번(POS번호) | 미등록 시 - | |
| terminalTransSeq | N | String | 단말기 거래 일련번호 | - | |
| tranDate | Y | String | 거래일자 | YYYYMMDD 취소 건은 취소일자 | |
| tranTime | Y | String | 거래시간 | HH24MISS 취소 건은 취소시간 | |
| payStep | Y | String | 거래 종류 | 1: 승인, 2: 취소 | |
| payType | Y | String | 지불 종류 | 1: 현금, 2: 신용카드, 3: 선불카드(교통카드), 4: 간편결제 | |
| cardCode | Y | String | 카드사(발급사) 코드 | 현금 결제 시 -선불카드는 카드 종류 코드 | |
| purchaseCode | Y | String | 매입사 코드 | 현금 결제 시 -선불카드는 카드 종류 코드 | |
| vanCode | Y | String | VAN사 코드 | 현금·선불카드 결제 시 - | |
| cardNo | N | String | 카드번호 | 마스킹된 카드번호 | |
| approvalNo | Y | String | 승인번호 | 승인번호가 없는 경우 - | |
| approvalDate | Y | String | 승인일자 | YYYYMMDD 취소 건은 취소일자 | |
| approvalTime | Y | String | 승인시간 | HH24MISS 취소 건은 취소시간 | |
| orgTransactionDate | N | String | 원거래일자 | 취소 시 원거래 일자 | |
| orgTerminalTransSeq | N | String | 원거래 단말기 거래 일련번호 | 취소 시 원거래 단말기 거래번호 | |
| orgApprovalNo | Y | String | 원거래 승인번호 | 취소 시 원거래 승인번호 없는 경우 - | |
| colNo | Y | String | 머신기 컬럼번호 | - | |
| productCode | Y | String | 상품코드 | 미등록 시 - | |
| productName | Y | String | 상품명 | 미등록 시 - | |
| productBarcode | Y | String | 상품바코드 | 미등록 시 - | |
| count | Y | String | 판매수량 | 항상 1여러 상품을 한 번에 결제한 경우 상품별로 행이 분리되어 전달됨 | |
| price | Y | String | 판매단가 | - | |
| salePrice | Y | String | 판매금액 | 판매수량 * 판매단가 | |
| discount | Y | String | 할인금액 | 현재 미지원 (항상 0) | |
| point | Y | String | 사용포인트 | 현재 미지원 (항상 0) | |
| amount | Y | String | 결제금액 | 판매금액 - 할인금액 - 포인트 | |
| beforeBalance | Y | String | 사용 전 잔액 | 현재 미지원 (항상 0) | |
| afterBalance | Y | String | 사용 후 잔액 | 현재 미지원 (항상 0) | |
| purchaseExpDate | Y | String | 매입 예정일 | YYYYMMDD 신용·간편·선불 결제만 제공, 그 외 및 취소 건은 - | |
| payExpDate | Y | String | 입금 예정일 | YYYYMMDD 현금은 거래일자, 취소 건은 -예정일이며 확정된 입금일이 아님 (아래 '입금 예정일 (주의)' 참고) |
아래 값은 이해를 돕기 위한 예시입니다. (HTTP 200)
{ "type": "sales", "message": "Get SalesList at 20261015", "salesDate": "20261015", "decription": "요청 일시 기준으로 매출을 추출합니다.", "salesList": [ { "transactionDate": "20261015", "transactionNo": "1234567890", "terminalId": "1000000001", "terminalCode": "VM-001", "placeCode": "S001", "placeNo": "0001", "terminalTransSeq": "0123", "tranDate": "20261015", "tranTime": "093015", "payStep": "1", "payType": "2", "cardCode": "01", "vanCode": "01", "purchaseCode": "01", "cardNo": "536181******1234", "approvalNo": "12345678", "approvalDate": "20261015", "approvalTime": "093015", "orgTransactionDate": "20261015", "orgTerminalTransSeq": "0123", "orgApprovalNo": "12345678", "colNo": "11", "productCode": "P0001", "productName": "생수 500ml", "productBarcode": "8801234567890", "count": "1", "price": "1000", "salePrice": "1000", "discount": "0", "point": "0", "amount": "1000", "beforeBalance": "0", "afterBalance": "0", "purchaseExpDate": "20261016", "payExpDate": "20261021" } ]}조회 결과가 없는 경우 (HTTP 404)
{ "type": "sales", "message": "No Result", "salesDate": "20261015", "decription": "요청 일시 기준으로 매출을 추출합니다."}GET | POST /sales/{date}/{time}/{minute}
요청일자(date)의 기준시간(time)으로부터 minute분 이전까지 발생한 거래내역을 조회합니다.
조회 구간은 (time - minute, time] 입니다. (시작 시각 미포함, 기준시간 포함)
실시간 연동을 위해 주기적으로 호출하는 경우, 이전 호출의 time을 다음 호출의 시작점으로 맞추면 누락 없이 조회할 수 있습니다.
요청에서 필요로 하는 필드는 다음과 같습니다.
| 필드명 | 필수 | 타입 | 설명 | 비고 |
|---|---|---|---|---|
| date | Y | String | 조회일자 (Path) | YYYYMMDD 규격오늘 이후의 일자는 요청 불가 |
| time | Y | String | 기준시간 (Path) | HHMISS 규격 (24시간제)240000 입력 시 235959로 처리 |
| minute | Y | String | 조회 구간(분) (Path) | 기준시간으로부터 몇 분 전까지 조회할지 지정 최대 60 |
minute은 최대 60분까지 지정할 수 있습니다.time - minute이 000000보다 작으면 요청 불가)time은 현재 시각 기준 5분 이전이어야 합니다. 단말기 거래 데이터의 수신 지연을 고려한 제약입니다.// get, post 모두 지원합니다.// 예시) 2026년 10월 15일 14:00:00 기준, 30분 전(13:30:00 초과 ~ 14:00:00 이하)의 거래내역 조회const res = await API.get("/sales/20261015/140000/30");
// 예시) 2026년 10월 15일 23:00:00 ~ 23:59:59 의 거래내역 조회const res2 = await API.get("/sales/20261015/240000/60");payStep: 1)와 별개로 취소 건(payStep: 2)이 취소일자 기준으로 추가 전달됩니다.
취소 건의 orgTransactionDate, orgTerminalTransSeq, orgApprovalNo로 원거래를 확인할 수 있습니다.transactionNo로 상품별 행이 나뉘어 전달되며 각 행의 amount는 해당 상품 금액입니다.payExpDate는 영업일 기준으로 산정한 순수한 예정일이며, 입금일이 확정된 값이 아닙니다. 실제 입금일은 VAN사를 통해 입금 데이터가 전달되는 시점에 확정되므로 예정일과 다를 수 있습니다. 입금 여부·확정된 입금일은 정산내역 요청으로 확인해 주세요.purchaseExpDate도 영업일 기준으로 산정한 예정일이며, 실제 매입일과 다를 수 있습니다.요청이 정상적으로 처리되지 않은 경우 아래와 같은 형식으로 응답됩니다.
code가 포함된 형식으로 응답됩니다. 코드 전체 목록은 응답코드 정리를 참고해 주세요.
| HTTP 상태 | code | description | 발생 조건 |
|---|---|---|---|
| 400 | ERR_101 | token 데이터 누락 | 헤더에 token이 없는 경우 |
| ERR_102 | company 데이터 누락 | 헤더에 company가 없는 경우 | |
| ERR_103 | token 과 company 미일치(인증 실패) | token이 company에 대해 발급된 값이 아닌 경우 | |
| ERR_105 | 유효하지 않은 company | API 사용 권한이 등록되지 않은 company인 경우 | |
| 5113 | 데이터 처리 실패 | 인증 처리 중 오류가 발생한 경우 (재시도 요망) |
{ "type": "sales", "code": "ERR_103", "description": "token 과 company 미일치(인증 실패)", "message": "필수 데이터가 누락되었습니다."}code 없이 type, message만 응답됩니다. (HTTP 400)
| message | 발생 조건 |
|---|---|
| 오늘 날짜 이후의 일자는 요청이 불가능합니다. | date가 오늘 이후인 경우 |
| 요청값에는 null을 포함할 수 없습니다. | time 또는 minute이 비어 있는 경우 |
| 요청기준시간이 요청기간보다 작습니다. | time - minute이 000000보다 작은 경우 |
| 현재시간의 5분 이전 거래만 조회 가능합니다. | 당일 조회 시 time이 현재 시각 5분 전보다 늦은 경우 |
| 기준시간의 60분 이전까지만 조회 가능합니다. | minute이 60을 초과한 경우 |
{ "type": "sales", "message": "현재시간의 5분 이전 거래만 조회 가능합니다."}