### Install hometaxbot

Source: https://github.com/finecodekr/hometaxbot/blob/main/README.md

Install the hometaxbot package using pip. Note that pyOpenSSL is pinned to version 23.2.0 due to compatibility issues.

```bash
pip install hometaxbot
```

--------------------------------

### Get Business Registration Status

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Retrieve the VAT tax type (taxable/exempt), registration status text, and history of changes to the simplified tax system for the currently selected business.

```python
from hometaxbot.scraper import HometaxScraper

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

상태 = scraper.사업자등록상태()
print(상태['면세구분'])       # '과세' 또는 '면세'
print(상태['등록상태'])       # 홈택스 원문 텍스트
# 간이→일반 전환 이력이 있는 경우
if '과세유형전환' in 상태:
    print(상태['과세유형전환']['전환일자'])   # date(2022, 7, 1)
    print(상태['과세유형전환']['전환유형'])   # '일반과세자로 전환된'
```

--------------------------------

### Query Tax Agent's Client List

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Retrieves a list of taxpayers represented by a tax accountant in tax agent mode. Includes taxpayer details, representation start date, and consent date. Requires prior login and switching to tax agent mode.

```python
from datetime import date
from hometaxbot.scraper import HometaxScraper
from hometaxbot.scraper import taxagent

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')
scraper.login_as_tax_accountant('123456', 'taxagent_pw')

for 수임 in taxagent.수임납세자(scraper, date(2024, 1, 1), date(2024, 12, 31)):
    print(수임.납세자.납세자번호)         # '987-65-43210'
    print(수임.납세자.납세자명)           # '주식회사 고객사'
    print(수임.납세자.대표자명)           # '김고객'
    print(수임.수임일)                    # '20230101'
    print(수임.동의일)                    # '20230103'
```

--------------------------------

### Handle Hometax Exceptions: Authentication, Throttling, and General Errors

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Demonstrates how to catch specific exceptions like `AuthenticationFailed` and `Throttled`, as well as the general `HometaxException`, to manage errors during login and data scraping. Includes a retry mechanism for throttled requests.

```python
from datetime import date
from hometaxbot import HometaxException, AuthenticationFailed, Throttled
from hometaxbot.scraper import HometaxScraper, reports
import time

scraper = HometaxScraper()

try:
    scraper.login_with_cert(['signCert.der', 'signPri.key'], 'wrong_password')
except AuthenticationFailed as e:
    print(f'인증 실패: {e}')   # '홈택스에 등록된 인증서가 아닙니다'
except HometaxException as e:
    print(f'홈택스 오류: {e}')

try:
    for report in reports.전자신고결과조회(scraper, date(2024, 1, 1), date(2024, 12, 31)):
        print(report.신고서종류)
except Throttled as e:
    wait = e.wait if hasattr(e, 'wait') and isinstance(e.wait, int) else 60
    print(f'{wait}초 후 재시도합니다.')
    time.sleep(wait)
except HometaxException as e:
    print(f'스크래핑 오류: {e}')
```

--------------------------------

### Query Cash Receipt Transactions (Sales/Purchases)

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Retrieves both sales and purchase cash receipt details. Sales are collected via download, while purchases use pagination. Requires prior login with a certificate.

```python
from datetime import date
from hometaxbot.scraper import HometaxScraper, transactions

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

for receipt in transactions.현금영수증(scraper, date(2024, 1, 1), date(2024, 3, 31)):
    print(receipt.매출매입)               # '매출' 또는 '매입'
    print(receipt.거래일시)               # datetime(2024, 1, 20, 11, 0, 0)
    print(receipt.총금액)                 # Decimal('33000')
    print(receipt.공급가액)               # Decimal('30000')
    print(receipt.부가세)                 # Decimal('3000')
    print(receipt.가맹점.납세자명)        # '올리브영 서초점'
    print(receipt.공제여부)               # True
```

--------------------------------

