Workhub 도움말

테마

팝빌 연동 — 세금계산서 발행 + 입금내역 자동 수집 ​

워크허브 재무관리는 팝빌(Popbill) 의 두 가지 API 를 사용해 매출 자동화를 구현합니다:

모듈역할사용 시점
팝빌 전자세금계산서매출 확정 시 세금계산서 자동 발행 + 발행 결과 자동 갱신입금 확정 → 자동 발행 / 화면에서 수동 발행
팝빌 계좌조회 (EasyFin)등록한 사업자 계좌의 입금내역을 매일 자동 수집 → 매출 자동 매칭백그라운드 (시스템 cron)

기관관리자 자가 등록: 본 화면에서 입력만 하면 즉시 활성 — 시스템관리자(워크허브 운영자) 개입 없이 본인이 등록·해제·테스트할 수 있습니다.

1. 사전 준비 — 팝빌 가입 + 파트너 키 발급 ​

1) 팝빌 회원 가입 ​

https://www.popbill.com → 회원가입 → "사업자 회원" 으로 가입 (개인 회원 불가)

가입 시 필요:

  • 사업자등록증
  • 공동인증서 (전자세금계산서 발급용)

2) 파트너(연동회원) 신청 ​

팝빌은 일반 회원과 별도로 "파트너 회원" (= 연동회원) 등록이 필요합니다. 워크허브 같은 외부 시스템이 API 로 호출하려면 파트너 자격이어야 LinkID/SecretKey 를 받을 수 있습니다.

  1. 팝빌 로그인 → 상단 "연동회원 신청" 메뉴
  2. 신청서 작성 + 사업자 자료 첨부
  3. 보통 1~2 영업일 내 승인 메일

3) LinkID / SecretKey 발급 ​

승인 후:

  1. 팝빌 로그인 → 마이페이지 → 연동정보 관리
  2. 화면에 표시되는 다음 값을 메모:
    • LinkID — 워크허브에 입력할 파트너 ID (예: MyCompany)
    • SecretKey — 비밀키 (예: aB3xY9zQwer...) — 외부 노출 금지
    • 사업자등록번호 — 팝빌 가입 시 등록한 본인 사업자번호

4) (세금계산서만) 공동인증서 등록 ​

전자세금계산서 발급은 법적으로 공동인증서 필수:

  1. 팝빌 로그인 → 마이페이지 → 인증서 관리
  2. 본인 사업자 명의 공동인증서 업로드 + 비밀번호 등록
  3. 유효기간 만료 전 갱신 필수 (메일 알림 옴)

워크허브는 인증서를 직접 다루지 않습니다 — 팝빌 측에 등록된 인증서를 팝빌이 자동 사용.

2. 워크허브에 팝빌 연결하기 ​

1) 화면 이동 ​

좌측 사이드바 재무관리 → 외부 연동 클릭, 또는 /app/finance/integrations 직접 접속.

메뉴가 안 보이면: 기관관리자에게 재무관리 모듈 활성화 요청.

2) "팝빌 — 전자세금계산서" 카드의 [연결하기] 클릭 ​

┌─────────────────────────────────────────────────────────────┐
│ 팝빌 — 전자세금계산서                          [연결하기]   │
│ 세금계산서 자동 발행. 공동인증서를 팝빌에 사전 등록 필요.      │
└─────────────────────────────────────────────────────────────┘

3) 자격증명 입력 모달 ​

필드입력 값비고
LinkID팝빌 마이페이지의 LinkID필수
SecretKey팝빌 마이페이지의 SecretKey필수 (저장 시 AES-GCM 암호화)
사업자등록번호본인 사업자번호 (1234567890 형식, 하이픈 가능)필수
팝빌 회원 ID일반 회원 ID (있으면)선택
인증서 식별자M2 단계 — 비워두면 됨선택

[저장] 클릭 → 백엔드에서 AES-GCM 암호화 후 org_external_connections 테이블에 저장.

4) 연결 테스트 — [테스트] 버튼 ​

