xdata-kr Composite Pack API

openapi: 3.2.0
info:
  title: XBOSS Composite Pack API
  description: '통합 REST API 서버 (홈택스 등). Human API guide: https://developer.xdata.kr · OpenAPI Reference: /docs'
  version: 2.0.0
security:
- basicClientCredential: []
- mcpOAuth2: []
tags:
- name: CompositePack
paths:
  /v1/packs:
    post:
      tags:
      - CompositePack
      summary: 묶음 실행 제출 (202 + 폴링)
      description: '묶음 실행을 접수하고 **바로 돌려준다**(기관 호출이 끝나기를 기다리지 않는다).


        새로 접수하면 202, 같은 `Idempotency-Key` 와 같은 본문으로 다시 보내면 200 으로 그 실행의 지금 상태를

        돌려준다(단일 작업 제출과 같은 규칙이다). 접수한 뒤에는 `GET /v1/packs/{pack_run_id}` 로 끝날 때까지

        조회한다.'
      operationId: submit_pack_v1_v1_packs_post
      parameters:
      - 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: Idempotency-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Idempotency-Key
      - name: User-Agent
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: User-Agent
      - 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/PackRunSubmitRequest'
      responses:
        '200':
          description: 같은 멱등키와 같은 본문으로 다시 보낸 요청 - 그 실행의 지금 상태다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackRunResponse'
        '202':
          description: 새 접수 - 묶음 실행이 시작됐다. 이어서 상태 조회로 끝날 때까지 확인한다.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/packs/{pack_run_id}:
    get:
      tags:
      - CompositePack
      summary: 묶음 실행 조회 - 이 호출이 단계를 한 칸 민다
      description: '묶음 실행의 지금 상태를 읽는다. **이 호출이 아직 끝나지 않은 실행을 한 단계 진행시킨다**(기다리지

        않고 지금 상태를 돌려준다). 끝날 때까지 이 주소를 폴링한다.


        끝난 실행은 진행시키지 않고 읽어서 그대로 돌려준다.

        연동 계정을 쓰는 팩은 처음 단계를 진행시킨 사용자와 다른 사용자의 키로 조회하면 지금 상태만 읽고 단계는 진행하지 않는다.'
      operationId: get_pack_run_v1_v1_packs__pack_run_id__get
      parameters:
      - name: pack_run_id
        in: path
        required: true
        schema:
          type: string
          title: Pack Run 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: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: User-Agent
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: User-Agent
      - 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/PackRunResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/packs/{pack_run_id}/artifacts:
    delete:
      tags:
      - CompositePack
      summary: 묶음 실행 결과 파일 삭제
      description: '끝난 묶음 실행의 결과 파일을 보관 기간이 지나기 전에 지운다. 단일 작업의 결과 파일 삭제와 같은 모양이다.


        실행을 진행시키지 않는다 - 지우기는 읽기도 실행도 아니다.


        응답 분기:

        - 실행이 없거나 다른 조직이나 환경의 것이면 → 404 RESOURCE_NOT_FOUND (상태 조회와 같은 코드)

        - 상태가 SUCCEEDED 가 아니면 → 409 RESOURCE_CONFLICT

        - 상태가 SUCCEEDED 이면 → 200 OK + `deleted_count` (다시 부르면 0)

        - 정책 거부 → 401, 403, 429 등

        - pack_run_id 형식 오류 → 400 VALIDATION_INVALID_FIELD'
      operationId: delete_pack_run_artifacts_v1_v1_packs__pack_run_id__artifacts_delete
      parameters:
      - name: pack_run_id
        in: path
        required: true
        schema:
          type: string
          title: Pack Run 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: 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/PackArtifactsDeleteResponse'
        '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
    PackRunSubmitRequest:
      properties:
        provider:
          type: string
          minLength: 1
          title: Provider
          description: 팩 provider (조합 상품)
        action:
          type: string
          minLength: 1
          title: Action
          description: 팩 action
        params:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Params
          description: 팩 파라미터 (선택). 실행기가 leg 로 나눠 쓴다.
      additionalProperties: false
      type: object
      required:
      - provider
      - action
      title: PackRunSubmitRequest
      description: '팩 실행 제출 본문. 받는 이름은 셋뿐이고 나머지는 **거절**한다.


        이름 셋은 단일 작업 제출 본문과 같은 낱말이라(`provider` · `action` · `params`) 고객이 두 계약을

        따로 배우지 않는다.'
    PackRunResponse:
      properties:
        pack_run_id:
          type: string
          title: Pack Run Id
          description: 묶음 실행 번호. 상태 조회와 결과 파일 삭제의 주소에 쓴다.
        status:
          type: string
          title: Status
          description: RUNNING, SUCCEEDED, FAILED, TIMEOUT 중 하나.
        env_scope:
          type: string
          title: Env Scope
          description: 요청한 환경 그대로. `sandbox`, `real_test`, `production` 중 하나.
        provider:
          type: string
          title: Provider
        action:
          type: string
          title: Action
        submitted_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Submitted At
          description: KST ISO-8601. 접수한 시각.
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
          description: KST ISO-8601. 끝나기 전이면 없다.
        progress:
          anyOf:
          - type: integer
          - type: 'null'
          title: Progress
          description: 0~100. 값과 문구는 단일 작업 조회와 같은 규칙에서 온다.
        progress_message:
          anyOf:
          - type: string
          - type: 'null'
          title: Progress Message
          description: 지금 무엇을 하고 있는지 한국어 한 줄. 끝난 실행에는 없다.
        retry_after_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          title: Retry After Seconds
          description: 다음 조회까지 기다릴 초. 끝난 실행에는 없다.
        legs:
          items:
            $ref: '#/components/schemas/PackLegEnvelope'
          type: array
          title: Legs
          description: 묶음을 이루는 호출 목록. 접수 직후에는 아직 제출되지 않은 단계의 칸이 비어 있다.
        result:
          anyOf:
          - $ref: '#/components/schemas/PackResultPayload'
          - type: 'null'
          description: SUCCEEDED 로 끝났을 때의 결과. 끝나기 전이거나 실패했으면 없다.
        error:
          anyOf:
          - $ref: '#/components/schemas/PackRunErrorEnvelope'
          - type: 'null'
          description: FAILED 또는 TIMEOUT 으로 끝났을 때의 오류.
      type: object
      required:
      - pack_run_id
      - status
      - env_scope
      - provider
      - action
      - legs
      title: PackRunResponse
      description: 묶음 실행의 접수 응답과 상태 조회 응답 - 두 응답은 같은 칸을 가진다.
    PackRunErrorEnvelope:
      properties:
        code:
          anyOf:
          - type: integer
          - type: 'null'
          title: Code
          description: 숫자 오류 코드. 표준 오류 코드 문자열은 `data.error_code` 에 있다.
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: 고객에게 보여 줄 한국어 설명.
        data:
          anyOf:
          - {}
          - type: 'null'
          title: Data
          description: 오류의 추가 정보. `error_code`(표준 오류 코드), `safe_to_retry`(다시 불러도 되는가)가 들어 있을 수 있다. 문서 파일을 만들지 못한 실패에는 받은 자료가 함께 들어 있다.
      type: object
      title: PackRunErrorEnvelope
      description: 실패한 묶음 실행의 오류.
    JobArtifactEntry:
      properties:
        artifact_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Artifact Id
          description: '`art_` + 26자 ULID.'
        name:
          type: string
          title: Name
          description: 받을 파일명(`업무명_YYYYMMDD[_구분].확장자`).
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
          description: '예: `application/pdf`.'
        size_bytes:
          anyOf:
          - type: integer
          - type: 'null'
          title: Size Bytes
        sha256:
          anyOf:
          - type: string
          - type: 'null'
          title: Sha256
          description: 받은 파일과 대조할 해시(16진수 64자).
        expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Expires At
          description: KST ISO-8601. 이 시각 뒤로는 파일을 받을 수 없다(보관 7일).
        expired:
          type: boolean
          title: Expired
          description: 보관 기간이 지났는가. 참이면 `download_url` 이 없다.
        download_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Download Url
          description: 서명된 단기 URL(15분). 지나면 결과를 다시 조회하면 새로 받는다.
      type: object
      required:
      - name
      - expired
      title: JobArtifactEntry
      description: '`result.artifacts[]` 항목 하나 - 상품이 낸 문서 파일.


        이 표준 전에 끝난 작업의 파일은 `artifact_id` · `size_bytes` · `sha256` 이 없다.

        `expires_at` 은 그 옛 파일에도 있다 - 끝난 시각에서 계산해 채운다.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PackLegEnvelope:
      properties:
        job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: 작업 번호
          description: 이 단계로 제출된 호출의 번호. 아직 제출되지 않았으면 없다.
        provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
          description: 이 단계가 부른 상품 묶음.
        action:
          anyOf:
          - type: string
          - type: 'null'
          title: Action
          description: 이 단계가 부른 기능.
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
          description: 이 단계 호출의 상태. 아직 제출되지 않았으면 없다.
      type: object
      title: PackLegEnvelope
      description: 묶음을 이루는 호출 하나의 지금 상태.
    PackResultPayload:
      properties:
        artifacts:
          items:
            $ref: '#/components/schemas/JobArtifactEntry'
          type: array
          title: Artifacts
          description: 문서 파일 목록. 파일을 내지 않는 묶음이면 빈 배열이다.
        artifacts_note:
          anyOf:
          - type: string
          - type: 'null'
          title: Artifacts Note
          description: 청한 문서 파일을 만들지 못했을 때만 있는 설명 문장. 일부 조회가 끝나지 않아 계산 결과가 없으면 파일을 만들지 않고 받은 자료만 이 응답에 담는다. 모든 조회가 끝난 뒤 새 멱등 키로 다시 요청하면 파일이 만들어진다.
      additionalProperties: true
      type: object
      title: PackResultPayload
      description: '묶음 실행이 성공으로 끝났을 때의 결과.


        `artifacts` 는 문서 파일 목록이다(항상 배열, 파일을 내지 않는 묶음이면 빈 배열). 나머지 칸은 묶음

        종류마다 다르다.'
    PackArtifactsDeleteResponse:
      properties:
        pack_run_id:
          type: string
          title: Pack Run Id
          description: 파일을 지운 묶음 실행 번호.
        deleted_count:
          type: integer
          title: Deleted Count
          description: 이번 요청이 지운 파일 수. 이미 지웠으면 0 이다.
      type: object
      required:
      - pack_run_id
      - deleted_count
      title: PackArtifactsDeleteResponse
      description: '`DELETE /v1/packs/{pack_run_id}/artifacts` 성공 응답.


        같은 요청을 다시 보내도 200 이고 `deleted_count` 가 0 이다. 지운 파일은 상태 조회의

        `result.artifacts` 에서 빠진다.'
  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: {}