### Perform Simple Authentication with Hometax

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Initiates a simplified authentication process (e.g., Kakao, PASS) and confirms it. After successful authentication, cookies are used to initialize the HometaxScraper.

```python
from datetime import date
import dateutil.parser
from hometaxbot.driver import HometaxDriver
from hometaxbot.scraper import HometaxScraper

driver = HometaxDriver()
driver.begin_simple_authentication(
    provider='카카오톡',           # 인증 앱 이름
    realname='홍길동',
    birthday=dateutil.parser.parse('1990-01-15'),
    phone_number='01012345678',
)

input('스마트폰에서 인증을 완료한 후 엔터를 누르세요...')

driver.confirm_simple_authentication()

# 인증 완료 후 쿠키로 스크래퍼 초기화
scraper = HometaxScraper()
scraper.login_with_cookies(driver.driver.get_cookies())
print(scraper.user_info.홈택스ID)  # 로그인된 홈택스 ID
driver.close()
```

--------------------------------

### HometaxDriver

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Initializes a Selenium-based driver for simplified login using easy authentication methods (e.g., Kakao, PASS) without a digital certificate.

```APIDOC
## HometaxDriver — Selenium 기반 간편인증 로그인

### Description
Initializes a Selenium-based driver for simplified login using easy authentication methods (e.g., Kakao, PASS) without a digital certificate. After authentication, cookies can be passed to `HometaxScraper` for API scraping.

### Initialization
`driver = HometaxDriver()`

### Usage
This class is used to automate the login process via a web browser. The obtained session cookies can then be used to initialize `HometaxScraper` for subsequent data scraping.
```

--------------------------------

### Scrape Hometax Reports with Python

Source: https://github.com/finecodekr/hometaxbot/blob/main/README.md

Use HometaxScraper to log in with a certificate and retrieve electronic filing results. Ensure you have a valid digital certificate and its password.

```python
from hometaxbot.scraper import HometaxScraper, reports
from datetime import date

scraper = HometaxScraper()
scraper.login_with_cert(['signKey.der', 'signPri.key'], '1234')
for report in reports.전자신고결과조회(scraper, date(2024, 1, 1), date(2024, 6, 1)):
    print(report.신고서종류)
    
```

--------------------------------

### Select Trader with Personal Certificate

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Switch between multiple businesses when logged in with a personal digital certificate. Available businesses can be listed and then selected by their business registration number.

```python
from hometaxbot.scraper import HometaxScraper

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

# 보유한 사업자 목록 확인
for trader in scraper.개인사업자_list:
    print(trader['사업자등록번호'])  # 123-45-67890

# 특정 사업자 선택
scraper.select_trader('1234567890')
print(scraper.selected_trader.납세자명)  # 홍길동 개인사업자
print(scraper.selected_trader.개업일)    # 2010-03-15
```

--------------------------------

### Login with Cookies

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Reuse saved cookies for subsequent requests to avoid repeated certificate logins, useful for frequent scraping within a short period.

```python
from hometaxbot.scraper import HometaxScraper

# 최초 인증서 로그인 후 쿠키 저장
scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')
saved_cookies = scraper.cookies()

# 이후 요청에서 쿠키로 재로그인
scraper2 = HometaxScraper()
scraper2.login_with_cookies(saved_cookies)
print(scraper2.user_info.홈택스ID)  # user@example
```

--------------------------------

### Query Tax Notices

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Fetches a list of tax notices with upcoming payment deadlines. Includes tax type, amount due, payment deadline, payment status, notice type, and electronic payment number.

```python
from datetime import date
from hometaxbot.scraper import HometaxScraper, reports

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

for notice in reports.고지내역(scraper, date(2024, 1, 1), date(2024, 12, 31)):
    print(notice.세목)               # '부가가치세'
    print(notice.고지세액)           # Decimal('710540')
    print(notice.납부기한)           # date(2024, 3, 31)
    print(notice.납부여부)           # '납부'
    print(notice.고지서유형)         # '일반고지'
    print(notice.전자납부번호)       # '0126-2403-5-41-22057360'
```