저장된 카드 우측의 [연결 테스트] 클릭 → 팝빌 API 호출:

  • ✅ 성공: "연결 정상 — 잔여포인트 12,345원" 같은 메시지
  • ❌ 실패: 메시지에 원인 표시 (자격증명 불일치 / 사업자번호 오타 / 인증서 미등록 등)

5) "팝빌 — 계좌조회 (EasyFin)" 도 동일하게 등록 ​

같은 LinkID/SecretKey/사업자번호 사용 (팝빌 계정 1개 = 두 모듈 공유).

추가 입력:

  • 환경: prod (운영) 또는 test (팝빌 테스트 모드). 기본 prod.

3. 동작 확인 ​

전자세금계산서 ​

자동 발행 — 입금 확정 시 ​

  1. 재무관리 → 매출 대장에서 청구 건 생성
  2. 팝빌 계좌조회로 입금이 자동 매칭되거나 사용자가 수동 매칭
  3. "입금 확정" 처리 시 → 백엔드가 자동으로 팝빌 정발행 호출
  4. 발행 결과는 1~3분 내 팝빌 → 워크허브 웹훅으로 자동 갱신
  5. 매출 행 옆 "세금계산서: 발행완료" 배지 표시 + PDF 링크

수동 발행 — 화면에서 ​

매출 대장의 청구 건 우측 [세금계산서 발행] 버튼 → 수신자 정보 확인 → [확인]

발행 결과 자동 갱신 ​

팝빌이 발행 처리(승인/실패) 가 완료되면 워크허브에 콜백 → 화면 즉시 갱신.

이게 동작하려면 워크허브 측 운영자가 시스템 환경에 POPBILL_WEBHOOK_SECRET + 팝빌 콘솔에 콜백 URL 을 등록해야 합니다 (운영자 1회 작업, 기관관리자 무관).

계좌조회 (입금내역) ​

사업자 계좌 등록 (팝빌 측) ​

  1. 팝빌 로그인 → 계좌조회 메뉴 → 계좌 추가
  2. 본인 사업자 명의 은행/계좌 추가
  3. ARS 또는 OTP 로 본인 인증

워크허브에서 폴링 ​

  • 매일 새벽 워크허브 cron 이 팝빌 EasyFin API 호출 → 신규 입금 내역 가져옴
  • 입금자명 + 금액으로 매출 청구 건에 자동 매칭
  • 매칭 후보가 여러 건이면 → 입금 매칭 보류함에 쌓임 → 사용자가 수동 선택

4. FAQ ​

Q. 워크허브에 등록한 LinkID/SecretKey 가 외부로 유출되지 않나요? ​

  • 저장 시 AES-GCM 암호화 — 마스터 키는 DB 밖에 보관 (워크허브 운영자도 평문 조회 불가)
  • 화면 응답에는 SecretKey 평문이 절대 포함되지 않음 (서버에서 마스킹)
  • 본인 외 다른 기관은 본인 자격증명에 접근 불가

Q. 사업자번호를 잘못 입력했어요. 수정 가능? ​

  • 외부 연동 화면 → 카드의 [수정] 버튼 → 새 값 입력 → [저장]
  • 사업자번호 변경은 자동 발행에 영향 — 매출 대장에 등록된 공급자 사업자번호와 일치해야 합니다.

Q. 연결 테스트가 "credentials invalid" 로 실패합니다. ​

체크 순서:

  1. LinkID 가 본인 회원 ID 가 아닌 파트너 LinkID 인지 (혼동 빈도 1위)
  2. SecretKey 복사 시 공백/줄바꿈 포함 여부
  3. 사업자번호 오타
  4. 팝빌 콘솔에서 LinkID 가 "사용" 상태인지

Q. 세금계산서 발행이 "인증서 미등록" 으로 실패합니다. ​

  • 팝빌 → 마이페이지 → 인증서 관리 에서 본인 사업자 명의 공동인증서를 업로드해야 합니다.
  • 인증서 만료 시 워크허브 측은 알지 못함 → 갱신 후 워크허브에서 재발행 시도하면 정상.

