---
title: "묶음 실행 제출 (202 + 폴링)"
method: POST
path: "/v1/packs"
tags: ["CompositePack"]
---

# 묶음 실행 제출 (202 + 폴링)

`POST /v1/packs`

## Request

- Base URL: `https://api.xdata.kr` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xdata.kr/v1/packs`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://api.xdata.kr/oauth/authorize`, token URL `https://api.xdata.kr/oauth/token`)

묶음 실행을 접수하고 **바로 돌려준다**(기관 호출이 끝나기를 기다리지 않는다).

새로 접수하면 202, 같은 `Idempotency-Key` 와 같은 본문으로 다시 보내면 200 으로 그 실행의 지금 상태를
돌려준다(단일 작업 제출과 같은 규칙이다). 접수한 뒤에는 `GET /v1/packs/{pack_run_id}` 로 끝날 때까지
조회한다.

## Query parameters

- `env_scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Headers

- `Authorization` string, nullable
- `Idempotency-Key` string, nullable
- `User-Agent` string, nullable
- `X-Env-Scope` 'production' | 'real_test' | 'sandbox', nullable: 환경을 고릅니다. 값은 production · real_test · sandbox 중 하나입니다. 경로 접두(/v1/sandbox/... · /v1/test/... · /v1/production/...) · X-Env-Scope 헤더 · env_scope 쿼리 가운데 한 통로로 반드시 보내야 합니다. 빼면 자동으로 채우지 않고 거절하며, 두 통로에 서로 다른 값을 담아도 거절합니다. 거절은 HTTP 422 이고 오류 코드는 VALIDATION_ENV_SCOPE_MISMATCH 입니다.

## Request body

- PackRunSubmitRequest: 팩 실행 제출 본문. 받는 이름은 셋뿐이고 나머지는 **거절**한다. 이름 셋은 단일 작업 제출 본문과 같은 낱말이라(`provider` · `action` · `params`) 고객이 두 계약을 따로 배우지 않는다.
  - `provider` string, required: 팩 provider (조합 상품)
  - `action` string, required: 팩 action
  - `params` object, nullable: 팩 파라미터 (선택). 실행기가 leg 로 나눠 쓴다.

## Response `200`

같은 멱등키와 같은 본문으로 다시 보낸 요청 - 그 실행의 지금 상태다.

- PackRunResponse: 묶음 실행의 접수 응답과 상태 조회 응답 - 두 응답은 같은 칸을 가진다.
  - `pack_run_id` string, required: 묶음 실행 번호. 상태 조회와 결과 파일 삭제의 주소에 쓴다.
  - `status` string, required: RUNNING, SUCCEEDED, FAILED, TIMEOUT 중 하나.
  - `env_scope` string, required: 요청한 환경 그대로. `sandbox`, `real_test`, `production` 중 하나.
  - `provider` string, required
  - `action` string, required
  - `submitted_at` string, nullable: KST ISO-8601. 접수한 시각.
  - `completed_at` string, nullable: KST ISO-8601. 끝나기 전이면 없다.
  - `progress` integer, nullable: 0~100. 값과 문구는 단일 작업 조회와 같은 규칙에서 온다.
  - `progress_message` string, nullable: 지금 무엇을 하고 있는지 한국어 한 줄. 끝난 실행에는 없다.
  - `retry_after_seconds` integer, nullable: 다음 조회까지 기다릴 초. 끝난 실행에는 없다.
  - `legs` PackLegEnvelope[], required: 묶음을 이루는 호출 목록. 접수 직후에는 아직 제출되지 않은 단계의 칸이 비어 있다.
    - `job_id` string, nullable: 이 단계로 제출된 호출의 번호. 아직 제출되지 않았으면 없다.
    - `provider` string, nullable: 이 단계가 부른 상품 묶음.
    - `action` string, nullable: 이 단계가 부른 기능.
    - `status` string, nullable: 이 단계 호출의 상태. 아직 제출되지 않았으면 없다.
  - `result` PackResultPayload: 묶음 실행이 성공으로 끝났을 때의 결과. `artifacts` 는 문서 파일 목록이다(항상 배열, 파일을 내지 않는 묶음이면 빈 배열). 나머지 칸은 묶음 종류마다 다르다.
    - `artifacts` JobArtifactEntry[]: 문서 파일 목록. 파일을 내지 않는 묶음이면 빈 배열이다.
      - `artifact_id` string, nullable: `art_` + 26자 ULID.
      - `name` string, required: 받을 파일명(`업무명_YYYYMMDD[_구분].확장자`).
      - `content_type` string, nullable: 예: `application/pdf`.
      - `size_bytes` integer, nullable
      - `sha256` string, nullable: 받은 파일과 대조할 해시(16진수 64자).
      - `expires_at` string, nullable: KST ISO-8601. 이 시각 뒤로는 파일을 받을 수 없다(보관 7일).
      - `expired` boolean, required: 보관 기간이 지났는가. 참이면 `download_url` 이 없다.
      - `download_url` string, nullable: 서명된 단기 URL(15분). 지나면 결과를 다시 조회하면 새로 받는다.
  - `error` PackRunErrorEnvelope: 실패한 묶음 실행의 오류.
    - `code` integer, nullable: 숫자 오류 코드. 표준 오류 코드 문자열은 `data.error_code` 에 있다.
    - `message` string, nullable: 고객에게 보여 줄 한국어 설명.
    - `data` unknown

## Other responses

- `202`: 새 접수 - 묶음 실행이 시작됐다. 이어서 상태 조회로 끝날 때까지 확인한다.
- `422`: Validation Error

---

[API](https://skmtc.dev/xdata/apis/xboss-api.md) · [All operations](https://skmtc.dev/xdata/apis/xboss-api/llms.txt) · [OpenAPI document](https://skmtc.dev/xdata/apis/xboss-api/revisions/816de78950db?raw)