--------------------------------

### Login with Digital Certificate (DER+KEY)

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Log in to Hometax using DER and KEY format digital certificate files and a password. User and business information are automatically set upon successful login.

```python
from hometaxbot.scraper import HometaxScraper

scraper = HometaxScraper()

# DER + KEY 파일 방식 (공동인증서)
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

# PFX 단일 파일 방식
# scraper.login_with_cert(['cert.pfx'], 'cert_password_1234')

print(scraper.user_info.납세자명)       # 홍길동 / 주식회사 예시
print(scraper.user_info.사용자구분)     # 홈택스사용자구분코드.법인사업자
print(scraper.selected_trader.납세자번호)  # 123-45-67890
print(scraper.selected_trader.업태)        # 제조업
print(scraper.selected_trader.간이과세여부)  # False
```

--------------------------------

### Fetch Tax Agent Representation Information (Taxpayer View)

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

As a taxpayer, query information about the tax agents representing you. This includes details of the tax agent and the scope of representation. Requires login with a taxpayer certificate.

```python
from hometaxbot.scraper import HometaxScraper

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

for 수임정보 in scraper.fetch_세무대리수임정보():
    print(수임정보.납세자.납세자번호)          # '123-45-67890'
    print(수임정보.세무대리인.상호)            # '한국세무법인'
    print(수임정보.세무대리인.관리번호)        # '123456'
    print(수임정보.세무대리인.전화번호)        # '02-1234-5678'
    print(수임정보.정보제공범위)               # '전체'
    print(수임정보.수임일)                     # '20220301'
```

--------------------------------

### Query Monthly Credit Card Sales Aggregation

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Retrieves quarterly credit card sales aggregation data, broken down monthly by transaction count, total amount, and card company. Requires prior login with a certificate.

```python
from datetime import date
from hometaxbot.scraper import HometaxScraper, transactions

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

for summary in transactions.카드매출월간집계(scraper, date(2024, 1, 1), date(2024, 3, 31)):
    print(summary.거래연월)           # date(2024, 1, 1)  → 2024년 1월
    print(summary.거래건수)           # 142
    print(summary.합계금액)           # Decimal('7850000')
    print(summary.매입처명)           # 'KB국민카드'
```

--------------------------------

### HometaxScraper.login_with_cert

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Logs into Hometax using digital certificate files (DER/KEY or PFX) and a password. Automatically sets user and trader information upon successful login.

```APIDOC
## HometaxScraper.login_with_cert

### Description
Logs into Hometax using digital certificate files (DER/KEY or PFX) and a password. Automatically sets user and trader information upon successful login.

### Method
```python
scraper.login_with_cert(cert_files: list[str], password: str)
```

### Parameters
#### Path Parameters
- **cert_files** (list[str]) - Required - A list containing the paths to the digital certificate files (e.g., ['signCert.der', 'signPri.key'] or ['cert.pfx']).
- **password** (str) - Required - The password for the digital certificate.

### Request Example
```python
from hometaxbot.scraper import HometaxScraper

scraper = HometaxScraper()

# DER + KEY file method (Digital Certificate)
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

# PFX single file method
# scraper.login_with_cert(['cert.pfx'], 'cert_password_1234')

print(scraper.user_info.납세자명)       # Example: Hong Gildong / Example Corp
print(scraper.user_info.사용자구분)     # Example: Hometax User Type Code.Corporate Business
print(scraper.selected_trader.납세자번호)  # Example: 123-45-67890
print(scraper.selected_trader.업태)        # Example: Manufacturing
print(scraper.selected_trader.간이과세여부)  # Example: False
```
```

--------------------------------

### Register Certificate with Hometax

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Registers a new digital certificate with Hometax. If the certificate is already registered, a corresponding message is returned. Requires login with an existing certificate.

