sam-docs/guides/홈택스 매입매출 조회성공.md

바로빌 홈택스 매입/매출 API 연동 - 문제 해결 기록

작성일: 2026-01-28 해결 소요: 약 2일 (2026-01-26 ~ 2026-01-28)

개요

바로빌 API를 통해 홈택스 매입/매출 세금계산서를 조회하는 기능 개발 중 발생한 오류와 해결 과정을 기록합니다.

사용 API

API 메소드	용도
GetPeriodTaxInvoiceSalesList	기간별 매출 세금계산서 목록 조회
GetPeriodTaxInvoicePurchaseList	기간별 매입 세금계산서 목록 조회

발생한 오류들

1. -10008 날짜형식 오류

오류 메시지:

-10008 날짜형식이 잘못되었습니다.

원인: 날짜 파라미터에 하이픈(-)이 포함됨

잘못된 예:

{
  "StartDate": "2026-01-01",
  "EndDate": "2026-01-26"
}

해결:

{
  "StartDate": "20260101",
  "EndDate": "20260126"
}

Laravel 코드:

// 하이픈 없는 YYYYMMDD 형식 사용
$startDate = date('Ymd', strtotime('-1 month'));
$endDate = date('Ymd');

---

2. -11010 과세형태 오류

오류 메시지:

-11010 과세형태가 잘못되었습니다. (TaxType)

원인: TaxType=0 (전체)은 바로빌 API에서 지원하지 않음

잘못된 예:

{
  "TaxType": 0
}

바로빌 API TaxType 값:

값	의미
0	❌ 미지원
1	과세 + 영세
3	면세

해결: 전체 조회 시 TaxType=1과 TaxType=3을 각각 조회하여 합침

// TaxType이 0(전체)인 경우 1(과세+영세)과 3(면세)를 각각 조회하여 합침
$taxTypesToQuery = ($taxType === 0) ? [1, 3] : [$taxType];
$allInvoices = [];

foreach ($taxTypesToQuery as $queryTaxType) {
    $result = $this->callSoap('GetPeriodTaxInvoiceSalesList', [
        'UserID' => $userId,
        'TaxType' => $queryTaxType,
        // ...
    ]);

    if ($result['success']) {
        $parsed = $this->parseInvoices($result['data'], 'sales');
        $allInvoices = array_merge($allInvoices, $parsed['invoices']);
    }
}

// 작성일 기준 최신순 정렬
usort($allInvoices, fn($a, $b) => strcmp($b['writeDate'] ?? '', $a['writeDate'] ?? ''));

---

3. DateType 권장사항

바로빌 권장: DateType=3 (전송일자) 사용 권장

DateType 값:

값	의미	비고
1	작성일 기준	-
3	전송일자 기준	권장

적용:

$result = $this->callSoap('GetPeriodTaxInvoiceSalesList', [
    'UserID' => $userId,
    'TaxType' => $queryTaxType,
    'DateType' => 3,  // 전송일자 기준 (권장)
    'StartDate' => $startDate,
    'EndDate' => $endDate,
    'CountPerPage' => $limit,
    'CurrentPage' => $page
]);

---

최종 작동 파라미터

{
  "CERTKEY": "인증키",
  "CorpNum": "사업자번호",
  "UserID": "바로빌ID",
  "TaxType": 1,
  "DateType": 3,
  "StartDate": "20251231",
  "EndDate": "20260130",
  "CountPerPage": 100,
  "CurrentPage": 1
}

관련 파일

• app/Http/Controllers/Barobill/HometaxController.php
  • sales() - 매출 조회
  • purchases() - 매입 조회
  • diagnose() - 서비스 진단

참고 자료

• 바로빌 개발자 문서: https://dev.barobill.co.kr/docs/taxinvoice
• 바로빌 운영센터 메일 (2026-01-27, 2026-01-28)

교훈

1. API 문서를 꼼꼼히 확인 - TaxType=0이 전체를 의미할 것 같지만 실제로는 미지원
2. 날짜 형식 주의 - 한국 API는 하이픈 없는 YYYYMMDD 형식을 많이 사용
3. 권장사항 따르기 - DateType=3 (전송일자) 사용 권장
4. 에러 발생 시 바로빌 고객센터 문의 - 로그를 분석해서 정확한 원인을 알려줌