Q. 잔여 포인트가 부족하면 어떻게 되나요? ​

  • 팝빌은 발행/조회 건당 포인트 차감 (전자세금계산서 1건당 약 80원)
  • 잔여 부족 시 발행 API 가 "잔여포인트 부족" 으로 실패 → 매출 행에 실패 사유 기록
  • 팝빌 측에서 포인트 충전 후 워크허브에서 재시도 가능

Q. 발행한 세금계산서를 취소·수정하려면? ​

  • 취소: 팝빌 콘솔에서 직접 취소 — 워크허브는 콜백을 받아 상태 반영
  • 수정(수정세금계산서): 매출 대장의 발행 행에서 [수정 발행] 버튼 → 사유 선택 → 자동 발급

Q. "운영 환경에서 외부 연동 비활성" 메시지가 떠요. ​

이건 워크허브 운영자(시스템관리자) 가 EXTERNAL_CONN_ENC_KEY 환경 키를 세팅하지 않은 상태입니다. 운영자에게 문의하세요. 자격증명 형식은 정상이지만 저장이 안 됩니다.

Q. 팝빌 외 다른 전자세금계산서 서비스(이지오피스 등) 도 지원하나요? ​

지금은 팝빌만 지원. 다른 서비스는 향후 검토 — 별도 어댑터 구현 필요.

5. 트러블슈팅 ​

발행 결과가 화면에 안 보이고 "처리 중" 으로 머물러요 ​

원인 후보:

  1. 워크허브 측 웹훅 미설정 — 운영자가 POPBILL_WEBHOOK_SECRET + 팝빌 콘솔 콜백 URL 등록을 안 한 경우 → 운영자 문의
  2. 팝빌 측 처리 지연 — 보통 1~3분 내 완료, 드물게 10분 이상 걸리면 팝빌 측 장애 가능
  3. 수동 새로고침: 매출 대장의 발행 행 우측 [상태 갱신] 버튼으로 즉시 조회 가능

입금내역이 안 들어와요 ​

체크:

  1. 팝빌 측 계좌가 "활성" 상태인지 (휴면/만료된 ARS 인증)
  2. 워크허브 외부 연동 화면에서 "팝빌 — 계좌조회" 카드 상태가 "연결됨" 인지
  3. 마지막 폴링 시각이 최근 24시간 내인지 (카드에 표시)

같은 자격증명으로 두 모듈 모두 등록 가능? ​

가능. 같은 팝빌 계정(LinkID + 사업자번호) 으로 전자세금계산서 + 계좌조회 둘 다 활성 가능. 포인트는 하나의 팝빌 지갑에서 공유 차감.

6. 보안 / 개인정보 ​

  • 자격증명은 AES-GCM 으로 암호화 후 DB 저장 — 워크허브 운영자도 평문 조회 불가
  • 마스터 키는 DB 외부 (운영 환경변수) 에 보관 — DB 덤프 유출 시에도 자격증명 보호
  • 본 화면 응답의 SecretKey 는 항상 마스킹 (••••••••)
  • 연결 해제 시 → 자격증명 즉시 삭제 (복구 불가)
  • 팝빌 측에서 LinkID 회수 시 → 워크허브에서 자동 감지 (다음 호출에서 401) → 상태 "expired" 표시

7. 운영자 (시스템관리자) 참고 ​

워크허브 운영자가 1회 세팅해야 하는 항목 (기관관리자와 무관):

환경변수목적미설정 시
EXTERNAL_CONN_ENC_KEY자격증명 AES-GCM 마스터 키외부 연동 모듈 전체 비활성 (503)
POPBILL_WEBHOOK_SECRET발행 결과 콜백 검증발행 결과 자동 갱신 안됨 (수동 새로고침 의존)

팝빌 콘솔에 콜백 URL 등록:

  • URL: https://<워크허브 호스트>/api/finance/tax/popbill/webhook
  • secret: 위 POPBILL_WEBHOOK_SECRET 과 동일 값

관련 가이드 ​

Workhub 업무협업 플랫폼

© 2026 Workhub. All rights reserved.