```python
from hometaxbot.scraper import HometaxScraper

scraper = HometaxScraper()
scraper.login_with_cert(['old_signCert.der', 'old_signPri.key'], 'old_password')

# 새 인증서 등록
result = scraper.register_cert(
    registration_no='1234567890',        # 사업자등록번호 (하이픈 없이)
    cert_paths=['new_signCert.der', 'new_signPri.key'],
    prikey_password='new_password'
)
print(result)  # '인증서가 정상적으로 등록되었습니다.' 또는 '이미 등록된 인증서입니다.'
```

--------------------------------

### Query Electronic Filing Results

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Fetch submission details for electronic filings (VAT, income tax, withholding tax, corporate tax) within a specified date range. Returns a generator of `전자신고결과조회` data class instances.

```python
from datetime import date
from hometaxbot.scraper import HometaxScraper, reports

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

for report in reports.전자신고결과조회(scraper, date(2024, 1, 1), date(2024, 12, 31)):
    print(report.신고서종류)    # '부가가치세 확정신고서'
    print(report.세목코드)      # 세목코드.부가세
    print(report.접수일)        # date(2024, 7, 25)
    print(report.과세연월)      # '202401'
    print(report.납부금액)      # Decimal('1500000')
    print(report.공급가액)      # Decimal('15000000')
```

--------------------------------

### Simplified Authentication Login via Selenium

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Logs into Hometax using simplified authentication methods (e.g., Kakao, PASS) without a digital certificate. The obtained cookies can then be used with HometaxScraper for API scraping.

```python
import dateutil.parser
from hometaxbot.scraper.webdriver import HometaxDriver
from hometaxbot.scraper import HometaxScraper

# Selenium Chrome 드라이버 초기화 (기본 headless)
driver = HometaxDriver()
```

--------------------------------

### reports.고지내역

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Queries for a list of notices with payment deadlines, including tax type, billed amount, due date, and payment status.

```APIDOC
## reports.고지내역 — 고지서 조회

### Description
Queries for a list of notices with payment deadlines, including tax type, billed amount, due date, and payment status.

### Method
`reports.고지내역(scraper, start_date, end_date)`

### Parameters
- **scraper**: An authenticated `HometaxScraper` instance.
- **start_date**: The start date for the notice search.
- **end_date**: The end date for the notice search.

### Response Example
```json
[
  {
    "세목": "부가가치세",
    "고지세액": "710540",
    "납부기한": "2024-03-31",
    "납부여부": "납부",
    "고지서유형": "일반고지",
    "전자납부번호": "0126-2403-5-41-22057360"
  }
]
```
```

--------------------------------

### Login as Tax Accountant

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Switches to tax accountant mode after initial certificate login, using the accountant's management number and password. This enables access to tax agent-specific functionalities.

```python
from hometaxbot.scraper import HometaxScraper

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

# 세무대리인 전환 로그인
scraper.login_as_tax_accountant(
    ctn_no='123456',          # 세무대리인 관리번호 (6자리) 
    cta_password='taxagent_pw'
)
print(scraper.cta_admin_no)   # '123456'
```

--------------------------------

### Query Business Card Purchase Transactions

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Retrieves business credit card purchase details such as transaction date, card company, merchant, and deductibility. Requires prior login with a certificate.

```python
from datetime import date
from hometaxbot.scraper import HometaxScraper, transactions

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

for card in transactions.카드매입(scraper, date(2024, 1, 1), date(2024, 6, 30)):
    print(card.거래일시)                  # datetime(2024, 3, 10, 14, 30, 0)
    print(card.카드사)                    # '신한카드'
    print(card.가맹점.납세자명)           # '스타벅스 강남점'
    print(card.공급가액)                  # Decimal('4545')
    print(card.부가세)                    # Decimal('455')
    print(card.총금액)                    # Decimal('5000')
    print(card.공제여부)                  # '공제'
```

--------------------------------

