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

단말기에서 발생한 매출의 거래내역을 조회할 수 있습니다.
거래내역은 승인·취소 건별로 결제수단, 카드/VAN/매입사 코드, 상품 정보, 매입·입금 예정일 등의 상세 정보를 제공합니다.

거래내역 조회는 일 단위 전체 조회와 시간 구간 조회(최대 60분) 두 가지 방식을 지원합니다.
  • 모든 요청은 헤더에 company, token이 필요합니다. (API 시작하기 참고)
  • GET, POST 방식을 모두 지원하며, 요청 Body는 사용하지 않습니다.
  • 조회 결과가 없는 경우 HTTP 상태코드 404와 함께 salesList 필드가 제외된 응답이 전달됩니다.

GET | POST /sales/{date}

요청일자(date)에 발생한 거래내역 전체를 조회합니다.
승인 건은 거래일자 기준, 취소 건은 취소일자 기준으로 포함됩니다.

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

필드명필수타입설명비고
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("/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-YStringAPI 유형sales 고정
message-YString응답 메시지조회 성공: Get SalesList at {date}
결과 없음: No Result
salesDate-YString요청일자YYYYMMDD
decription-YStringAPI 상세설명필드명 표기(decription)는 실제 응답 키 그대로입니다.
salesList-NArray거래내역 리스트객체 리스트
조회 결과가 없으면 필드 자체가 제외됨
transactionDateYString매출일자YYYYMMDD
취소 건은 취소일자
transactionNoYString거래고유번호UBCn 거래번호
terminalIdYString단말기 IDUBCn 단말기 ID
terminalCodeYString단말기(자판기) 코드가맹점 관리 단말기 코드
placeCodeYString위치코드(점포코드)미등록 시 -
placeNoYString위치순번(POS번호)미등록 시 -
terminalTransSeqNString단말기 거래 일련번호-
tranDateYString거래일자YYYYMMDD
취소 건은 취소일자
tranTimeYString거래시간HH24MISS
취소 건은 취소시간
payStepYString거래 종류1: 승인, 2: 취소
payTypeYString지불 종류1: 현금, 2: 신용카드, 3: 선불카드(교통카드), 4: 간편결제
cardCodeYString카드사(발급사) 코드현금 결제 시 -
선불카드는 카드 종류 코드
purchaseCodeYString매입사 코드현금 결제 시 -
선불카드는 카드 종류 코드
vanCodeYStringVAN사 코드현금·선불카드 결제 시 -
cardNoNString카드번호마스킹된 카드번호
approvalNoYString승인번호승인번호가 없는 경우 -
approvalDateYString승인일자YYYYMMDD
취소 건은 취소일자
approvalTimeYString승인시간HH24MISS
취소 건은 취소시간
orgTransactionDateNString원거래일자취소 시 원거래 일자
orgTerminalTransSeqNString원거래 단말기 거래 일련번호취소 시 원거래 단말기 거래번호
orgApprovalNoYString원거래 승인번호취소 시 원거래 승인번호
없는 경우 -
colNoYString머신기 컬럼번호-
productCodeYString상품코드미등록 시 -
productNameYString상품명미등록 시 -
productBarcodeYString상품바코드미등록 시 -
countYString판매수량항상 1
여러 상품을 한 번에 결제한 경우 상품별로 행이 분리되어 전달됨
priceYString판매단가-
salePriceYString판매금액판매수량 * 판매단가
discountYString할인금액현재 미지원 (항상 0)
pointYString사용포인트현재 미지원 (항상 0)
amountYString결제금액판매금액 - 할인금액 - 포인트
beforeBalanceYString사용 전 잔액현재 미지원 (항상 0)
afterBalanceYString사용 후 잔액현재 미지원 (항상 0)
purchaseExpDateYString매입 예정일YYYYMMDD
신용·간편·선불 결제만 제공, 그 외 및 취소 건은 -
payExpDateYString입금 예정일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을 다음 호출의 시작점으로 맞추면 누락 없이 조회할 수 있습니다.

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

필드명필수타입설명비고
dateYString조회일자 (Path)YYYYMMDD 규격
오늘 이후의 일자는 요청 불가
timeYString기준시간 (Path)HHMISS 규격 (24시간제)
240000 입력 시 235959로 처리
minuteYString조회 구간(분) (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 상태codedescription발생 조건
400ERR_101token 데이터 누락헤더에 token이 없는 경우
ERR_102company 데이터 누락헤더에 company가 없는 경우
ERR_103token 과 company 미일치(인증 실패)token이 company에 대해 발급된 값이 아닌 경우
ERR_105유효하지 않은 companyAPI 사용 권한이 등록되지 않은 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분 이전 거래만 조회 가능합니다."
}