# 전자세금계산서 수집

국세청 홈택스에 신고된 전자세금계산서 매입/매출 수집에 대하여 안내합니다.

## 수집 안내

팝빌에 등록된 인증정보로 국세청 홈택스에 신고된 매입/매출 전자세금계산서를 수집합니다. [\[인증관리\]](https://developers.popbill.com/guide/httaxinvoice/introduction/manage-cert)\
다음 2가지 방식 중 파트너가 원하는 수집 프로세스로 구현하여 이용이 가능합니다.

- **Webhook(Push)**\
  팝빌에서 수집하여 고객사가 등록한 콜백 URL에 1시간(정시) 간격으로 자동 전달 [\[Webhook\]](https://developers.popbill.com/api-reference/httaxinvoice/webhook/introduction)
- **API(Polling)**\
  프로그램 공급사가 직접 API를 호출하여 수집

> Webhook(Push) 방식의 홈택스 수집은 파트너센터로 접수하여 홈택스 수집정보를 설정해야만 이용 가능합니다. [\[연동문의\]](https://developers.popbill.com/customer-center/inquiry)

## 수집 프로세스

홈택스 수집으로 ‘Webhook(Push)’ 또는 ‘API(Polling)’ 방식을 제공하며 고객사에게 적합한 방식을 선택하여 구현합니다.\
단, ‘Webhook(Push)’ 방식을 이용하는 경우, ‘부서사용자’ 등록이 필수사항 입니다. [\[부서사용자 인증\]](https://developers.popbill.com/guide/httaxinvoice/introduction/manage-cert#hometax-auth)

**Webhook(Push)**

팝빌에서 1시간(정시) 간격으로 파트너가 지정한 CallbackURL로 매입/매출 상세정보를 자동 전달합니다.

```mermaid
sequenceDiagram
    participant 파트너
    participant Webhook Receiver
    participant POPBiLL

    파트너->>POPBiLL: Callback URL 등록
    loop 매일 정시마다 반복
      POPBiLL-->>Webhook Receiver: 매입/매출 상세정보 반환          
      Webhook Receiver->>Webhook Receiver: 내역 결과 저장
    end
```

**API(Polling)**

파트너는 “수집 요청 → 수집 상태 확인 → 수집 내역 확인” 단계로 구현하여 내역을 조회합니다.

```mermaid
sequenceDiagram
    participant 파트너
    participant POPBiLL

    파트너->>POPBiLL: RequestJob - 수집 요청
    POPBiLL->>파트너: jobID(작업아이디) 반환
    loop jobState != 3(완료)
      파트너->>POPBiLL: GetJobState - 수집 상태 확인
      POPBiLL->>파트너: jobState(수집상태) 반환
    end
    POPBiLL->>POPBiLL: 수집 완료
    Note right of 파트너: jobState == 3(완료) and ErrorCode == 1(성공)
    파트너->>POPBiLL: Search - 수집 내역 확인
    POPBiLL->>파트너: 수집내역 목록 및 요약정보 반환
```

1. **수집 요청** [\[RequestJob - 수집 요청\]](https://developers.popbill.com/reference/httaxinvoice/java/api/job#RequestJob)\
   \- 팝빌에 홈택스 매입/매출 내역 수집을 요청합니다. 단, 인증정보가 등록된 상태에서만 정상 응답이 반환됩니다.\
   \- 요청이 접수되면 팝빌은 파트너에게 요청에 대한 jobID(작업아이디)를 반환합니다. (단, jobID는 수집 요청 시점부터 1시간 동안만 유효)
2. **수집 상태 확인** [\[GetJobState - 수집 상태 확인\]](https://developers.popbill.com/reference/httaxinvoice/java/api/job#GetJobState)\
   \- 팝빌에서 반환한 리턴값 ‘jobID(작업아이디)’로 수집상태(접수/대기/진행/완료)와 수집결과(성공/실패)를 확인합니다.\
   \- 수집상태(jobState)가 ‘3(완료)‘이고, 수집 결과코드가 ‘1(성공)‘인 상태에서만 수집결과 확인이 가능합니다.
3. **수집 내역 확인** [\[Search - 수집 내역 확인\]](https://developers.popbill.com/reference/httaxinvoice/java/api/search#Search)\
   \- 팝빌로 수집이 완료된 매입/매출 세금계산서 요약정보(Search) 또는 수집내역 합계(Summary)를 확인합니다.

> 고객사가 매번 홈택스 수집을 직접 요청해야 하는 번거로움을 줄이기 위해, 팝빌이 수집 결과를 자동으로 전달하는 Webhook(Push) 방식을 권장합니다.