### transactions.현금영수증

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Retrieves cash receipt details for both sales and purchases. Sales are collected via download, and purchases are collected via pagination.

```APIDOC
## transactions.현금영수증 — 현금영수증 조회 (매출·매입)

### Description
Retrieves cash receipt details for both sales and purchases. Sales are collected via download, and purchases are collected via pagination.

### Method
`transactions.현금영수증(scraper: HometaxScraper, start_date: date, end_date: date)`

### Parameters
- `scraper` (HometaxScraper) - An authenticated HometaxScraper instance.
- `start_date` (date) - The start date for the transaction period.
- `end_date` (date) - The end date for the transaction period.

### Response Example
```json
[
  {
    "매출매입": "string",
    "거래일시": "datetime",
    "총금액": "Decimal",
    "공급가액": "Decimal",
    "부가세": "Decimal",
    "가맹점": {
      "납세자명": "string"
    },
    "공제여부": "boolean"
  }
]
```
```

--------------------------------

### Retrieve Electronic Tax Invoices

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Fetches sales and purchase electronic tax invoices (including statements and consignment) for a given period. Parses all fields from the original XML, such as supplier, buyer, item, and amount.

```python
from datetime import date
from hometaxbot.scraper import HometaxScraper, transactions

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

for invoice in transactions.세금계산서(scraper, date(2024, 1, 1), date(2024, 6, 30)):
    print(invoice.승인번호)                  # '20240115-...'
    print(invoice.작성일자)                  # date(2024, 1, 15)
    print(invoice.공급자.납세자명)           # '주식회사 공급사'
    print(invoice.공급받는자.납세자명)       # '주식회사 매입사'
    print(invoice.공급가액)                  # Decimal('10000000')
    print(invoice.세액)                      # Decimal('1000000')
    print(invoice.총금액)                    # Decimal('11000000')
    for 품목 in invoice.품목:
        print(품목.품목명, 품목.수량, 품목.단가)
```

--------------------------------

### transactions.카드매출월간집계

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Returns monthly aggregated credit card sales data, including transaction count, total amount, and card issuer, on a quarterly basis.

```APIDOC
## transactions.카드매출월간집계 — 신용카드 매출 월간 집계 조회

### Description
Returns monthly aggregated credit card sales data, including transaction count, total amount, and card issuer, on a quarterly basis.

### Method
`transactions.카드매출월간집계(scraper: HometaxScraper, start_date: date, end_date: date)`

### Parameters
- `scraper` (HometaxScraper) - An authenticated HometaxScraper instance.
- `start_date` (date) - The start date for the aggregation period.
- `end_date` (date) - The end date for the aggregation period.

### Response Example
```json
[
  {
    "거래연월": "date",
    "거래건수": "integer",
    "합계금액": "Decimal",
    "매입처명": "string"
  }
]
```
```

--------------------------------

### HometaxScraper.login_with_cookies

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Reuses saved cookies for login, avoiding repeated certificate authentication for frequent scraping tasks.

```APIDOC
## HometaxScraper.login_with_cookies

### Description
Reuses saved cookies for login, avoiding repeated certificate authentication for frequent scraping tasks.

### Method
```python
scraper.login_with_cookies(cookies: dict)
```

### Parameters
#### Path Parameters
- **cookies** (dict) - Required - A dictionary containing the saved cookies.

### Request Example
```python
from hometaxbot.scraper import HometaxScraper

# First, log in with certificate and save cookies
scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')
saved_cookies = scraper.cookies()

# Then, log in using the saved cookies for subsequent requests
scraper2 = HometaxScraper()
scraper2.login_with_cookies(saved_cookies)
print(scraper2.user_info.홈택스ID)  # Example: user@example
```
```

--------------------------------

### Query Tax Filing History by Tax Type

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Access tax filing history from the My Hometax 'Filing History' screen, allowing queries for all tax types or specific ones. Supports VAT, corporate tax, and withholding tax.

