# 바로빌 홈택스 매입/매출 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. **에러 발생 시 바로빌 고객센터 문의** - 로그를 분석해서 정확한 원인을 알려줌
