세금계산서 웹훅 가이드

✔️ 웹훅이란?

포트원 파트너 정산 내 세금계산서 제품은 세금계산서의 상태가 변경되었을 때 고객사가 사전에 설정한 URL로 즉각적으로 이벤트와 관련된 정보를 전달하여 효율적인 시스템 연동을 지원합니다.

웹훅이 필요한 이유

웹훅은 다음과 같은 이유로 시스템 간 효율적인 통합에 필수적입니다.

• 리소스 절약: 주기적으로 데이터를 폴링(polling)하지 않고 이벤트 발생 시에만 정보를 받아볼 수 있어 리소스와 네트워크 대역폭을 크게 절약합니다.
• 실시간성: 이벤트 발생 직후 즉시 알림을 받을 수 있어 지연 없이 후속 처리가 가능합니다.
• 확장성: 여러 시스템이나 서비스를 쉽게 연동할 수 있어 비즈니스 프로세스 자동화와 확장에 용이합니다.

✔️ 세금계산서 웹훅 사용 예시

사용 시나리오

• 세금계산서가 국세청에 성공적으로 전송 완료된 경우에만 정산금 지급 처리를 수행해야 하는 정책이 존재할 수 있습니다. 이 때 세금계산서 상태를 확인하기 위해 반복하여 콘솔에 접속하지 않고도 웹훅을 통해 실시간으로 상태 알림을 전달받을 수 있습니다.

• 고객사의 내부 데이터베이스에 세금계산서의 상태를 직접 관리하고자 하는 경우, 상태 변화를 내부 시스템에 실시간으로 반영합니다.

동작 흐름

1. 포트원에서 특정 이벤트(예: 세금계산서 국세청 전송 완료)가 발생합니다.
2. 고객사가 사전에 설정한 웹훅 URL로 JSON 데이터를 포함한 HTTP POST 요청이 발송됩니다.
3. 고객사 서버는 웹훅 데이터를 받아 필요한 내부 로직을 처리합니다.

예시 코드 (Node.js)

const express = require("express");
const app = express();

app.use(express.json());

// 포트원에 사전 설정된 웹훅 URL 예시: https://<고객사 서버 URL>/webhook/taxinvoice
app.post("/webhook/taxinvoice", (req, res) => {
  const event = req.body;

  switch (event.type) {
    case "TaxInvoice.SendingCompleted":
      // 세금계산서 국세청 전송 완료 로직 처리
      handleSendingCompleted(event.data);
      break;
    // 다른 이벤트 처리 로직 추가 가능
  }

  res.status(200).send("Webhook received successfully");
});

✔️ 웹훅 스키마

웹훅 데이터는 다음 JSON 구조로 전달됩니다.

실제 웹훅 데이터 예시

{
  "type": "TaxInvoice.SendingCompleted",
  "timestamp": "2025-03-20T14:25:10Z",
  "data": {
    "taxInvoiceId": "txi-test",
    "supplierDocumentKey": "sdk-test",
    "recipientDocumentKey": "rdk-test",
    "status": "SENDING_COMPLETED",
    "supplierBrn": "1234567890",
    "totalAmount": 110000,
    "totalSupplyAmount": 100000,
    "totalTaxAmount": 10000
  }
}

type 상세 정보

웹훅을 트리거한 이벤트의 타입으로, 아래와 같은 종류로 구성됩니다.

• TaxInvoice.Requested: 역발행 요청이 완료된 경우
• TaxInvoice.Issued: 공급자가 발행을 승인한 경우
• TaxInvoice.RequestCancelled: 공급받는자가 역발행 요청을 취소한 경우
• TaxInvoice.IssuanceCancelled: 공급자가 역발행 승인 이후 취소한 경우
• TaxInvoice.Refused: 공급자가 역발행 요청을 발행 거부한 경우
• TaxInvoice.SendingCompleted: 발행 완료된 세금계산서가 국세청에 전송 완료된 경우
• TaxInvoice.Manual: 특정 이벤트가 발생하지 않고 수동 웹훅 재발송 기능을 이용한 경우 (수동 웹훅 발송 API는 추후 지원 예정)

