외부 업무 API gateway

leysys-integrations는 결제가 아닌 공용 외부 업무 API를 여러 제품이 재사용하는 경계입니다. 업체별 저장소나 제품별 SDK wrapper가 아니라 capability별 interface를 정의합니다.

구현 참고와 확인 범위

이 페이지는 Integrations gateway의 계획·구현 계약입니다. 2026-07-15 KST에는 local foundation과 SDK 미배포 상태로 기록됐으며, 현재 운영 제공 여부는 재검증하지 않았습니다. 현재 제공 상태와 대상 런타임을 확인한 뒤 채택하십시오.

Capability 계약

Interface	대표 동작
TaxInvoiceProvider	발행, 취소, 상태 조회, 같은 provider 대사
CashReceiptProvider	발행, 취소, 상태 조회
BusinessStatusProvider	사업자 상태 단건·다건 조회
MessagingProvider	SMS/LMS/MMS 등 정규화된 메시지 전송

BarobillProvider와 PopbillProvider는 이 interface의 adapter입니다. 제품은 provider 이름이나 provider 전용 필드를 요청에 넣지 않습니다.

공통 client method

계획된 @leysys/integrations-client의 capability method는 다음과 같습니다.

• issueTaxInvoice
• cancelTaxInvoice
• issueCashReceipt
• cancelCashReceipt
• getBusinessStatuses
• sendMessage
• getOperation

client SDK에는 타입과 HTTP client만 둡니다. provider SDK, SOAP client, 인증키, service-role key를 넣지 않습니다.

Routing 원칙

1. account와 capability에 승인된 route를 찾습니다.
2. 기존 document binding이 있으면 그 provider를 무조건 사용합니다.
3. binding이 없는 새 document에만 cohort 정책을 적용합니다.
4. 첫 mutation 전에 document key와 provider connection을 영구 연결합니다.
5. 결과가 unknown이면 같은 provider로 대사합니다.

구 고객은 Popbill, 신규 고객은 Barobill이라는 정책은 3번에서만 작동합니다. 이미 Popbill에서 발행한 문서를 Barobill로 취소하려고 시도하면 안 됩니다.

결제 control plane과 분리하는 이유

• 회계 문서는 결제와 다른 법적·운영 상태를 갖습니다.
• provider 원문에 포함되는 개인정보와 보존 기간이 다릅니다.
• 문서 발행의 불명확 상태는 중복 발행 위험 때문에 자동 failover가 특히 위험합니다.
• Barobill/Popbill 장애가 결제·entitlement 조회에 전파되면 안 됩니다.