xdata-kr Billing Webhooks API

openapi: 3.2.0
info:
  title: XBOSS Billing Webhooks API
  description: '통합 REST API 서버 (홈택스 등). Human API guide: https://developer.xdata.kr · OpenAPI Reference: /docs'
  version: 2.0.0
security:
- basicClientCredential: []
- mcpOAuth2: []
tags:
- name: Billing Webhooks
paths:
  /v1/billing/webhooks/{provider}:
    post:
      tags:
      - Billing Webhooks
      summary: Receive Webhook
      description: PG 웹훅 수신 - 받은 뒤 7단계로 처리한다.
      operationId: receive_webhook_v1_billing_webhooks__provider__post
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      - name: X-Env-Scope
        in: header
        required: false
        schema:
          anyOf:
          - enum:
            - sandbox
            - real_test
            - production
            type: string
          - type: 'null'
          description: 외부 PG 가 보내는 환경 힌트입니다(필수가 아닙니다). 값은 production, real_test, sandbox 중 하나이고, 보내면 그 환경의 서명만 검증합니다. 보내지 않으면 production, real_test, sandbox 순서로 시도해 서명이 맞는 환경을 고릅니다. 목록 밖의 값은 HTTP 400 WEBHOOK_PAYLOAD_INVALID 로 거절합니다.
          title: X-Env-Scope
        description: 외부 PG 가 보내는 환경 힌트입니다(필수가 아닙니다). 값은 production, real_test, sandbox 중 하나이고, 보내면 그 환경의 서명만 검증합니다. 보내지 않으면 production, real_test, sandbox 순서로 시도해 서명이 맞는 환경을 고릅니다. 목록 밖의 값은 HTTP 400 WEBHOOK_PAYLOAD_INVALID 로 거절합니다.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookAckResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    WebhookAckResponse:
      properties:
        received:
          type: boolean
          const: true
          title: Received
          description: 수신 확인. 잠금된 단일 값(`true`). PG 사업자 호환 보존 위해 변경 금지. false 반환 케이스는 정의되지 않으며, 영구 오류도 `received=true` + 내부 FAILED 분류.
      additionalProperties: false
      type: object
      required:
      - received
      title: WebhookAckResponse
      description: "PG 웹훅 수신 ACK 응답.\n\n외부 응답은 단순 ack만 반환한다:\n    - 정상 처리: 200 OK + `{ \"received\": true }`\n    - 중복 수신: 200 OK + `{ \"received\": true }` (SKIPPED_DUPLICATE 내부 분류)\n    - 영구 오류: 200 OK + `{ \"received\": true }` (FAILED 내부 분류; PG 재전송 폭주 방지)\n\nPG가 비-2xx 응답 시 재전송하므로, 비즈 처리 실패가 일시적이지 않은 **영구 오류**라면\n200 OK + `processing_status='FAILED'` 적재로 재전송 폭주를 막는다.\n\n서명 실패/payload 오류는 본 DTO 대신 표준 오류 envelope으로 응답:\n    - 401 WEBHOOK_SIGNATURE_INVALID\n    - 400 WEBHOOK_PAYLOAD_INVALID\n    - 503 PROVIDER_UNAVAILABLE (PG 자동 재전송 유도)\n\n응답 시그니처는 PG 사업자별로 호환을 유지해야 하므로(PG 재시도 정책 보존),\n필드 추가/제거/변경은 상위 계약과 이 docstring 을 함께 고치고 별도 결정을 거친다.\n\n본 응답은 외부 노출 전용 — `billing_events.id`/`processing_status` 등 내부 식별자는\n포함하지 않는다(증거 보존 + 운영 API 분리)."
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  securitySchemes:
    basicClientCredential:
      type: http
      scheme: basic
      description: 'Console-issued client credential. Send `Authorization: Basic base64(client_id:client_secret)`.'
    mcpOAuth2:
      type: oauth2
      description: For MCP clients. OAuth 2.0 authorization code flow with PKCE (S256) for public clients. The client_id is the HTTPS URL of an OAuth Client ID Metadata Document that XBOSS has allow-listed; dynamic client registration is not supported.
      flows:
        authorizationCode:
          authorizationUrl: https://api.xdata.kr/oauth/authorize
          tokenUrl: https://api.xdata.kr/oauth/token
          scopes: {}