data 객체 상세

status 상세 정보

세금계산서의 현재 상태를 나타내는 값으로, 다음과 같은 종류로 구성됩니다. 웹훅의 경우 아래 상태들 중 주요 상태로 변경되는 이벤트에 대해서만 발송됩니다.

• DRAFTED: 임시 저장 완료
• DRAFT_PENDING: 임시 저장 대기 (일괄 발행 시 시스템의 처리 대기 상태)
• DRAFT_FAILED: 임시 저장 실패
• REQUESTED: 발행 요청 완료 (공급자에게 이메일이 발송된 상태)
• REQUEST_PENDING: 발행 요청 대기 (일괄 발행 시 시스템의 처리 대기 상태)
• REQUEST_FAILED: 발행 요청 실패
• REQUEST_CANCELLED: 공급받는 자에 의한 발행 취소 (공급자가 역발행 승인하기 이전에 공급받는자가 미리 취소한 상태)
• REQUEST_REFUSED: 발행 요청 거부
• ISSUED: 발행 완료
• ISSUANCE_CANCELLED: 공급자에 의한 발행 취소 (공급자가 역발행 승인 이후 취소된 상태)
• BEFORE_SENDING: 국세청 전송 전
• WAITING_SENDING: 국세청 전송 대기
• SENDING: 국세청 전송 중
• SENDING_COMPLETED: 국세청 전송 완료 (세금계산서가 발행 승인되어 최종적으로 국세청까지 전달된 상태)
• SENDING_FAILED: 국세청 전송 실패

✔️ 웹훅 설정 방법

포트원 세금계산서 웹훅은 기술팀에서 직접 설정합니다. 아래 절차를 따라 웹훅 설정을 요청해주세요.

설정 요청 절차

1. 웹훅 수신 URL을 준비해주세요.
2. 기술지원 이메일(support.b2b@portone.io)로 웹훅 URL(운영 환경, 테스트 환경 별도 적용 가능)을 전달해주세요.
3. 테스트 모드 설정이 완료되었다는 회신을 받으면 테스트 모드에서 웹훅 정상 작동 여부를 확인해주세요
4. 운영 환경에도 적용을 요청하신 뒤 운영 환경에서 웹훅 정상 작동 여부를 확인해주세요.

테스트 모드 웹훅 정상 작동 확인 방법

• 포트원 콘솔에서 웹훅 테스트 토글을 활성화해주세요.
• 테스트용 세금계산서를 발행 요청하면 설정된 테스트용 URL로 웹훅이 전송됩니다.

IP 필터링 안내

포트원은 아래 고정 IP를 사용하여 웹훅을 전송합니다.

안전한 웹훅 수신을 위해 IP 필터링이 필요하신 경우, 아래 IP를 허용 목록에 추가해 주세요.

• 포트원 V2 웹훅 IP: 52.78.5.241

추후 웹훅 발송 IP가 추가/변경될 경우 사전에 메일로 안내드릴 예정이며, 이 때 IP 필터를 업데이트해 주셔야 정상적으로 웹훅 수신이 가능합니다.

웹훅 실패 시 재시도 정책

웹훅 요청 시 실패 응답을 받은 경우, 포트원에서는 총 5회(최초 요청 + 4회 재시도)까지 웹훅 전송을 시도합니다. 또한 고객사의 시스템 장애 상황에서 웹훅 과부하로 인한 영향을 최소화하기 위해 다음과 같은 재시도 정책을 적용하고 있습니다:

• 지수함수 형태로 지연 시간을 점진적으로 늘리는 Exponential Backoff 방식
• 지연 시간에 무작위성을 추가하는 Equal Jitter 정책

이러한 정책에 따라 각 재시도는 5분, 10분, 20분, 40분의 기본 지연시간을 기반으로 하지만, 실제 지연시간은 기본값의 절반 정도의 무작위성을 추가하여 결정됩니다. 위에서 언급된 재시도 정책의 자세한 기술적 내용이 궁금하시면 포트원 기술 블로그 - 웹훅 재시도에서 확인하실 수 있습니다.