```python
from datetime import date
from hometaxbot.scraper import HometaxScraper, reports

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

begin, end = date(2024, 1, 1), date(2024, 12, 31)

# 전체 세목 (부가세 + 법인세 + 원천세)
for report in reports.세금신고내역(scraper, begin, end):
    print(report.세목코드, report.납부금액)

# 원천세만
for report in reports.세금신고내역_원천세(scraper, begin, end):
    print(report.신고서종류)    # '원천징수이행상황신고서'
    print(report.납부금액)      # Decimal('330000')

# 부가가치세만
for report in reports.세금신고내역_부가가치세(scraper, begin, end):
    print(report.과세기간시작일)  # date(2024, 1, 1)
```

--------------------------------

### HometaxScraper.login_as_tax_accountant

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Switches to tax agent mode after initial login with a certificate, using the tax agent's management number and password.

```APIDOC
## HometaxScraper.login_as_tax_accountant — 세무대리인 계정으로 전환 로그인

### Description
Switches to tax agent mode after initial login with a certificate, using the tax agent's management number and password.

### Method
`scraper.login_as_tax_accountant(ctn_no: str, cta_password: str)`

### Parameters
- `ctn_no` (str) - The 6-digit tax agent management number.
- `cta_password` (str) - The password for the tax agent account.

### Response
This method does not return a value but modifies the scraper's state to operate in tax agent mode. The `cta_admin_no` attribute will be set.
```

--------------------------------

### HometaxScraper.fetch_세무대리수임정보

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

As a taxpayer, query the tax agents authorized to represent you, including their business name, management number, and contact information.

```APIDOC
## HometaxScraper.fetch_세무대리수임정보 — 납세자 입장에서 수임 세무대리인 조회

### Description
As a taxpayer, query the tax agents authorized to represent you, including their business name, management number, and contact information.

### Method
`scraper.fetch_세무대리수임정보()`

### Parameters
None

### Response Example
```json
[
  {
    "납세자": {
      "납세자번호": "string"
    },
    "세무대리인": {
      "상호": "string",
      "관리번호": "string",
      "전화번호": "string"
    },
    "정보제공범위": "string",
    "수임일": "string"
  }
]
```
```

--------------------------------

### reports.세금신고내역

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Retrieves tax filing history from the My Hometax 'Tax Filing History' section. Supports querying all tax types or specific types like VAT, withholding tax, and corporate tax.

```APIDOC
## reports.세금신고내역

### Description
Retrieves tax filing history from the My Hometax 'Tax Filing History' section. Supports querying all tax types or specific types like VAT, withholding tax, and corporate tax.

### Method
```python
reports.세금신고내역(scraper: HometaxScraper, start_date: date, end_date: date)
reports.세금신고내역_부가가치세(scraper: HometaxScraper, start_date: date, end_date: date)
reports.세금신고내역_원천세(scraper: HometaxScraper, start_date: date, end_date: date)
reports.세금신고내역_법인세(scraper: HometaxScraper, start_date: date, end_date: date)
```

### Parameters
#### Path Parameters
- **scraper** (HometaxScraper) - Required - An authenticated HometaxScraper instance.
- **start_date** (date) - Required - The start date of the period to query.
- **end_date** (date) - Required - The end date of the period to query.

### Response
#### Success Response (200)
- **세목코드** (str) - Tax item code.
- **납부금액** (Decimal) - Amount paid.
- **신고서종류** (str) - Type of the report filed (e.g., '원천징수이행상황신고서').
- **과세기간시작일** (date) - Start date of the taxable period.

### Request Example
```python
from datetime import date
from hometaxbot.scraper import HometaxScraper, reports

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

begin, end = date(2024, 1, 1), date(2024, 12, 31)

# Query all tax types (VAT + Corporate Tax + Withholding Tax)
for report in reports.세금신고내역(scraper, begin, end):
    print(report.세목코드, report.납부금액)

