---
title: "작업 제출"
method: POST
path: "/v1/jobs"
tags: ["UnifiedJob"]
---

# 작업 제출

`POST /v1/jobs`

## 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/jobs`
- 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`)

`POST /v1/jobs` 작업 제출 단일 진입점.

응답 분기:
    - 신규 INSERT (inserted=True)         → 202 Accepted
    - 멱등 매칭 (inserted=False, no conflict) → 200 OK
    - 멱등 충돌 (IdempotencyKeyConflict)  → 409 IDEMPOTENCY_KEY_CONFLICT
    - 정책 거부 (AuthPolicyError)         → 401/402/403/422/429
    - 입력 검증 실패 (ValueError)         → 400 VALIDATION_INVALID_FIELD
    - account_link 소유권 실패            → 404 RESOURCE_NOT_FOUND
    - 그 외 예외                          → 500 INTERNAL_ERROR

## 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

- JobSubmitRequest: `POST /v1/jobs` 요청 본문.
  - `provider` string, required: 요청 provider (예: hometax)
  - `action` string, required: 요청 action — provider 종속 enum
  - `account_link_id` string, nullable: 연동 계정 식별자 (선택). 생략 시 API 키 기반 자동 해결. 다중 인증서 환경에서만 명시.
  - `params` object, nullable: 액션별 파라미터 (선택). 평문 PII 직접 전송 금지 — encrypted_fields 사용.
  - `encrypted_fields` object, nullable: RSA-OAEP base64 암호문 필드 (선택). 평문 dict 저장 금지 — base64 형식 강제.

## Response `200`

같은 멱등키·같은 본문의 재생 - 그 작업의 **지금** 상태다.

- JobSubmitResponse: `POST /v1/jobs` 성공 응답 - `202 Accepted` 본문과 **1:1**. 칸은 여섯이다.
  - `job_id` string, required: `job_` + 26자 ULID.
  - `status` string, required: 새 접수면 `QUEUED`. 멱등 재생이면 **그 작업의 지금 상태**다 - 끝난 작업을 `QUEUED` 라고 하지 않는다(멱등 재호출 규칙).
  - `env_scope` string, required: 요청한 환경 그대로. `sandbox` · `real_test` · `production`.
  - `provider` string, required
  - `action` string, required
  - `submitted_at` string, nullable: KST ISO-8601. 접수 시각을 아직 모르면 없다(조립부가 None 을 싣는 갈래가 있다).

## Other responses

- `202`: 새 접수 - 작업이 `QUEUED` 로 들어갔다(정본 §4-1).
- `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)