docs:바로빌 홈택스 API 연동 문제해결 기록

- TaxType, DateType, 날짜형식 오류 해결 과정 문서화
- 최종 작동 파라미터 및 코드 예시 포함

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

claudedocs/홈택스 매입매출 조회성공.md

@@ -0,0 +1,164 @@
+# 바로빌 홈택스 매입/매출 API 연동 - 문제 해결 기록
+
+> 작성일: 2026-01-28
+> 해결 소요: 약 2일 (2026-01-26 ~ 2026-01-28)
+
+## 개요
+
+바로빌 API를 통해 홈택스 매입/매출 세금계산서를 조회하는 기능 개발 중 발생한 오류와 해결 과정을 기록합니다.
+
+## 사용 API
+
+| API 메소드 | 용도 |
+|-----------|------|
+| `GetPeriodTaxInvoiceSalesList` | 기간별 매출 세금계산서 목록 조회 |
+| `GetPeriodTaxInvoicePurchaseList` | 기간별 매입 세금계산서 목록 조회 |
+
+## 발생한 오류들
+
+### 1. -10008 날짜형식 오류
+
+**오류 메시지:**
+```
+-10008 날짜형식이 잘못되었습니다.
+```
+
+**원인:**
+날짜 파라미터에 하이픈(`-`)이 포함됨
+
+**잘못된 예:**
+```json
+{
+  "StartDate": "2026-01-01",
+  "EndDate": "2026-01-26"
+}
+```
+
+**해결:**
+```json
+{
+  "StartDate": "20260101",
+  "EndDate": "20260126"
+}
+```
+
+**Laravel 코드:**
+```php
+// 하이픈 없는 YYYYMMDD 형식 사용
+$startDate = date('Ymd', strtotime('-1 month'));
+$endDate = date('Ymd');
+```
+
+---
+
+### 2. -11010 과세형태 오류
+
+**오류 메시지:**
+```
+-11010 과세형태가 잘못되었습니다. (TaxType)
+```
+
+**원인:**
+`TaxType=0` (전체)은 바로빌 API에서 **지원하지 않음**
+
+**잘못된 예:**
+```json
+{
+  "TaxType": 0
+}
+```
+
+**바로빌 API TaxType 값:**
+| 값 | 의미 |
+|----|------|
+| 0 | ❌ 미지원 |
+| 1 | 과세 + 영세 |
+| 3 | 면세 |
+
+**해결:**
+전체 조회 시 TaxType=1과 TaxType=3을 **각각 조회하여 합침**
+
+```php
+// 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 | 전송일자 기준 | **권장** |
+
+**적용:**
+```php
+$result = $this->callSoap('GetPeriodTaxInvoiceSalesList', [
+    'UserID' => $userId,
+    'TaxType' => $queryTaxType,
+    'DateType' => 3,  // 전송일자 기준 (권장)
+    'StartDate' => $startDate,
+    'EndDate' => $endDate,
+    'CountPerPage' => $limit,
+    'CurrentPage' => $page
+]);
+```
+
+---
+
+## 최종 작동 파라미터
+
+```json
+{
+  "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. **에러 발생 시 바로빌 고객센터 문의** - 로그를 분석해서 정확한 원인을 알려줌