# Query only withholding tax
for report in reports.세금신고내역_원천세(scraper, begin, end):
    print(report.신고서종류)    # '원천징수이행상황신고서'
    print(report.납부금액)      # Decimal('330000')

# Query only VAT
for report in reports.세금신고내역_부가가치세(scraper, begin, end):
    print(report.과세기간시작일)  # date(2024, 1, 1)
```
```

--------------------------------

### Parse Detailed Tax Return Items

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Retrieves and parses detailed items (e.g., employment income, business income) from tax return reports. Requires a logged-in HometaxScraper instance and a report object.

```python
from datetime import date
from hometaxbot.models import 세목코드
from hometaxbot.scraper import HometaxScraper, reports

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

for report in reports.전자신고결과조회(scraper, date(2024, 1, 1), date(2025, 1, 1)):
    if report.세목코드 == 세목코드.원천세:
        items = reports.원천세_세부항목(scraper, report)
        # A01: 근로소득, A25: 사업소득 등
        if 'A01' in items:
            print(items['A01'].항목명)          # '근로소득'
            print(items['A01'].인원)            # 15
            print(items['A01'].총지급액)        # Decimal('62285950')
            print(items['A01'].소득세등)        # Decimal('3754760')
        if 'A25' in items:
            print(items['A25'].소득세등)        # Decimal('50000')
```

--------------------------------

### reports.환급금조회

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Queries Hometax for determined tax refund details, including tax type, amount, tax period, and refund determination date.

```APIDOC
## reports.환급금조회 — 세금 환급금 조회

### Description
Queries Hometax for determined tax refund details, including tax type, amount, tax period, and refund determination date.

### Method
`reports.환급금조회(scraper, start_date, end_date)`

### Parameters
- **scraper**: An authenticated `HometaxScraper` instance.
- **start_date**: The start date for the refund search.
- **end_date**: The end date for the refund search.

### Response Example
```json
[
  {
    "세목": "부가가치세",
    "금액": "500000",
    "환급결정일": "2024-02-10",
    "귀속연월": "2023-12-01",
    "세무서명": "서초세무서"
  }
]
```
```

--------------------------------

### reports.전자신고결과조회

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Retrieves submission details for electronic reports (VAT, income tax, withholding tax, corporate tax) filed within a specified period. Returns a generator of `전자신고결과조회` data class instances.

```APIDOC
## reports.전자신고결과조회

### Description
Retrieves submission details for electronic reports (VAT, income tax, withholding tax, corporate tax) filed within a specified period. Returns a generator of `전자신고결과조회` data class instances.

### Method
```python
reports.전자신고결과조회(scraper: HometaxScraper, start_date: date, end_date: date)
```

### Parameters
#### Path Parameters
- **scraper** (HometaxScraper) - Required - An authenticated HometaxScraper instance.
- **start_date** (date) - Required - The start date of the period to query.
- **end_date** (date) - Required - The end date of the period to query.

### Response
#### Success Response (200)
- **신고서종류** (str) - Type of the report filed (e.g., '부가가치세 확정신고서').
- **세목코드** (str) - Tax item code (e.g., 세목코드.부가세).
- **접수일** (date) - Submission date.
- **과세연월** (str) - Taxable period (e.g., '202401').
- **납부금액** (Decimal) - Amount paid.
- **공급가액** (Decimal) - Supply value.

### Request Example
```python
from datetime import date
from hometaxbot.scraper import HometaxScraper, reports

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

for report in reports.전자신고결과조회(scraper, date(2024, 1, 1), date(2024, 12, 31)):
    print(report.신고서종류)    # '부가가치세 확정신고서'
    print(report.세목코드)      # 세목코드.부가세
    print(report.접수일)        # date(2024, 7, 25)
    print(report.과세연월)      # '202401'
    print(report.납부금액)      # Decimal('1500000')
    print(report.공급가액)      # Decimal('15000000')
```
```

--------------------------------

