xdata-kr Product Catalog Versions API

openapi: 3.2.0
info:
  title: XBOSS Product Catalog Versions API
  description: '통합 REST API 서버 (홈택스 등). Human API guide: https://developer.xdata.kr · OpenAPI Reference: /docs'
  version: 2.0.0
security:
- basicClientCredential: []
- mcpOAuth2: []
tags:
- name: Product Catalog Versions
paths:
  /v1/products/{product_id}/versions:
    post:
      tags:
      - Product Catalog Versions
      summary: Create Product Version
      operationId: create_product_version_v1_products__product_id__versions_post
      parameters:
      - name: product_id
        in: path
        required: true
        schema:
          type: integer
          title: Product Id
      - name: env_scope
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
          enum:
          - production
          - real_test
          - sandbox
          title: Env Scope
        description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
      - name: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Env-Scope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
          enum:
          - production
          - real_test
          - sandbox
          title: X-Env-Scope
        description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductVersionCreateRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProductVersionResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Product Catalog Versions
      summary: List Product Versions
      operationId: list_product_versions_v1_products__product_id__versions_get
      parameters:
      - name: product_id
        in: path
        required: true
        schema:
          type: integer
          title: Product Id
      - name: query
        in: query
        required: true
        schema:
          $ref: '#/components/schemas/ProductVersionListQuery'
      - name: env_scope
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
          enum:
          - production
          - real_test
          - sandbox
          title: Env Scope
        description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: X-Env-Scope
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
          enum:
          - production
          - real_test
          - sandbox
          title: X-Env-Scope
        description: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageEnvelope_ProductVersionResponse_'
        '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
    ProductVersionListQuery:
      properties:
        limit:
          type: integer
          maximum: 100.0
          minimum: 1.0
          title: Limit
          default: 20
        cursor:
          anyOf:
          - type: string
            maxLength: 2048
          - type: 'null'
          title: Cursor
          description: opaque 커서 (BIGINT after_id 또는 URL-safe base64 인코딩 페이로드 — RFC 4648 §5). 최대 2048자 — RFC 7230 권고 HTTP URI 한도 (~8KB) 아래 안전 마진. 클라이언트는 본문을 해석하거나 만들지 않는다.
        sort:
          type: string
          enum:
          - created_at:asc
          - created_at:desc
          - version:asc
          - version:desc
          title: Sort
          default: created_at:desc
        version_status:
          anyOf:
          - items:
              type: string
              enum:
              - DRAFT
              - PUBLISHED
              - DEPRECATED
              - RETIRED
            type: array
            maxItems: 20
          - type: 'null'
          title: Version Status
          description: 버전 상태 필터. 다중 콤마 (`?version_status=PUBLISHED,DEPRECATED`) 또는 반복형 양쪽 허용. 최대 20 원소.
      type: object
      title: ProductVersionListQuery
      description: '`GET /v1/products/{product_id}/versions` 쿼리 파라미터.


        페이지네이션 + 필터. 부모 `product_id` 는 경로 파라미터(본 DTO 영역 외).'
    PageEnvelope_ProductVersionResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ProductVersionResponse'
          type: array
          title: Items
          description: Page result items. Empty list allowed.
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Opaque cursor for next page, or null on last page.
        has_more:
          type: boolean
          title: Has More
          description: Whether another page exists. False when next_cursor is null.
          default: false
      additionalProperties: false
      type: object
      title: PageEnvelope[ProductVersionResponse]
    ProductVersionCreateRequest:
      properties:
        version:
          type: string
          maxLength: 20
          minLength: 1
          pattern: ^[A-Za-z0-9._\-]{1,20}$
          title: Version
          description: '버전 식별자(예: ''v1''/''v2''). 같은 상품 안에서 유일해야 한다. 형식 `^[A-Za-z0-9._-]{1,20}$`.'
        provider:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z][a-z0-9_]{0,63}$
          title: Provider
          description: 등록된 기관 식별자. 등록되지 않은 값이면 400 VALIDATION_INVALID_FIELD 로 거절한다. 형식 `^[a-z][a-z0-9_]{0,63}$`.
        action:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z][a-z0-9_.]{0,63}$
          title: Action
          description: 등록된 액션 식별자. 기관에 종속한다. 형식 `^[a-z][a-z0-9_.]{0,63}$`.
        params_schema_ref:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Params Schema Ref
          description: '`provider.action.vN` 형식. 작업 결과의 schema 값과 같은 형식이다.'
        result_schema_ref:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Result Schema Ref
          description: 동상.
        pricing_hint:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pricing Hint
          description: 가격 표시 힌트. 정책을 결정하는 키는 넣을 수 없다. JSON 직렬화 후 최대 65536 bytes.
        rate_limit_hint:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Rate Limit Hint
          description: rate limit 표시 힌트. 정책을 결정하는 키는 넣을 수 없다. JSON 직렬화 후 최대 65536 bytes.
        metadata:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Metadata
          description: 자유 메타데이터. 정책을 결정하는 키는 넣을 수 없다. JSON 직렬화 후 최대 65536 bytes.
        publish_immediately:
          type: boolean
          title: Publish Immediately
          description: true 이면 발행 트랜잭션 안에서 version_status='PUBLISHED' + published_at=now(). false 이면 DRAFT 발행.
          default: false
        set_as_current:
          type: boolean
          title: Set As Current
          description: publish_immediately=true + 본 필드 true ⇒ api_products.current_version_id 동시 UPDATE. publish_immediately=false + 본 필드 true ⇒ 422 VALIDATION_SEMANTIC_ERROR.
          default: false
      additionalProperties: false
      type: object
      required:
      - version
      - provider
      - action
      title: ProductVersionCreateRequest
      description: '`POST /v1/products/{product_id}/versions` 요청 본문.


        자세한 SCHEMA 매핑과 제약은 이 클래스 위 주석에 있다.'
    ProductVersionResponse:
      properties:
        id:
          type: integer
          maximum: 9.223372036854776e+18
          minimum: 1.0
          title: Id
          description: api_product_versions.id.
        product_id:
          type: integer
          maximum: 9.223372036854776e+18
          minimum: 1.0
          title: Product Id
          description: 부모 api_products.id.
        version:
          type: string
          maxLength: 20
          minLength: 1
          pattern: ^[A-Za-z0-9._\-]{1,20}$
          title: Version
        version_status:
          type: string
          enum:
          - DRAFT
          - PUBLISHED
          - DEPRECATED
          - RETIRED
          title: Version Status
        provider:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z][a-z0-9_]{0,63}$
          title: Provider
        action:
          type: string
          maxLength: 64
          minLength: 1
          pattern: ^[a-z][a-z0-9_.]{0,63}$
          title: Action
        params_schema_ref:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Params Schema Ref
        result_schema_ref:
          anyOf:
          - type: string
            maxLength: 120
          - type: 'null'
          title: Result Schema Ref
        pricing_hint:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Pricing Hint
        rate_limit_hint:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Rate Limit Hint
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        env_scope:
          type: string
          enum:
          - sandbox
          - real_test
          - production
          title: Env Scope
          description: 부모 상품의 환경을 상속한다.
        published_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Published At
          description: 발행 시각. DRAFT 행은 NULL. PUBLISHED 진입 시 자동으로 채워진다.
        deprecated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Deprecated At
          description: 폐기 시각. PUBLISHED → DEPRECATED 전이 시 자동 채움.
        retired_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Retired At
          description: 종결 시각. DEPRECATED → RETIRED 전이 시 자동 채움. terminal.
        created_at:
          type: string
          format: date-time
          title: Created At
      additionalProperties: false
      type: object
      required:
      - id
      - product_id
      - version
      - version_status
      - provider
      - action
      - env_scope
      - created_at
      title: ProductVersionResponse
      description: "상품 버전 단일 객체 응답.\n\nSCHEMA → DTO 매핑:\n- `api_product_versions.id` → `id`.\n- `product_id` / `version` / `version_status` / `provider` / `action` / 스키마 ref 2종 /\n  `pricing_hint` / `rate_limit_hint` / `metadata` / `env_scope` / `created_at` →\n  직접 매핑.\n- lifecycle timestamps (`published_at` / `deprecated_at` / `retired_at`) — append-only\n  트리거가 단방향 전이 시 자동 채움. DRAFT 행은 모두 NULL.\n\n응답에서 `metadata`/`pricing_hint`/`rate_limit_hint` 노출 허용\n(자유 표시 메타다)."
    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: {}