세금계산서

제품은 자신의 invoice domain object를 versioned canonical tax invoice로 변환해 integrations gateway에 보냅니다. gateway가 account route와 기존 document binding을 확인해 Barobill 또는 Popbill adapter를 호출합니다.

예정 소비 계약

미배포

아래 @leysys/integrations-client 예시는 현재 타입 계약이며 아직 package registry나 운영 API에서 사용할 수 없습니다.

import { createIntegrationsClient } from '@leysys/integrations-client'

const integrations = createIntegrationsClient({
  baseUrl: process.env.LEYSYS_INTEGRATIONS_URL!,
})

const operation = await integrations.issueTaxInvoice({
  documentKey: localInvoiceId,
  document: canonicalTaxInvoice,
  idempotencyKey: crypto.randomUUID(),
  accessToken: productServiceToken,
})

안정 식별자

식별자	소유자	재시도 규칙
documentKey	제품	같은 업무 문서에는 영구 재사용
idempotencyKey	제품 operation	같은 사용자 의도의 재요청에는 재사용
operation ID	integrations	처리·대사 상태 조회에 사용
provider document ID	integrations	제품에 provider 의미로 노출하지 않고 binding에 보존

네트워크 timeout이 발생했다고 새 documentKey나 idempotency key를 만들어 다시 발행하면 중복 문서가 생길 수 있습니다.

unknown 처리

const latest = await integrations.getOperation({
  operationId: operation.id,
  accessToken: productServiceToken,
})

• 같은 operation을 조회합니다.
• 제품은 mutation을 다시 제출하지 않습니다.
• provider를 바꾸지 않습니다.
• gateway가 reconcile_same_provider를 수행합니다.
• 사람이 확인해야 하면 operation을 manual review queue에 남깁니다.

취소

취소는 원본 document binding을 따라갑니다. 원본이 Popbill이면 취소도 Popbill adapter가 처리하고, 원본이 Barobill이면 Barobill adapter가 처리합니다. 취소 결과가 불명확하면 다른 provider에 취소나 음수 문서를 자동 제출하지 않습니다.

데이터 경계

• 제품은 canonical document 작성에 필요한 업무 데이터만 보냅니다.
• gateway는 provider 요청·응답 원문, provider document ID, 재시도, 오류 분류, 감사 로그를 보존합니다.
• 제품 로그에는 세금계산서 원문이나 provider credential을 복제하지 않습니다.
• 주민등록번호 등 고위험 필드는 capability schema가 명시적으로 허용하지 않는 한 거부합니다.