### Inquire About Tax Refunds

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Fetches details of determined tax refunds, including tax type, amount, attribution period, and refund determination date. Requires a logged-in HometaxScraper instance.

```python
from datetime import date
from hometaxbot.scraper import HometaxScraper, reports

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

for refund in reports.환급금조회(scraper, date(2023, 1, 1), date(2024, 12, 31)):
    print(refund.세목)            # '부가가치세'
    print(refund.금액)            # Decimal('500000')
    print(refund.환급결정일)      # date(2024, 2, 10)
    print(refund.귀속연월)        # date(2023, 12, 1)
    print(refund.세무서명)        # '서초세무서'
```

--------------------------------

### HometaxScraper.사업자등록상태

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Retrieves the business registration status, including VAT type (taxable/exempt), registration status text, and history of changes to simplified taxation status.

```APIDOC
## HometaxScraper.사업자등록상태

### Description
Retrieves the business registration status, including VAT type (taxable/exempt), registration status text, and history of changes to simplified taxation status.

### Method
```python
scraper.사업자등록상태() -> dict
```

### Response
#### Success Response (200)
- **면세구분** (str) - The VAT type ('과세' or '면세').
- **등록상태** (str) - The original registration status text from Hometax.
- **과세유형전환** (dict, optional) - Information about changes in taxation type, if any.
  - **전환일자** (date) - The date of the taxation type change.
  - **전환유형** (str) - The type of change (e.g., '일반과세자로 전환된' - converted to general taxation).

### Request Example
```python
from hometaxbot.scraper import HometaxScraper

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

status = scraper.사업자등록상태()
print(status['면세구분'])       # '과세' or '면세'
print(status['등록상태'])       # Hometax original text
# If there's a history of conversion from simplified to general taxation
if '과세유형전환' in status:
    print(status['과세유형전환']['전환일자'])   # date(2022, 7, 1)
    print(status['과세유형전환']['전환유형'])   # '일반과세자로 전환된'
```
```

--------------------------------

### reports.원천세_세부항목

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Parses detailed items for withholding tax reports, returning information such as number of people, total payment, and income tax for each category (e.g., employment income, business income).

```APIDOC
## reports.원천세_세부항목 — 원천세 신고서 세부 항목 파싱

### Description
Parses detailed items for withholding tax reports, returning information such as number of people, total payment, and income tax for each category (e.g., employment income, business income).

### Method
`reports.원천세_세부항목(scraper, report)`

### Parameters
- **scraper**: An authenticated `HometaxScraper` instance.
- **report**: A report object obtained from `reports.전자신고결과조회`.

### Response Example
```json
{
  "A01": {
    "항목명": "근로소득",
    "인원": 15,
    "총지급액": "62285950",
    "소득세등": "3754760"
  },
  "A25": {
    "소득세등": "50000"
  }
}
```
```

--------------------------------

### HometaxScraper.select_trader

Source: https://context7.com/finecodekr/hometaxbot/llms.txt

Selects a specific business entity when logged in with a personal digital certificate that has access to multiple businesses. Lists available businesses.

```APIDOC
## HometaxScraper.select_trader

### Description
Selects a specific business entity when logged in with a personal digital certificate that has access to multiple businesses. Lists available businesses.

### Method
```python
scraper.select_trader(business_registration_number: str)
```

### Parameters
#### Path Parameters
- **business_registration_number** (str) - Required - The business registration number of the trader to select.

### Request Example
```python
from hometaxbot.scraper import HometaxScraper

scraper = HometaxScraper()
scraper.login_with_cert(['signCert.der', 'signPri.key'], 'cert_password_1234')

# Check the list of available businesses
for trader in scraper.개인사업자_list:
    print(trader['사업자등록번호'])  # Example: 123-45-67890

# Select a specific business
scraper.select_trader('1234567890')
print(scraper.selected_trader.납세자명)  # Example: Hong Gildong Sole Proprietorship
print(scraper.selected_trader.개업일)    # Example: 2010-03-15
```
```