{"openapi":"3.1.0","info":{"title":"VURITY Open API","description":"VURITY 셀러 데이터를 외부 시스템(OMS·ERP 등)에서 조회하고 처리하기 위한 API입니다.\n셀러가 파트너센터에서 발급한 API Key 하나로 인증하며, 그 키를 발급한 셀러의 데이터만 조회·변경할 수 있습니다.\n\n## 인증\n\n모든 요청에 `X-Api-Key` 헤더로 API Key를 실어 보냅니다.\n\n```\nX-Api-Key: vpk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n```\n\n- `vpk_live_`로 시작하는 키는 실서비스용, `vpk_test_`로 시작하는 키는 개발(dev) 환경용입니다.\n  환경이 맞지 않는 키를 보내면 인증에 실패합니다.\n- 키에는 기능별 권한(스코프)이 붙어 있습니다. 권한이 없는 API를 호출하면 403으로 거절됩니다.\n  주문 조회 `orders:read` · 주문 처리 `orders:write` · 클레임 조회 `claims:read` ·\n  클레임 처리 `claims:write` · 문의 조회 `qna:read` · 문의 답변 `qna:write`.\n- 키 발급·재발급 절차는 연동 가이드(별도 제공 문서)를 따릅니다.\n\n## 응답 형식\n\n모든 응답은 `meta`와 `data` 두 필드로 감싼 공통 형식으로 반환됩니다. 실제 결과는 `data` 안에 있습니다.\n\n```json\n{\n  \"meta\": { \"code\": 200, \"message\": \"OK\", \"error_code\": null, \"error_data\": null },\n  \"data\": { \"order_no\": \"VR20260826-0000001\" }\n}\n```\n\n실패 응답도 같은 형식이며, `data`는 `null`이고 `meta.error_code`에 아래 표의 고정 코드가 담깁니다.\n사람이 읽는 안내는 `meta.message`에 들어가므로, 분기 처리는 반드시 `meta.error_code`로 해주세요\n(메시지 문구는 예고 없이 다듬어질 수 있습니다).\n\n## 시각 표기\n\n- 요청의 시각 파라미터는 ISO 8601 형식으로 보냅니다. 예: `2026-08-26T00:00:00+09:00`\n- 오프셋을 생략하면(예: `2026-08-26T00:00:00`) **UTC로 해석**합니다. 한국 시각으로 조회하려면\n  `+09:00`을 반드시 붙여주세요.\n- 응답의 모든 시각은 UTC이며 `Z`로 끝나는 ISO 8601 문자열입니다(예: `2026-08-26T01:12:33.482910Z`).\n  한국 시각으로 보려면 9시간을 더하면 됩니다.\n- **URL 인코딩 주의**: 쿼리스트링의 `+`는 공백으로 해석됩니다. URL을 직접 조립한다면 `+09:00`의\n  `+`를 `%2B`로 인코딩하거나(`2026-08-26T00:00:00%2B09:00`), UTC 기준 `Z` 표기를 사용해주세요.\n  HTTP 클라이언트 라이브러리의 파라미터 기능을 쓰면 자동으로 인코딩됩니다.\n\n## 목록 조회와 페이지 넘김\n\n목록 API는 `{ \"list\": [...], \"next_cursor\": \"...\" }` 형태로 응답합니다.\n\n1. 첫 페이지는 `cursor` 없이 요청합니다.\n2. 응답의 `next_cursor` 값을 **그대로** 다음 요청의 `cursor` 파라미터에 넣습니다.\n3. `next_cursor`가 `null`이면 마지막 페이지입니다.\n\n`cursor`는 서버가 발급한 문자열입니다. 직접 만들거나 고쳐서 보내면 422(`INVALID_CURSOR`)로 거절됩니다.\n그 경우 `cursor` 없이 처음부터 다시 수집하면 복구됩니다. 총 건수(total)는 제공하지 않습니다.\n\n## 변경분만 주기적으로 가져오기(증분 수집)\n\n주문·클레임·문의 목록은 `updated_at_gte`/`updated_at_lte`로 \"이 시각 이후에 변경된 것\"만 가져오는 방식을\n권장합니다. 이때 중복 없이 딱 한 번씩만 받는 것은 보장되지 않으므로, 아래 방식으로 수집해주세요.\n\n- 수집 주기: 5분\n- 조회 구간: 마지막 수집 시각보다 **10분 앞선 시각**부터(구간을 겹쳐 조회 — 경계에서의 누락 방지)\n- 저장: 같은 건이 두 번 와도 문제없도록 주문번호 등 식별자 기준으로 덮어쓰기(upsert)\n\n## 처리 API 공통 규칙\n\n**결과가 같으면 성공입니다.** 처리 API는 \"이 주문/클레임을 이 상태로 만들어 달라\"는 요청으로 동작합니다.\n이미 요청한 상태라면 아무것도 바꾸지 않고 성공(200)으로 응답합니다. 응답의 `already_done`·`converged`\n필드로 \"이번에 바뀐 것인지, 원래 그 상태였는지\"를 구분할 수 있습니다.\n\n**`Idempotency-Key` 헤더가 필수입니다.** 모든 처리(POST) 요청에 요청마다 고유한 문자열(UUID 권장,\n200자 이하)을 담아 보내주세요.\n\n```\nIdempotency-Key: 6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31\n```\n\n- 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보냅니다. 서버는 저장해 둔 첫 결과를\n  그대로 다시 돌려주므로 이중 처리가 발생하지 않습니다.\n- 같은 키로 **내용이 다른** 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절됩니다.\n  새 작업에는 반드시 새 키를 써주세요.\n- 저장된 결과는 24시간 보관됩니다. 그 뒤 같은 키로 재시도하면 410(`IDEMPOTENCY_RESULT_EXPIRED`)입니다.\n\n**410(`IDEMPOTENCY_RESULT_EXPIRED`)을 받았을 때의 복구 절차** — 아래 3단계를 그대로 따라주세요.\n\n1. **같은 키로 재시도하지 않습니다.** 보관 기간이 지난 키라 몇 번을 보내도 계속 410입니다.\n2. **해당 리소스를 조회해 현재 상태를 확인합니다.** 주문이면 `GET /open/v1/orders/{order_no}`,\n   클레임이면 `GET /open/v1/claims/{claim_no}`로 지금 상태를 읽습니다.\n3. **이미 원하던 상태면 그 요청은 성공으로 처리**하고(재전송하지 않습니다), 아직 반영되지 않았으면\n   **새 `Idempotency-Key`를 발급해 다시 전송**합니다.\n\n## 호출 한도\n\n- 조회 API: 분당 60회\n- 처리 API: 분당 30회\n- 조회로 반환되는 행 수: 분당 3,000행\n\n초과하면 429로 응답하며 `Retry-After`(초) 헤더가 함께 옵니다. 그 시간만큼 기다린 뒤 재시도해주세요.\n응답의 `X-RateLimit-Limit`·`X-RateLimit-Remaining` 헤더로 남은 호출 수를 확인할 수 있습니다.\n\n## 오류 코드\n\n실패 응답의 `meta.error_code`에는 아래 고정 코드 중 하나가 담깁니다. 이 표는 서버 코드의\n카탈로그(`open_api/errors.py`)에서 **생성**되며, 실제로 발행되는 코드와 어긋나면 테스트가\n실패합니다 — 표에 없는 코드를 받는 일은 없습니다.\n\n`일괄` 열의 ●는 그 코드가 **일괄 송장 등록의 `data.failed[].error_code`에도** 실린다는 뜻입니다.\n일괄 처리는 주문 단위로 부분 성공하므로 그때 HTTP는 **200**입니다(개별 실패는 본문에만 나타납니다).\n`HTTP` 열이 `200`인 코드는 일괄 처리 본문에서만 나타나는 코드입니다.\n\n| HTTP | `error_code` | 일괄 | 의미와 대처 |\n|---|---|---|---|\n| 200 | `ORDER_BATCH_ERROR` | ● | 일괄 처리 중 그 주문에서 예상치 못한 오류가 났습니다. 다른 주문의 처리에는 영향이 없으며, 해당 주문만 잠시 후 다시 시도해주세요. |\n| 400 | `SHIPMENT_FIELDS_REQUIRED` | ● | 운송장번호가 비어 있거나 공백뿐입니다. 값을 채워 다시 보내주세요. (**택배사명**이 비어 있으면 그보다 앞선 422 `SHIPMENT_CARRIER_NOT_ALLOWED`로, 필드를 아예 보내지 않으면 422 `VALIDATION_ERROR`로 거절됩니다.) |\n| 400 | `SHIPMENT_INPUT_INVALID` | ● | 택배사명·운송장번호·물류대행사명에 저장할 수 없는 제어문자가 섞여 있습니다. |\n| 401 | `API_KEY_REQUIRED` |  | `X-Api-Key` 헤더가 없습니다. |\n| 401 | `INVALID_API_KEY` |  | 키가 잘못됐거나 폐기·만료됐습니다(환경이 다른 키도 같습니다). 셀러에게 키 재발급을 요청해주세요. |\n| 403 | `SCOPE_FORBIDDEN` |  | 키에 이 API의 권한(스코프)이 없습니다. 셀러가 권한을 포함해 키를 재발급해야 합니다. |\n| 404 | `ORDER_NOT_FOUND` | ● | 주문이 없거나 이 키의 셀러 주문이 아닙니다(결제 전 주문도 조회되지 않습니다). |\n| 404 | `CLAIM_NOT_FOUND` |  | 클레임이 없거나 이 키의 셀러 클레임이 아닙니다. |\n| 404 | `QNA_NOT_FOUND` |  | 문의가 없거나 이 키의 셀러 상품 문의가 아닙니다(`qna_id` 형식 오류도 같습니다). |\n| 404 | `ORDER_ITEM_NOT_FOUND` | ● | `item_ids`가 그 주문의 귀사 상품이 아닙니다(없는 ID·타 주문·타 셀러·형식 오류가 모두 같은 응답입니다). |\n| 409 | `IDEMPOTENCY_KEY_REUSED` |  | 같은 `Idempotency-Key`로 다른 내용을 보냈습니다. 새 작업에는 새 키를 써주세요. |\n| 409 | `IDEMPOTENCY_IN_PROGRESS` |  | 같은 키의 요청이 처리 중입니다. 잠시 후 같은 키로 재시도해주세요. |\n| 409 | `IDEMPOTENCY_UNRESOLVED` |  | 요청의 처리 결과를 확정하지 못했습니다(클레임 처리는 현재 상태에서 그 액션을 확정할 수 없다는 뜻입니다). 조회로 현재 상태를 확인한 뒤 재시도해주세요. |\n| 409 | `ORDER_ITEM_NOT_PREPARABLE` |  | 발주확인할 수 없는 상태의 상품입니다. |\n| 409 | `ORDER_ITEM_NOT_SHIPPABLE` | ● | 발송 처리할 수 없는 상태의 상품입니다. |\n| 409 | `ORDER_ITEM_NOT_DELIVERABLE` |  | 배송완료 처리할 수 없는 상태의 상품입니다. |\n| 409 | `ORDER_ITEM_HAS_ACTIVE_CLAIM` | ● | 취소·반품·교환이 진행 중인 상품이라 처리할 수 없습니다. |\n| 409 | `SHIPMENT_STATE_CONFLICT` | ● | 이미 **다른 송장**으로 발송 처리된 상품입니다(같은 송장을 다시 보내면 성공입니다). 주문 조회로 등록된 송장을 확인해주세요. |\n| 409 | `EXCHANGE_ITEM_NOT_PREPARABLE` |  | 교환으로 생성된 상품은 교환 신청이 재출고 단계에 오기 전에는 발주확인할 수 없습니다. |\n| 409 | `EXCHANGE_ITEM_NOT_RESHIPPING` | ● | 교환으로 생성된 상품은 교환 신청이 재출고 단계일 때만 발송 처리할 수 있습니다. |\n| 409 | `CLAIM_NOT_APPROVABLE` |  | 승인할 수 없는 상태의 클레임입니다. 조회 응답의 `available_actions`를 확인해주세요. |\n| 409 | `CLAIM_NOT_REJECTABLE` |  | 거부할 수 없는 상태의 클레임입니다. 조회 응답의 `available_actions`를 확인해주세요. |\n| 409 | `CLAIM_NOT_COLLECTABLE` |  | 수거 등록할 수 없는 상태의 클레임입니다. 조회 응답의 `available_actions`를 확인해주세요. |\n| 409 | `CLAIM_NOT_COLLECT_DONE` |  | 수거 완료 처리할 수 없는 상태의 클레임입니다. 조회 응답의 `available_actions`를 확인해주세요. |\n| 409 | `CLAIM_NOT_INSPECTABLE` |  | 검수 결과를 등록할 수 없는 상태의 클레임입니다. 조회 응답의 `available_actions`를 확인해주세요. |\n| 409 | `CLAIM_NOT_RESHIPPABLE` |  | 재출고 등록할 수 없는 상태의 클레임입니다. 조회 응답의 `available_actions`를 확인해주세요. |\n| 409 | `EXCHANGE_ITEM_SHIP_FAILED` |  | 교환 재출고를 등록했지만 새로 만들어진 교환 상품의 출고 처리가 확정되지 않았습니다. 클레임 조회로 현재 상태를 확인한 뒤 다시 시도해주세요. |\n| 409 | `QNA_ALREADY_ANSWERED` |  | 이미 다른 내용의 답변이 등록돼 있습니다(같은 내용을 다시 보내면 성공입니다). 답변 수정은 파트너센터에서만 가능합니다. |\n| 409 | `QNA_ANSWER_UNRESOLVED` |  | 문의 답변 결과를 확정하지 못했습니다(답변이 취소된 찰나). 잠시 후 다시 시도해주세요. |\n| 410 | `IDEMPOTENCY_RESULT_EXPIRED` |  | 24시간이 지나 저장된 결과가 삭제됐습니다. 조회 API로 현재 상태를 확인해주세요. |\n| 422 | `VALIDATION_ERROR` |  | 요청 본문·쿼리의 형식이 계약과 다릅니다(필드 누락·타입 불일치·빈 문자열·길이 초과 등). 어느 필드가 왜 틀렸는지는 `meta.error_data.errors`에 담깁니다. |\n| 422 | `IDEMPOTENCY_KEY_REQUIRED` |  | 처리 API에 `Idempotency-Key` 헤더가 없거나 공백뿐입니다. |\n| 422 | `IDEMPOTENCY_KEY_TOO_LONG` |  | `Idempotency-Key`가 200자를 넘었습니다. |\n| 422 | `INVALID_CURSOR` |  | `cursor` 값이 잘못됐습니다. `cursor` 없이 처음부터 다시 수집해주세요. |\n| 422 | `STATUS_CHANGED_FILTER_INCOMPLETE` |  | `status_changed_to`와 시각 필터는 **함께** 보내야 합니다(한쪽만은 거절). |\n| 422 | `STATUS_CHANGED_RANGE_INVALID` |  | `status_changed_at_gte`가 `status_changed_at_lte`보다 뒤입니다. |\n| 422 | `SHIPMENT_CARRIER_NOT_ALLOWED` | ● | 지원하지 않는 택배사명입니다(빈 값·공백뿐인 값도 여기에 해당합니다). 허용 목록의 표기를 그대로 보내주세요. 일괄 처리에서는 HTTP 200 응답의 `failed[]`에 담깁니다. |\n| 429 | `RATE_LIMITED` |  | 호출 한도 또는 행수 예산을 넘었습니다. `Retry-After` 초만큼 기다린 뒤 재시도해주세요. |\n| 503 | `RATE_LIMIT_UNAVAILABLE` |  | 한도를 확인할 수 없어 요청을 처리하지 않았습니다(서버 일시 장애). 잠시 후 재시도해주세요. |\n","version":"1.0.0"},"paths":{"/open/v1/orders":{"get":{"tags":["주문"],"summary":"주문 목록 조회","description":"결제가 완료된 주문을 조건에 맞춰 최신 변경 순으로 가져옵니다. 결제 전 주문은 조회되지 않으며, 각 주문에는 요청한 API Key의 셀러 상품만 담깁니다.\n\n새 주문과 변경분을 주기적으로 수집하려면 `updated_at_gte`로 구간을 지정해 반복 호출해주세요.\n### 수집 루프\n\n1. 첫 요청은 `cursor` 없이 보냅니다.\n2. 응답의 `data.next_cursor`를 **같은 필터 조건을 유지한 채** 다음 요청의 `cursor`로 그대로 전달합니다.\n3. `next_cursor`가 `null`이면 이번 회차 수집이 끝난 것입니다.\n4. 다음 회차는 5분 뒤에 시작하되 `updated_at_gte`를 **직전 수집 시각보다 10분 앞선 값**으로 두고\n   커서 없이 다시 1번부터 진행합니다. 구간을 겹쳐 조회하므로 같은 건이 두 번 올 수 있습니다 —\n   식별자 기준으로 덮어쓰기(upsert)하면 중복이 문제가 되지 않습니다.","operationId":"list_orders_open_v1_orders_get","security":[{"X-Api-Key":[]}],"parameters":[{"name":"paid_at_gte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"이 시각 이후(같은 시각 포함)에 결제된 주문만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-26T00:00:00+09:00"],"title":"Paid At Gte"},"description":"이 시각 이후(같은 시각 포함)에 결제된 주문만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"paid_at_lte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"이 시각 이전(같은 시각 포함)에 결제된 주문만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-27T00:00:00+09:00"],"title":"Paid At Lte"},"description":"이 시각 이전(같은 시각 포함)에 결제된 주문만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"updated_at_gte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"이 시각 이후(같은 시각 포함)에 변경된 주문만 가져옵니다. 변경분 수집의 기준이 되는 필터입니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-26T09:00:00+09:00"],"title":"Updated At Gte"},"description":"이 시각 이후(같은 시각 포함)에 변경된 주문만 가져옵니다. 변경분 수집의 기준이 되는 필터입니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"updated_at_lte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"이 시각 이전(같은 시각 포함)에 변경된 주문만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-26T09:10:00+09:00"],"title":"Updated At Lte"},"description":"이 시각 이전(같은 시각 포함)에 변경된 주문만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"order_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"주문 전체 상태가 정확히 이 값인 주문만 가져옵니다. `paid` · `preparing` · `shipping` · `delivered` · `confirmed` · `partially_claimed` · `canceled` 중 하나를 보냅니다.","examples":["paid"],"title":"Order Status"},"description":"주문 전체 상태가 정확히 이 값인 주문만 가져옵니다. `paid` · `preparing` · `shipping` · `delivered` · `confirmed` · `partially_claimed` · `canceled` 중 하나를 보냅니다."},{"name":"item_status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"귀사 상품 중 이 상태인 것이 하나라도 있는 주문만 가져옵니다. 발송 대상만 뽑을 때처럼 상품 단위로 걸러야 할 때 사용합니다. `paid` · `preparing` · `shipping` · `delivered` · `confirmed` · `canceled` · `returned` · `exchanged` 중 하나를 보냅니다.","examples":["preparing"],"title":"Item Status"},"description":"귀사 상품 중 이 상태인 것이 하나라도 있는 주문만 가져옵니다. 발송 대상만 뽑을 때처럼 상품 단위로 걸러야 할 때 사용합니다. `paid` · `preparing` · `shipping` · `delivered` · `confirmed` · `canceled` · `returned` · `exchanged` 중 하나를 보냅니다."},{"name":"order_no","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"주문번호가 정확히 일치하는 주문만 가져옵니다.","examples":["VR20260826-0000001"],"title":"Order No"},"description":"주문번호가 정확히 일치하는 주문만 가져옵니다."},{"name":"status_changed_to","in":"query","required":false,"schema":{"anyOf":[{"enum":["paid","preparing","shipping","delivered","confirmed","canceled","returned","exchanged"],"type":"string"},{"type":"null"}],"description":"귀사 상품이 이 상태로 **전환된 이력이 있는** 주문만 가져옵니다. `status_changed_at_gte`/`status_changed_at_lte`와 함께 쓰면 \"어제 발송한 주문\"처럼 상태가 바뀐 시점 기준으로 조회할 수 있습니다. 현재 상태가 아니라 거쳐 간 이력을 보므로, 이미 다음 단계로 넘어간 주문도 결과에 포함됩니다. `status_changed_at_gte`/`status_changed_at_lte` 중 최소 하나와 **반드시 함께** 보내야 하며, 단독으로 보내면 422(`STATUS_CHANGED_FILTER_INCOMPLETE`)입니다.","examples":["shipping"],"title":"Status Changed To"},"description":"귀사 상품이 이 상태로 **전환된 이력이 있는** 주문만 가져옵니다. `status_changed_at_gte`/`status_changed_at_lte`와 함께 쓰면 \"어제 발송한 주문\"처럼 상태가 바뀐 시점 기준으로 조회할 수 있습니다. 현재 상태가 아니라 거쳐 간 이력을 보므로, 이미 다음 단계로 넘어간 주문도 결과에 포함됩니다. `status_changed_at_gte`/`status_changed_at_lte` 중 최소 하나와 **반드시 함께** 보내야 하며, 단독으로 보내면 422(`STATUS_CHANGED_FILTER_INCOMPLETE`)입니다."},{"name":"status_changed_at_gte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"상태 전환이 이 시각 이후(같은 시각 포함)에 일어난 주문만 가져옵니다. `status_changed_to` 없이 단독으로 보내면 422(`STATUS_CHANGED_FILTER_INCOMPLETE`)입니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-26T00:00:00+09:00"],"title":"Status Changed At Gte"},"description":"상태 전환이 이 시각 이후(같은 시각 포함)에 일어난 주문만 가져옵니다. `status_changed_to` 없이 단독으로 보내면 422(`STATUS_CHANGED_FILTER_INCOMPLETE`)입니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"status_changed_at_lte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"상태 전환이 이 시각 이전(같은 시각 포함)에 일어난 주문만 가져옵니다. `status_changed_to`와 함께 보내야 합니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-27T00:00:00+09:00"],"title":"Status Changed At Lte"},"description":"상태 전환이 이 시각 이전(같은 시각 포함)에 일어난 주문만 가져옵니다. `status_changed_to`와 함께 보내야 합니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"한 페이지에 받을 최대 건수입니다. 1 이상 100 이하이며, 생략하면 50건입니다.","examples":[50],"default":50,"title":"Limit"},"description":"한 페이지에 받을 최대 건수입니다. 1 이상 100 이하이며, 생략하면 50건입니다."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"페이지 넘김 토큰입니다. 첫 요청에는 보내지 않습니다. 응답의 `data.next_cursor` 값을 같은 필터 조건을 유지한 채 다음 요청의 `cursor`로 그대로 전달하면 다음 페이지를 받습니다. 서버가 발급한 값만 유효하며 직접 생성·수정하면 422(`INVALID_CURSOR`)로 거부됩니다.","examples":["eyJtIjoiMjAyNi0wOC0yNlQwMjo0MTowNy45MTMyMDQrMDA6MDAiLCJwIjoiLi4uIiwidiI6MSwidyI6Ii4uLiJ9"],"title":"Cursor"},"description":"페이지 넘김 토큰입니다. 첫 요청에는 보내지 않습니다. 응답의 `data.next_cursor` 값을 같은 필터 조건을 유지한 채 다음 요청의 `cursor`로 그대로 전달하면 다음 페이지를 받습니다. 서버가 발급한 값만 유효하며 직접 생성·수정하면 422(`INVALID_CURSOR`)로 거부됩니다."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenCursorPage_OpenOrderOut__"},"example":{"meta":{"code":200,"message":"OK"},"data":{"list":[{"order_no":"VR20260826-0000001","order_status":"paid","paid_at":"2026-08-26T01:12:33.482910Z","updated_at":"2026-08-26T01:12:33.482910Z","currency":"KRW","seller_items_amount":54000,"seller_discount_amount":5400,"seller_point_used_amount":1000,"seller_paid_amount":47600,"seller_shipping_fee_base":3000,"seller_shipping_fee_paid":3000,"orderer_name":"김뷰리","orderer_phone":"01012345678","recipient_name":"김뷰리","recipient_phone":"01012345678","zipcode":"06236","address1":"서울특별시 강남구 테헤란로 123","address2":"5층 501호","ship_memo":"부재 시 경비실에 맡겨 주세요","items":[{"item_code":"VR20260826-0000001-01","item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품","quantity":2,"list_price":32000,"unit_price":27000,"line_amount":54000,"discount_amount":5400,"line_paid_amount":47600,"item_status":"paid","is_exchange":false,"has_active_claim":false}]},{"order_no":"VR20260826-0000002","order_status":"preparing","paid_at":"2026-08-26T02:05:41.220118Z","updated_at":"2026-08-26T02:41:07.913204Z","currency":"KRW","seller_items_amount":27000,"seller_discount_amount":0,"seller_point_used_amount":0,"seller_paid_amount":27000,"seller_shipping_fee_base":0,"seller_shipping_fee_paid":0,"orderer_name":"이하늘","orderer_phone":"01098765432","recipient_name":"이하늘","recipient_phone":"01098765432","zipcode":"13529","address1":"경기도 성남시 분당구 판교역로 235","items":[{"item_code":"VR20260826-0000002-01","item_id":"5a1c2d33-8e47-4b90-b6f2-1d0e9a7c4b58","product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품","quantity":1,"list_price":32000,"unit_price":27000,"line_amount":27000,"discount_amount":0,"line_paid_amount":27000,"item_status":"preparing","is_exchange":false,"has_active_claim":false}]}],"next_cursor":"eyJtIjoiMjAyNi0wOC0yNlQwMjo0MTowNy45MTMyMDQrMDA6MDAiLCJwIjoiLi4uIiwidiI6MSwidyI6Ii4uLiJ9"}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"422":{"description":"커서 또는 필터 조합이 잘못됐습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"커서가 올바르지 않습니다. 커서 없이 처음부터 다시 수집해 주세요.","error_code":"INVALID_CURSOR"}}}}}}}},"/open/v1/orders/{order_no}":{"get":{"tags":["주문"],"summary":"주문 상세 조회","description":"주문번호로 주문 1건을 가져옵니다. 응답 형식은 목록 조회의 각 항목과 같습니다. 다른 셀러의 주문이거나 아직 결제되지 않은 주문이면 404(`ORDER_NOT_FOUND`)로 응답합니다.","operationId":"get_order_open_v1_orders__order_no__get","security":[{"X-Api-Key":[]}],"parameters":[{"name":"order_no","in":"path","required":true,"schema":{"type":"string","description":"조회할 주문번호입니다.","examples":["VR20260826-0000001"],"title":"Order No"},"description":"조회할 주문번호입니다."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenOrderOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"order_no":"VR20260826-0000001","order_status":"paid","paid_at":"2026-08-26T01:12:33.482910Z","updated_at":"2026-08-26T01:12:33.482910Z","currency":"KRW","seller_items_amount":54000,"seller_discount_amount":5400,"seller_point_used_amount":1000,"seller_paid_amount":47600,"seller_shipping_fee_base":3000,"seller_shipping_fee_paid":3000,"orderer_name":"김뷰리","orderer_phone":"01012345678","recipient_name":"김뷰리","recipient_phone":"01012345678","zipcode":"06236","address1":"서울특별시 강남구 테헤란로 123","address2":"5층 501호","ship_memo":"부재 시 경비실에 맡겨 주세요","items":[{"item_code":"VR20260826-0000001-01","item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품","quantity":2,"list_price":32000,"unit_price":27000,"line_amount":54000,"discount_amount":5400,"line_paid_amount":47600,"item_status":"paid","is_exchange":false,"has_active_claim":false}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"주문이 없거나 이 API Key의 셀러 주문이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"주문을 찾을 수 없습니다.","error_code":"ORDER_NOT_FOUND"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/open/v1/claims":{"get":{"tags":["클레임"],"summary":"클레임 목록 조회","description":"귀사 상품에 접수된 취소·반품·교환 신청을 최신 변경 순으로 가져옵니다. 각 신청에 지금 어떤 처리를 호출할 수 있는지는 응답의 `available_actions`가 알려 줍니다.\n\n새 신청과 진행 상황을 주기적으로 수집하려면 `updated_at_gte`로 구간을 지정해 반복 호출해주세요.\n### 수집 루프\n\n1. 첫 요청은 `cursor` 없이 보냅니다.\n2. 응답의 `data.next_cursor`를 **같은 필터 조건을 유지한 채** 다음 요청의 `cursor`로 그대로 전달합니다.\n3. `next_cursor`가 `null`이면 이번 회차 수집이 끝난 것입니다.\n4. 다음 회차는 5분 뒤에 시작하되 `updated_at_gte`를 **직전 수집 시각보다 10분 앞선 값**으로 두고\n   커서 없이 다시 1번부터 진행합니다. 구간을 겹쳐 조회하므로 같은 건이 두 번 올 수 있습니다 —\n   식별자 기준으로 덮어쓰기(upsert)하면 중복이 문제가 되지 않습니다.","operationId":"list_claims_open_v1_claims_get","security":[{"X-Api-Key":[]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"신청 종류로 거릅니다. `cancel`(취소) · `return`(반품) · `exchange`(교환) 중 하나입니다.","examples":["return"],"title":"Type"},"description":"신청 종류로 거릅니다. `cancel`(취소) · `return`(반품) · `exchange`(교환) 중 하나입니다."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"진행 상태가 정확히 이 값인 신청만 가져옵니다. 처리 대기 건만 뽑으려면 `requested`를, 검수 대기 건만 뽑으려면 `collected`를 보냅니다.","examples":["requested"],"title":"Status"},"description":"진행 상태가 정확히 이 값인 신청만 가져옵니다. 처리 대기 건만 뽑으려면 `requested`를, 검수 대기 건만 뽑으려면 `collected`를 보냅니다."},{"name":"requested_at_gte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"이 시각 이후(같은 시각 포함)에 신청된 건만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-26T00:00:00+09:00"],"title":"Requested At Gte"},"description":"이 시각 이후(같은 시각 포함)에 신청된 건만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"requested_at_lte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"이 시각 이전(같은 시각 포함)에 신청된 건만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-28T00:00:00+09:00"],"title":"Requested At Lte"},"description":"이 시각 이전(같은 시각 포함)에 신청된 건만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"updated_at_gte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"이 시각 이후(같은 시각 포함)에 변경된 건만 가져옵니다. 변경분 수집의 기준이 되는 필터입니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-28T09:00:00+09:00"],"title":"Updated At Gte"},"description":"이 시각 이후(같은 시각 포함)에 변경된 건만 가져옵니다. 변경분 수집의 기준이 되는 필터입니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"updated_at_lte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"이 시각 이전(같은 시각 포함)에 변경된 건만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-28T09:10:00+09:00"],"title":"Updated At Lte"},"description":"이 시각 이전(같은 시각 포함)에 변경된 건만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"한 페이지에 받을 최대 건수입니다. 1 이상 100 이하이며, 생략하면 50건입니다.","examples":[50],"default":50,"title":"Limit"},"description":"한 페이지에 받을 최대 건수입니다. 1 이상 100 이하이며, 생략하면 50건입니다."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"페이지 넘김 토큰입니다. 첫 요청에는 보내지 않습니다. 응답의 `data.next_cursor` 값을 같은 필터 조건을 유지한 채 다음 요청의 `cursor`로 그대로 전달하면 다음 페이지를 받습니다. 서버가 발급한 값만 유효하며 직접 생성·수정하면 422(`INVALID_CURSOR`)로 거부됩니다.","examples":["eyJtIjoiMjAyNi0wOC0yNlQwMjo0MTowNy45MTMyMDQrMDA6MDAiLCJwIjoiLi4uIiwidiI6MSwidyI6Ii4uLiJ9"],"title":"Cursor"},"description":"페이지 넘김 토큰입니다. 첫 요청에는 보내지 않습니다. 응답의 `data.next_cursor` 값을 같은 필터 조건을 유지한 채 다음 요청의 `cursor`로 그대로 전달하면 다음 페이지를 받습니다. 서버가 발급한 값만 유효하며 직접 생성·수정하면 422(`INVALID_CURSOR`)로 거부됩니다."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenCursorPage_OpenClaimOut__"},"example":{"meta":{"code":200,"message":"OK"},"data":{"list":[{"claim_no":"CL260826-000123","order_no":"VR20260826-0000001","type":"return","status":"requested","available_actions":["approve","reject"],"fault":"buyer","reason_code":"change_of_mind","refund_amount":47600,"claim_shipping_fee":3000,"price_difference":0,"requested_at":"2026-08-27T04:10:22.118400Z","updated_at":"2026-08-27T04:10:22.118400Z","items":[{"item_code":"VR20260826-0000001-01","item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","quantity":2,"product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품"}]}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"422":{"description":"커서가 잘못됐습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"커서가 올바르지 않습니다. 커서 없이 처음부터 다시 수집해 주세요.","error_code":"INVALID_CURSOR"}}}}}}}},"/open/v1/claims/{claim_no}":{"get":{"tags":["클레임"],"summary":"클레임 상세 조회","description":"클레임번호로 신청 1건을 가져옵니다. 응답 형식은 목록 조회의 각 항목, 그리고 처리 API의 응답과 모두 같습니다.","operationId":"get_claim_open_v1_claims__claim_no__get","security":[{"X-Api-Key":[]}],"parameters":[{"name":"claim_no","in":"path","required":true,"schema":{"type":"string","description":"조회할 클레임번호입니다.","examples":["CL260826-000123"],"title":"Claim No"},"description":"조회할 클레임번호입니다."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenClaimOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"claim_no":"CL260826-000123","order_no":"VR20260826-0000001","type":"return","status":"requested","available_actions":["approve","reject"],"fault":"buyer","reason_code":"change_of_mind","refund_amount":47600,"claim_shipping_fee":3000,"price_difference":0,"requested_at":"2026-08-27T04:10:22.118400Z","updated_at":"2026-08-27T04:10:22.118400Z","items":[{"item_code":"VR20260826-0000001-01","item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","quantity":2,"product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품"}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"클레임이 없거나 이 API Key의 셀러 클레임이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"클레임을 찾을 수 없습니다.","error_code":"CLAIM_NOT_FOUND"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/open/v1/orders/batch/shipment":{"post":{"tags":["주문"],"summary":"송장 일괄 등록(여러 주문 발송 처리)","description":"여러 주문의 송장을 한 번에 등록하고 해당 상품을 배송중으로 바꿉니다. 주문마다 택배사·운송장번호를 각각 지정합니다.\n\n**항목 단위로 각각 처리되며 일부가 실패해도 HTTP 200으로 응답합니다.** 상태 코드가 아니라 응답의 `failed` 목록을 확인해 실패 건을 재처리해주세요. 이미 같은 송장으로 발송 처리된 상품은 다시 바꾸지 않고 성공으로 집계됩니다. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"batch_shipment_open_v1_orders_batch_shipment_post","security":[{"X-Api-Key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenBatchShipmentRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_BatchTransitionResult_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"succeeded":["0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b"],"failed":[{"order_no":"VR20260826-0000002","order_item_public_ids":["5a1c2d33-8e47-4b90-b6f2-1d0e9a7c4b58"],"error_code":"ORDER_ITEM_NOT_SHIPPABLE","message":"발송 처리할 수 없는 상태의 상품입니다."}],"summary":{"succeeded":1,"failed":1}}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"409":{"description":"같은 Idempotency-Key로 다른 내용을 보냈습니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"같은 Idempotency-Key로 다른 요청을 보낼 수 없습니다.","error_code":"IDEMPOTENCY_KEY_REUSED"}}}}},"422":{"description":"허용되지 않은 택배사명입니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"허용되지 않은 택배사입니다. 목록에서 선택해주세요.","error_code":"SHIPMENT_CARRIER_NOT_ALLOWED"}}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}]}},"/open/v1/orders/{order_no}/preparation":{"post":{"tags":["주문"],"summary":"발주확인(상품준비중으로 전환)","description":"주문을 접수 처리해 지정한 상품을 상품준비중(`preparing`)으로 바꿉니다. 결제완료(`paid`) 상태의 상품에만 호출할 수 있습니다.\n\n이미 요청한 상태라면 아무것도 바꾸지 않고 성공(200)으로 응답합니다. 응답 항목의 `already_done`이\n`true`면 이번 호출 전에 이미 그 상태였다는 뜻입니다. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"transition_preparation_open_v1_orders__order_no__preparation_post","security":[{"X-Api-Key":[]}],"parameters":[{"name":"order_no","in":"path","required":true,"schema":{"type":"string","description":"처리할 주문번호입니다.","examples":["VR20260826-0000001"],"title":"Order No"},"description":"처리할 주문번호입니다."},{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenTransitionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenTransitionResultOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"order_no":"VR20260826-0000001","order_status":"preparing","updated_at":"2026-08-26T03:40:52.117903Z","items":[{"item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","item_code":"VR20260826-0000001-01","item_status":"preparing","already_done":false}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"주문이 없거나 이 API Key의 셀러 주문이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"주문을 찾을 수 없습니다.","error_code":"ORDER_NOT_FOUND"}}}}},"409":{"description":"발주확인할 수 없는 상태의 상품입니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"발주확인할 수 없는 상태의 상품입니다.","error_code":"ORDER_ITEM_NOT_PREPARABLE"}}}}},"422":{"description":"Idempotency-Key 헤더가 없습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"Idempotency-Key 헤더가 필요합니다.","error_code":"IDEMPOTENCY_KEY_REQUIRED"}}}}}}}},"/open/v1/orders/{order_no}/shipment":{"post":{"tags":["주문"],"summary":"송장 등록(배송중으로 전환)","description":"송장 정보를 등록하고 지정한 상품을 배송중(`shipping`)으로 바꿉니다. 상품준비중(`preparing`) 상태의 상품에만 호출할 수 있습니다.\n\n이미 **같은 송장**으로 발송 처리된 상품이면 아무것도 바꾸지 않고 성공으로 응답합니다(`already_done`이 `true`). 이미 발송된 상품에 **다른 송장**을 보내면 409로 거절되므로, 송장을 바꾸려면 파트너센터에서 수정해주세요. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"transition_shipment_open_v1_orders__order_no__shipment_post","security":[{"X-Api-Key":[]}],"parameters":[{"name":"order_no","in":"path","required":true,"schema":{"type":"string","description":"처리할 주문번호입니다.","examples":["VR20260826-0000001"],"title":"Order No"},"description":"처리할 주문번호입니다."},{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenShipmentRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenTransitionResultOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"order_no":"VR20260826-0000001","order_status":"shipping","updated_at":"2026-08-26T05:22:10.884231Z","items":[{"item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","item_code":"VR20260826-0000001-01","item_status":"shipping","tracking_no":"123456789012","carrier_name":"CJ대한통운","already_done":false}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"주문이 없거나 이 API Key의 셀러 주문이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"주문을 찾을 수 없습니다.","error_code":"ORDER_NOT_FOUND"}}}}},"409":{"description":"발송 처리할 수 없는 상태이거나 이미 다른 송장이 등록돼 있습니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"발송 처리할 수 없는 상태의 상품입니다.","error_code":"ORDER_ITEM_NOT_SHIPPABLE"}}}}},"422":{"description":"허용되지 않은 택배사명입니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"허용되지 않은 택배사입니다. 목록에서 선택해주세요.","error_code":"SHIPMENT_CARRIER_NOT_ALLOWED"}}}}}}}},"/open/v1/orders/{order_no}/delivery":{"post":{"tags":["주문"],"summary":"배송완료 처리","description":"지정한 상품을 배송완료(`delivered`)로 바꿉니다. 배송중(`shipping`) 상태의 상품에만 호출할 수 있습니다. 배송완료 시점부터 고객의 반품·교환 신청 기간이 시작됩니다.\n\n이미 요청한 상태라면 아무것도 바꾸지 않고 성공(200)으로 응답합니다. 응답 항목의 `already_done`이\n`true`면 이번 호출 전에 이미 그 상태였다는 뜻입니다. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"transition_delivery_open_v1_orders__order_no__delivery_post","security":[{"X-Api-Key":[]}],"parameters":[{"name":"order_no","in":"path","required":true,"schema":{"type":"string","description":"처리할 주문번호입니다.","examples":["VR20260826-0000001"],"title":"Order No"},"description":"처리할 주문번호입니다."},{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenTransitionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenTransitionResultOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"order_no":"VR20260826-0000001","order_status":"delivered","updated_at":"2026-08-27T02:40:18.220145Z","items":[{"item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","item_code":"VR20260826-0000001-01","item_status":"delivered","tracking_no":"123456789012","carrier_name":"CJ대한통운","already_done":false}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"주문이 없거나 이 API Key의 셀러 주문이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"주문을 찾을 수 없습니다.","error_code":"ORDER_NOT_FOUND"}}}}},"409":{"description":"배송완료 처리할 수 없는 상태의 상품입니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"배송완료 처리할 수 없는 상태의 상품입니다.","error_code":"ORDER_ITEM_NOT_DELIVERABLE"}}}}},"422":{"description":"Idempotency-Key 헤더가 없습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"Idempotency-Key 헤더가 필요합니다.","error_code":"IDEMPOTENCY_KEY_REQUIRED"}}}}}}}},"/open/v1/claims/{claim_no}/approve":{"post":{"tags":["클레임"],"summary":"클레임 승인","description":"고객의 취소·반품·교환 신청을 승인합니다. 접수 대기(`requested`) 상태에서만 호출할 수 있습니다.\n\n취소를 승인하면 환불 절차가 VURITY 내부에서 자동으로 진행됩니다. 반품·교환을 승인하면 다음 단계는 수거 등록(`pickup`)입니다. 이미 승인된 신청에 다시 호출하면 아무것도 바꾸지 않고 성공으로 응답합니다. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"approve_claim_open_v1_claims__claim_no__approve_post","security":[{"X-Api-Key":[]}],"parameters":[{"name":"claim_no","in":"path","required":true,"schema":{"type":"string","description":"처리할 클레임번호입니다.","examples":["CL260826-000123"],"title":"Claim No"},"description":"처리할 클레임번호입니다."},{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenClaimOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"claim_no":"CL260826-000123","order_no":"VR20260826-0000001","type":"return","status":"approved","available_actions":["pickup"],"fault":"buyer","reason_code":"change_of_mind","refund_amount":47600,"claim_shipping_fee":3000,"price_difference":0,"requested_at":"2026-08-27T04:10:22.118400Z","updated_at":"2026-08-27T05:02:44.910233Z","items":[{"item_code":"VR20260826-0000001-01","item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","quantity":2,"product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품"}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"클레임이 없거나 이 API Key의 셀러 클레임이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"클레임을 찾을 수 없습니다.","error_code":"CLAIM_NOT_FOUND"}}}}},"409":{"description":"승인할 수 없는 상태의 클레임입니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"승인할 수 없는 상태의 클레임입니다.","error_code":"CLAIM_NOT_APPROVABLE"}}}}},"422":{"description":"Idempotency-Key 헤더가 없습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"Idempotency-Key 헤더가 필요합니다.","error_code":"IDEMPOTENCY_KEY_REQUIRED"}}}}}}}},"/open/v1/claims/{claim_no}/reject":{"post":{"tags":["클레임"],"summary":"클레임 거부","description":"고객의 신청을 거부합니다. 사유(`memo`)가 필수입니다. 접수 대기(`requested`) 상태에서, 그리고 반품·교환의 경우 검수 불합격 처리를 위해 검수중(`inspecting`) 상태에서도 호출할 수 있습니다.\n\n이미 거부된 신청에 다시 호출하면 사유 문구가 달라도 성공으로 응답하며, 저장된 사유는 처음 성공한 요청의 값이 유지됩니다. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"reject_claim_open_v1_claims__claim_no__reject_post","security":[{"X-Api-Key":[]}],"parameters":[{"name":"claim_no","in":"path","required":true,"schema":{"type":"string","description":"처리할 클레임번호입니다.","examples":["CL260826-000123"],"title":"Claim No"},"description":"처리할 클레임번호입니다."},{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenClaimRejectRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenClaimOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"claim_no":"CL260826-000123","order_no":"VR20260826-0000001","type":"return","status":"rejected","available_actions":[],"fault":"buyer","reason_code":"change_of_mind","refund_amount":47600,"claim_shipping_fee":3000,"price_difference":0,"requested_at":"2026-08-27T04:10:22.118400Z","completed_at":"2026-08-27T05:02:44.910233Z","updated_at":"2026-08-27T05:02:44.910233Z","items":[{"item_code":"VR20260826-0000001-01","item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","quantity":2,"product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품"}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"클레임이 없거나 이 API Key의 셀러 클레임이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"클레임을 찾을 수 없습니다.","error_code":"CLAIM_NOT_FOUND"}}}}},"409":{"description":"거부할 수 없는 상태의 클레임입니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"거부할 수 없는 상태의 클레임입니다.","error_code":"CLAIM_NOT_REJECTABLE"}}}}},"422":{"description":"Idempotency-Key 헤더가 없습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"Idempotency-Key 헤더가 필요합니다.","error_code":"IDEMPOTENCY_KEY_REQUIRED"}}}}}}}},"/open/v1/claims/{claim_no}/pickup":{"post":{"tags":["클레임"],"summary":"수거 등록(반품·교환 상품 회수)","description":"반품·교환 상품을 회수할 택배사와 운송장번호를 등록하고 상태를 수거중(`collecting`)으로 바꿉니다. 승인(`approved`) 상태에서만 호출할 수 있으며, 취소 신청에는 사용하지 않습니다.\n\n이미 같은 송장으로 수거 등록된 신청이면 아무것도 바꾸지 않고 성공으로 응답합니다. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"schedule_pickup_open_v1_claims__claim_no__pickup_post","security":[{"X-Api-Key":[]}],"parameters":[{"name":"claim_no","in":"path","required":true,"schema":{"type":"string","description":"처리할 클레임번호입니다.","examples":["CL260826-000123"],"title":"Claim No"},"description":"처리할 클레임번호입니다."},{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenClaimShipmentRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenClaimOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"claim_no":"CL260826-000123","order_no":"VR20260826-0000001","type":"return","status":"collecting","available_actions":["collect-done"],"fault":"buyer","reason_code":"change_of_mind","refund_amount":47600,"claim_shipping_fee":3000,"price_difference":0,"collect_carrier_name":"CJ대한통운","collect_tracking_no":"123456789012","requested_at":"2026-08-27T04:10:22.118400Z","updated_at":"2026-08-27T06:15:03.442901Z","items":[{"item_code":"VR20260826-0000001-01","item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","quantity":2,"product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품"}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"클레임이 없거나 이 API Key의 셀러 클레임이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"클레임을 찾을 수 없습니다.","error_code":"CLAIM_NOT_FOUND"}}}}},"409":{"description":"수거 등록할 수 없는 상태의 클레임입니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"수거 등록할 수 없는 상태의 클레임입니다.","error_code":"CLAIM_NOT_COLLECTABLE"}}}}},"422":{"description":"Idempotency-Key 헤더가 없습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"Idempotency-Key 헤더가 필요합니다.","error_code":"IDEMPOTENCY_KEY_REQUIRED"}}}}}}}},"/open/v1/claims/{claim_no}/collect-done":{"post":{"tags":["클레임"],"summary":"수거 완료(회수 상품 입고)","description":"회수한 상품이 창고에 도착했음을 등록하고 상태를 수거완료(`collected`)로 바꿉니다. 수거중(`collecting`) 상태에서만 호출할 수 있으며, 다음 단계는 검수(`inspect`)입니다.\n\n이미 요청한 상태라면 아무것도 바꾸지 않고 성공(200)으로 응답합니다. 응답 항목의 `already_done`이\n`true`면 이번 호출 전에 이미 그 상태였다는 뜻입니다. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"mark_collect_done_open_v1_claims__claim_no__collect_done_post","security":[{"X-Api-Key":[]}],"parameters":[{"name":"claim_no","in":"path","required":true,"schema":{"type":"string","description":"처리할 클레임번호입니다.","examples":["CL260826-000123"],"title":"Claim No"},"description":"처리할 클레임번호입니다."},{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenClaimOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"claim_no":"CL260826-000123","order_no":"VR20260826-0000001","type":"return","status":"collected","available_actions":["inspect"],"fault":"buyer","reason_code":"change_of_mind","refund_amount":47600,"claim_shipping_fee":3000,"price_difference":0,"collect_carrier_name":"CJ대한통운","collect_tracking_no":"123456789012","requested_at":"2026-08-27T04:10:22.118400Z","updated_at":"2026-08-28T01:05:44.702311Z","items":[{"item_code":"VR20260826-0000001-01","item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","quantity":2,"product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품"}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"클레임이 없거나 이 API Key의 셀러 클레임이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"클레임을 찾을 수 없습니다.","error_code":"CLAIM_NOT_FOUND"}}}}},"409":{"description":"수거 완료 처리할 수 없는 상태의 클레임입니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"수거 완료 처리할 수 없는 상태의 클레임입니다.","error_code":"CLAIM_NOT_COLLECT_DONE"}}}}},"422":{"description":"Idempotency-Key 헤더가 없습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"Idempotency-Key 헤더가 필요합니다.","error_code":"IDEMPOTENCY_KEY_REQUIRED"}}}}}}}},"/open/v1/claims/{claim_no}/inspect":{"post":{"tags":["클레임"],"summary":"검수 결과 등록","description":"회수한 상품의 검수 결과를 등록합니다. 수거완료(`collected`) 상태에서만 호출할 수 있습니다.\n\n`result`가 `pass`(합격)면 반품은 환불 절차로, 교환은 재출고 절차로 넘어갑니다. `fail`(불합격)이면 신청이 거부 처리되며 `memo`에 사유를 반드시 넣어야 합니다. 이미 검수한 신청에 다시 호출하면 409로 거절되므로, 현재 상태는 클레임 조회로 확인해주세요. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"inspect_claim_open_v1_claims__claim_no__inspect_post","security":[{"X-Api-Key":[]}],"parameters":[{"name":"claim_no","in":"path","required":true,"schema":{"type":"string","description":"처리할 클레임번호입니다.","examples":["CL260826-000123"],"title":"Claim No"},"description":"처리할 클레임번호입니다."},{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenClaimInspectRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenClaimOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"claim_no":"CL260826-000123","order_no":"VR20260826-0000001","type":"return","status":"refund_processing","available_actions":[],"fault":"buyer","reason_code":"change_of_mind","refund_amount":47600,"claim_shipping_fee":3000,"price_difference":0,"collect_carrier_name":"CJ대한통운","collect_tracking_no":"123456789012","inspect_result":"pass","requested_at":"2026-08-27T04:10:22.118400Z","updated_at":"2026-08-28T02:22:19.360744Z","items":[{"item_code":"VR20260826-0000001-01","item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","quantity":2,"product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품"}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"클레임이 없거나 이 API Key의 셀러 클레임이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"클레임을 찾을 수 없습니다.","error_code":"CLAIM_NOT_FOUND"}}}}},"409":{"description":"검수 처리할 수 없는 상태의 클레임입니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"검수 처리할 수 없는 상태의 클레임입니다.","error_code":"CLAIM_NOT_INSPECTABLE"}}}}},"422":{"description":"Idempotency-Key 헤더가 없습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"Idempotency-Key 헤더가 필요합니다.","error_code":"IDEMPOTENCY_KEY_REQUIRED"}}}}}}}},"/open/v1/claims/{claim_no}/reship":{"post":{"tags":["클레임"],"summary":"교환 재출고 송장 등록","description":"교환 상품을 다시 보낼 택배사와 운송장번호를 등록해 교환을 완료합니다. 재출고 대기(`reshipping`) 상태의 교환 신청에만 호출할 수 있습니다.\n\n이미 같은 송장으로 재출고 등록된 신청이면 아무것도 바꾸지 않고 성공으로 응답합니다. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"reship_claim_open_v1_claims__claim_no__reship_post","security":[{"X-Api-Key":[]}],"parameters":[{"name":"claim_no","in":"path","required":true,"schema":{"type":"string","description":"처리할 클레임번호입니다.","examples":["CL260826-000123"],"title":"Claim No"},"description":"처리할 클레임번호입니다."},{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenClaimShipmentRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenClaimOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"claim_no":"CL260826-000123","order_no":"VR20260826-0000001","type":"exchange","status":"completed","available_actions":[],"fault":"buyer","reason_code":"change_of_mind","refund_amount":0,"claim_shipping_fee":3000,"price_difference":0,"collect_carrier_name":"CJ대한통운","collect_tracking_no":"123456789012","reship_carrier_name":"CJ대한통운","reship_tracking_no":"987654321098","inspect_result":"pass","requested_at":"2026-08-27T04:10:22.118400Z","completed_at":"2026-08-28T03:41:57.884120Z","updated_at":"2026-08-28T03:41:57.884120Z","items":[{"item_code":"VR20260826-0000001-01","item_id":"0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b","quantity":2,"product_name":"비타민C 브라이트닝 세럼 30ml","option_name":"30ml 단품","exchange_option_name":"50ml 단품"}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"클레임이 없거나 이 API Key의 셀러 클레임이 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"클레임을 찾을 수 없습니다.","error_code":"CLAIM_NOT_FOUND"}}}}},"409":{"description":"재출고 등록할 수 없는 상태의 클레임입니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"재출고 등록할 수 없는 상태의 클레임입니다.","error_code":"CLAIM_NOT_RESHIPPABLE"}}}}},"422":{"description":"Idempotency-Key 헤더가 없습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"Idempotency-Key 헤더가 필요합니다.","error_code":"IDEMPOTENCY_KEY_REQUIRED"}}}}}}}},"/open/v1/qna":{"get":{"tags":["상품 문의"],"summary":"상품 문의 목록 조회","description":"귀사 상품에 달린 고객 문의를 최신 변경 순으로 가져옵니다. 답변 대기 건만 뽑으려면 `status=waiting`을 사용해주세요.\n\n비밀글도 응답에 내용이 그대로 담기므로(판매자 응대용), 귀사 시스템에서 외부에 노출하지 않도록 주의해주세요. 새 문의를 주기적으로 수집하려면 `updated_at_gte`로 구간을 지정해 반복 호출합니다.\n### 수집 루프\n\n1. 첫 요청은 `cursor` 없이 보냅니다.\n2. 응답의 `data.next_cursor`를 **같은 필터 조건을 유지한 채** 다음 요청의 `cursor`로 그대로 전달합니다.\n3. `next_cursor`가 `null`이면 이번 회차 수집이 끝난 것입니다.\n4. 다음 회차는 5분 뒤에 시작하되 `updated_at_gte`를 **직전 수집 시각보다 10분 앞선 값**으로 두고\n   커서 없이 다시 1번부터 진행합니다. 구간을 겹쳐 조회하므로 같은 건이 두 번 올 수 있습니다 —\n   식별자 기준으로 덮어쓰기(upsert)하면 중복이 문제가 되지 않습니다.","operationId":"list_qnas_open_v1_qna_get","security":[{"X-Api-Key":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"enum":["waiting","answered"],"type":"string"},{"type":"null"}],"description":"답변 상태로 거릅니다. `waiting`(답변 대기) 또는 `answered`(답변 완료)이며, 그 밖의 값을 보내면 422로 거절됩니다.","examples":["waiting"],"title":"Status"},"description":"답변 상태로 거릅니다. `waiting`(답변 대기) 또는 `answered`(답변 완료)이며, 그 밖의 값을 보내면 422로 거절됩니다."},{"name":"updated_at_gte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"이 시각 이후(같은 시각 포함)에 변경된 문의만 가져옵니다. 변경분 수집의 기준이 되는 필터입니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-26T09:00:00+09:00"],"title":"Updated At Gte"},"description":"이 시각 이후(같은 시각 포함)에 변경된 문의만 가져옵니다. 변경분 수집의 기준이 되는 필터입니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"updated_at_lte","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"이 시각 이전(같은 시각 포함)에 변경된 문의만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422).","examples":["2026-08-26T09:10:00+09:00"],"title":"Updated At Lte"},"description":"이 시각 이전(같은 시각 포함)에 변경된 문의만 가져옵니다. ISO 8601 형식으로 보냅니다. 오프셋을 생략하면 UTC로 해석하므로 한국 시각은 `+09:00`을 붙여주세요. URL을 직접 조립한다면 `+`를 `%2B`로 인코딩해야 합니다(미인코딩 시 공백으로 해석되어 422)."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"한 페이지에 받을 최대 건수입니다. 1 이상 100 이하이며, 생략하면 50건입니다.","examples":[50],"default":50,"title":"Limit"},"description":"한 페이지에 받을 최대 건수입니다. 1 이상 100 이하이며, 생략하면 50건입니다."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"페이지 넘김 토큰입니다. 첫 요청에는 보내지 않습니다. 응답의 `data.next_cursor` 값을 같은 필터 조건을 유지한 채 다음 요청의 `cursor`로 그대로 전달하면 다음 페이지를 받습니다. 서버가 발급한 값만 유효하며 직접 생성·수정하면 422(`INVALID_CURSOR`)로 거부됩니다.","examples":["eyJtIjoiMjAyNi0wOC0yNlQwMjo0MTowNy45MTMyMDQrMDA6MDAiLCJwIjoiLi4uIiwidiI6MSwidyI6Ii4uLiJ9"],"title":"Cursor"},"description":"페이지 넘김 토큰입니다. 첫 요청에는 보내지 않습니다. 응답의 `data.next_cursor` 값을 같은 필터 조건을 유지한 채 다음 요청의 `cursor`로 그대로 전달하면 다음 페이지를 받습니다. 서버가 발급한 값만 유효하며 직접 생성·수정하면 422(`INVALID_CURSOR`)로 거부됩니다."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenCursorPage_OpenQnaOut__"},"example":{"meta":{"code":200,"message":"OK"},"data":{"list":[{"qna_id":"7c4a9e15-2b83-4f6d-a0c9-5e1d3f7b8a24","product_id":"b2e5d418-93af-4c07-8d61-0a5f4e2c9b73","product_name":"비타민C 브라이트닝 세럼 30ml","category":"delivery","body":"주문한 상품 언제 발송되나요?","is_secret":false,"member_display_name":"뷰리러버","status":"waiting","image_urls":[],"created_at":"2026-08-26T03:11:09.204118Z","updated_at":"2026-08-26T03:11:09.204118Z"}]}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"422":{"description":"커서가 잘못됐습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"커서가 올바르지 않습니다. 커서 없이 처음부터 다시 수집해 주세요.","error_code":"INVALID_CURSOR"}}}}}}}},"/open/v1/qna/{qna_id}/answer":{"post":{"tags":["상품 문의"],"summary":"문의 답변 등록","description":"고객 문의에 답변을 등록합니다. 답변이 등록되면 문의 상태가 `answered`로 바뀝니다.\n\n**이미 등록된 답변은 이 API로 바꿀 수 없습니다.** 같은 내용을 다시 보내면 아무것도 바꾸지 않고 성공으로 응답하고(`converged`가 `true`), 다른 내용을 보내면 409(`QNA_ALREADY_ANSWERED`)로 거절됩니다. 답변 수정이 필요하면 파트너센터에서 진행해주세요. 요청에는 `Idempotency-Key` 헤더가 필수입니다.","operationId":"answer_qna_open_v1_qna__qna_id__answer_post","security":[{"X-Api-Key":[]}],"parameters":[{"name":"qna_id","in":"path","required":true,"schema":{"type":"string","description":"답변을 등록할 문의의 고유 ID(UUID)입니다.","examples":["7c4a9e15-2b83-4f6d-a0c9-5e1d3f7b8a24"],"title":"Qna Id"},"description":"답변을 등록할 문의의 고유 ID(UUID)입니다."},{"name":"Idempotency-Key","in":"header","required":true,"description":"요청마다 새로 만드는 고유 문자열입니다(UUID 권장, 200자 이하). 타임아웃·네트워크 오류로 재시도할 때는 **처음과 같은 키**를 보내주세요 — 서버가 저장해 둔 첫 결과를 그대로 다시 돌려주므로 이중 처리가 일어나지 않습니다. 같은 키로 내용이 다른 요청을 보내면 409(`IDEMPOTENCY_KEY_REUSED`)로 거절되며, 저장된 결과는 24시간 뒤 삭제됩니다. 빈 값이거나 공백만 있는 값은 422(`IDEMPOTENCY_KEY_REQUIRED`)로 거절됩니다.","schema":{"type":"string","minLength":1,"maxLength":200,"pattern":"\\S"},"example":"6b1f7a52-3c9e-4d18-9a77-0f2c5e8b4d31"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenQnaAnswerRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponse_OpenQnaAnswerOut_"},"example":{"meta":{"code":200,"message":"OK"},"data":{"qna_id":"7c4a9e15-2b83-4f6d-a0c9-5e1d3f7b8a24","status":"answered","answered_at":"2026-08-26T06:20:31.556902Z","converged":false}}}}},"401":{"description":"API Key가 없거나 유효하지 않습니다.","content":{"application/json":{"example":{"meta":{"code":401,"message":"유효하지 않은 API 키입니다.","error_code":"INVALID_API_KEY"}}}}},"403":{"description":"API Key에 이 엔드포인트의 권한(스코프)이 없습니다.","content":{"application/json":{"example":{"meta":{"code":403,"message":"이 API를 호출할 권한이 없습니다.","error_code":"SCOPE_FORBIDDEN"}}}}},"404":{"description":"문의가 없거나 이 API Key의 셀러 상품 문의가 아닙니다.","content":{"application/json":{"example":{"meta":{"code":404,"message":"문의를 찾을 수 없습니다.","error_code":"QNA_NOT_FOUND"}}}}},"409":{"description":"이미 다른 내용의 답변이 등록돼 있습니다.","content":{"application/json":{"example":{"meta":{"code":409,"message":"이미 다른 내용의 답변이 등록돼 있습니다.","error_code":"QNA_ALREADY_ANSWERED"}}}}},"422":{"description":"Idempotency-Key 헤더가 없습니다.","content":{"application/json":{"example":{"meta":{"code":422,"message":"Idempotency-Key 헤더가 필요합니다.","error_code":"IDEMPOTENCY_KEY_REQUIRED"}}}}}}}}},"components":{"schemas":{"ApiResponse_BatchTransitionResult_":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","default":{"code":200,"message":"OK"}},"data":{"anyOf":[{"$ref":"#/components/schemas/BatchTransitionResult"},{"type":"null"}]}},"type":"object","title":"ApiResponse[BatchTransitionResult]"},"ApiResponse_OpenClaimOut_":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","default":{"code":200,"message":"OK"}},"data":{"anyOf":[{"$ref":"#/components/schemas/OpenClaimOut"},{"type":"null"}]}},"type":"object","title":"ApiResponse[OpenClaimOut]"},"ApiResponse_OpenCursorPage_OpenClaimOut__":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","default":{"code":200,"message":"OK"}},"data":{"anyOf":[{"$ref":"#/components/schemas/OpenCursorPage_OpenClaimOut_"},{"type":"null"}]}},"type":"object","title":"ApiResponse[OpenCursorPage[OpenClaimOut]]"},"ApiResponse_OpenCursorPage_OpenOrderOut__":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","default":{"code":200,"message":"OK"}},"data":{"anyOf":[{"$ref":"#/components/schemas/OpenCursorPage_OpenOrderOut_"},{"type":"null"}]}},"type":"object","title":"ApiResponse[OpenCursorPage[OpenOrderOut]]"},"ApiResponse_OpenCursorPage_OpenQnaOut__":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","default":{"code":200,"message":"OK"}},"data":{"anyOf":[{"$ref":"#/components/schemas/OpenCursorPage_OpenQnaOut_"},{"type":"null"}]}},"type":"object","title":"ApiResponse[OpenCursorPage[OpenQnaOut]]"},"ApiResponse_OpenOrderOut_":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","default":{"code":200,"message":"OK"}},"data":{"anyOf":[{"$ref":"#/components/schemas/OpenOrderOut"},{"type":"null"}]}},"type":"object","title":"ApiResponse[OpenOrderOut]"},"ApiResponse_OpenQnaAnswerOut_":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","default":{"code":200,"message":"OK"}},"data":{"anyOf":[{"$ref":"#/components/schemas/OpenQnaAnswerOut"},{"type":"null"}]}},"type":"object","title":"ApiResponse[OpenQnaAnswerOut]"},"ApiResponse_OpenTransitionResultOut_":{"properties":{"meta":{"$ref":"#/components/schemas/Meta","default":{"code":200,"message":"OK"}},"data":{"anyOf":[{"$ref":"#/components/schemas/OpenTransitionResultOut"},{"type":"null"}]}},"type":"object","title":"ApiResponse[OpenTransitionResultOut]"},"BatchFailure":{"properties":{"order_no":{"type":"string","title":"Order No","description":"실패한 주문의 번호입니다.","examples":["VR20260826-0000002"]},"order_item_public_ids":{"items":{"type":"string"},"type":"array","title":"Order Item Public Ids","description":"실패한 주문 상품의 고유 ID 목록입니다. 주문 자체를 찾지 못한 경우 빈 배열입니다.","examples":[["5a1c2d33-8e47-4b90-b6f2-1d0e9a7c4b58"]]},"error_code":{"type":"string","title":"Error Code","description":"실패 원인을 나타내는 고정 코드입니다. 의미는 문서 상단의 오류 코드 표를 참고해주세요.","examples":["ORDER_ITEM_NOT_SHIPPABLE"]},"message":{"type":"string","title":"Message","description":"사람이 읽는 실패 사유입니다. 분기 처리는 `error_code`로 해주세요.","examples":["발송 처리할 수 없는 상태의 상품입니다."]}},"type":"object","required":["order_no","error_code","message"],"title":"BatchFailure","description":"일괄 처리에서 실패한 항목 1건입니다. 처리 가능한 항목은 그대로 반영되고, 실패한 항목만\n이 목록에 담깁니다."},"BatchTransitionResult":{"properties":{"succeeded":{"items":{"type":"string"},"type":"array","title":"Succeeded","description":"처리에 성공한 주문 상품의 고유 ID 목록입니다.","examples":[["0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b"]]},"failed":{"items":{"$ref":"#/components/schemas/BatchFailure"},"type":"array","title":"Failed","description":"처리하지 못한 항목의 목록입니다. 전부 성공하면 빈 배열입니다."},"summary":{"$ref":"#/components/schemas/BatchTransitionSummary","description":"성공·실패 건수 집계입니다."}},"type":"object","title":"BatchTransitionResult","description":"일괄 처리 결과입니다. 일부만 성공해도 HTTP 200으로 응답하므로, 상태 코드가 아니라 `failed`\n목록을 확인해 실패 건을 처리해주세요."},"BatchTransitionSummary":{"properties":{"succeeded":{"type":"integer","title":"Succeeded","description":"처리에 성공한 주문 상품 수입니다.","default":0,"examples":[1]},"failed":{"type":"integer","title":"Failed","description":"처리에 실패한 주문 상품 수입니다.","default":0,"examples":[1]}},"type":"object","title":"BatchTransitionSummary","description":"일괄 처리 결과 집계입니다."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Meta":{"properties":{"code":{"type":"integer","title":"Code","default":200},"message":{"type":"string","title":"Message","default":"OK"},"error_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Code"},"error_data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Error Data"}},"type":"object","title":"Meta","description":"응답 메타. 성공/에러 형태를 일관되게 유지한다."},"OpenBatchShipmentEntry":{"properties":{"item_ids":{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1,"title":"Item Ids","description":"이 송장으로 발송하는 주문 상품의 고유 ID(UUID) 목록입니다. 1개 이상 200개 이하이며, 요청 전체에서 같은 값이 두 번 나타나면 422로 거절됩니다.","examples":[["0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b"]]},"order_no":{"type":"string","maxLength":40,"title":"Order No","description":"송장을 등록할 주문의 번호입니다.","examples":["VR20260826-0000001"]},"carrier_name":{"type":"string","maxLength":80,"title":"Carrier Name","description":"택배사명입니다. 허용되는 값은 `CJ대한통운` · `우체국택배` · `한진택배` · `롯데택배` · `로젠택배` 다섯 가지입니다.","examples":["CJ대한통운"]},"tracking_no":{"type":"string","maxLength":80,"title":"Tracking No","description":"운송장번호입니다.","examples":["123456789012"]},"logistics_company":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Logistics Company","description":"물류대행사명입니다. 없으면 생략하거나 `null`로 보냅니다.","examples":["위킵"]}},"type":"object","required":["item_ids","order_no","carrier_name","tracking_no"],"title":"OpenBatchShipmentEntry","description":"일괄 송장 등록에서 주문 1건에 대한 입력입니다. 주문마다 송장이 다르므로 항목마다 택배사·\n운송장번호를 각각 지정합니다."},"OpenBatchShipmentRequest":{"properties":{"items":{"items":{"$ref":"#/components/schemas/OpenBatchShipmentEntry"},"type":"array","maxItems":500,"minItems":1,"title":"Items","description":"주문별 송장 항목 목록입니다. 1건 이상 500건 이하로 보냅니다."}},"type":"object","required":["items"],"title":"OpenBatchShipmentRequest","description":"여러 주문의 송장을 한 번에 등록하는 요청입니다. 주문 단위로 각각 처리되므로 일부가 실패해도\n나머지는 정상 등록됩니다."},"OpenClaimInspectRequest":{"properties":{"result":{"type":"string","enum":["pass","fail"],"title":"Result","description":"검수 결과입니다. `pass`(합격)를 보내면 반품은 환불 절차로, 교환은 재출고 절차로 넘어갑니다. `fail`(불합격)을 보내면 신청이 거부 처리되며 이때 `memo`가 필수입니다.","examples":["pass"]},"memo":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Memo","description":"검수 메모입니다. 500자 이하로 보냅니다. `result`가 `fail`이면 불합격 사유로 반드시 채워야 합니다.","examples":["개봉 흔적 없이 정상 회수되었습니다."]}},"type":"object","required":["result"],"title":"OpenClaimInspectRequest","description":"회수한 상품의 검수 결과 등록 요청입니다."},"OpenClaimItemOut":{"properties":{"item_code":{"type":"string","title":"Item Code","description":"신청 대상이 된 원래 주문상품번호입니다. 고객이 주문 수량 중 일부만 신청해 주문 상품이 나뉘더라도 이 값은 귀사가 처음 수집한 번호 그대로 유지되므로, 귀사 시스템의 주문 건과 맞춰 보는 기준으로 사용해주세요.","examples":["VR20260826-0000001-01"]},"item_id":{"type":"string","title":"Item Id","description":"현재 이 신청에 묶여 있는 주문 상품의 고유 ID(UUID)입니다. 부분 취소·반품으로 주문 상품이 나뉘면 새로 만들어진 쪽의 ID가 들어오므로, `item_code`와 값이 다를 수 있습니다. **부분 클레임이 완결되면 원래 주문 상품 1줄이 「신청 수량」 줄과 「남은 수량」 줄로 나뉩니다** — 신청 수량 쪽은 새 `item_id`를 가진 종료 상태 줄로 분리되고 남은 수량은 원래 줄에 그대로 남으며, 이 필드는 신청 수량 쪽(새 줄)을 가리킵니다. 주문 조회 응답에서도 두 줄이 각각 별도 항목으로 나타납니다.","examples":["0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b"]},"quantity":{"type":"integer","title":"Quantity","description":"고객이 신청한 수량입니다.","examples":[2]},"product_name":{"type":"string","title":"Product Name","description":"주문 시점의 상품명입니다.","examples":["비타민C 브라이트닝 세럼 30ml"]},"option_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Option Name","description":"주문 시점의 옵션명입니다. 옵션이 없는 상품이면 `null`입니다.","examples":["30ml 단품"]},"exchange_option_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Exchange Option Name","description":"고객이 교환받기를 원하는 옵션명입니다. 교환 신청이 아니거나 옵션이 없는 상품이면 `null`입니다.","examples":["50ml 단품"]}},"type":"object","required":["item_code","item_id","quantity","product_name"],"title":"OpenClaimItemOut","description":"취소·반품·교환 신청 대상 상품 1건입니다."},"OpenClaimOut":{"properties":{"claim_no":{"type":"string","title":"Claim No","description":"클레임번호입니다. `CL` + 신청일(YYMMDD) + `-` + 6자리 순번 형식입니다.","examples":["CL260826-000123"]},"order_no":{"type":"string","title":"Order No","description":"이 신청이 걸린 주문의 번호입니다.","examples":["VR20260826-0000001"]},"type":{"type":"string","title":"Type","description":"신청 종류입니다. `cancel`(취소) · `return`(반품) · `exchange`(교환) 중 하나입니다.","examples":["return"]},"status":{"type":"string","title":"Status","description":"신청의 진행 상태입니다. `requested`(접수 대기) · `approved`(승인) · `collecting`(수거중) · `collected`(수거완료) · `inspecting`(검수중) · `reshipping`(재출고 대기, 교환만) · `refund_processing`(환불 진행) · `completed`(완료) · `rejected`(거부) · `withdrawn`(고객 철회) · `converted_to_return`(교환에서 반품으로 전환) · `expired`(기한 만료) · `payment_pending`(차액 결제 대기) 중 하나입니다.","examples":["collected"]},"available_actions":{"items":{"type":"string"},"type":"array","title":"Available Actions","description":"**지금 이 신청에 호출할 수 있는 처리 API 목록**입니다. 서버가 현재 상태와 신청 종류를 보고 계산해 주므로, 상태 문자열을 보고 직접 판단하지 말고 이 배열로 버튼 노출·자동 처리 여부를 결정해주세요. 배열의 각 값은 처리 API 경로의 마지막 조각과 같습니다 — `approve` · `reject` · `pickup` · `collect-done` · `inspect` · `reship`. 빈 배열이면 지금 호출할 수 있는 처리가 없다는 뜻입니다(완료·거부 등 종료 상태이거나, 다음 단계가 VURITY 내부에서 진행되는 중입니다).\n\n이 배열은 **신청 종류(`type`) × 현재 상태(`status`)** 매핑에서 서버가 계산합니다. 예를 들어 `pickup`·`collect-done`·`inspect`는 `return`·`exchange`에만 있고 `cancel`에는 없으며, `reship`은 `exchange`의 `reshipping` 상태에서만 나옵니다. 종류별 단계 흐름은 연동 규격서의 「클레임 플로우」 절에 정리돼 있으니 참고하시되, **연동 구현은 그 흐름을 코드로 옮겨 적지 말고 이 필드를 그대로 사용**해주세요. 매핑이 바뀌어도 이 필드는 항상 서버 기준으로 맞습니다.","examples":[["inspect"]]},"fault":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fault","description":"귀책 주체입니다. `buyer`(고객 사유 — 배송비를 고객이 부담) 또는 `seller`(판매자 사유 — 배송비를 판매자가 부담)입니다. 신청 사유에서 자동으로 결정됩니다.","examples":["buyer"]},"reason_code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason Code","description":"신청 사유입니다. `change_of_mind`(단순변심) · `wrong_order_info`(정보오기재) · `defective`(상품 하자·파손) · `wrong_delivery`(오배송) · `out_of_stock`(품절) · `delayed_by_seller`(발송지연) · `etc`(기타) 중 하나입니다. `wrong_order_info`(정보오기재)는 `return`·`exchange` 전용 `buyer` 귀책이며 `cancel`에는 사용할 수 없습니다.","examples":["change_of_mind"]},"refund_amount":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Refund Amount","description":"고객에게 환불되는 금액(원)입니다. 배송비 부담분까지 반영한 최종 금액이며, 환불 금액이 확정되기 전이거나 환불이 없는 신청이면 `null`일 수 있습니다.","examples":[47600]},"claim_shipping_fee":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Claim Shipping Fee","description":"이 신청에 부과된 반품·교환 배송비(원)입니다. `fault`가 `buyer`면 환불액에서 차감되고, `seller`면 0입니다.","examples":[3000]},"price_difference":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Price Difference","description":"교환 시 발생한 상품 가격 차액(원)입니다. 양수면 고객이 추가로 결제한 금액, 음수면 고객에게 돌려주는 금액입니다. 취소·반품은 0입니다.","examples":[0]},"collect_carrier_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collect Carrier Name","description":"반품·교환 상품을 회수할 택배사명입니다. 아직 수거 등록 전이면 `null`입니다.","examples":["CJ대한통운"]},"collect_tracking_no":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Collect Tracking No","description":"회수 운송장번호입니다. 아직 수거 등록 전이면 `null`입니다.","examples":["123456789012"]},"reship_carrier_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reship Carrier Name","description":"교환 상품을 다시 보낼 때의 택배사명입니다. 교환이 아니거나 아직 재출고 송장을 등록하지 않았으면 `null`입니다.","examples":["CJ대한통운"]},"reship_tracking_no":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reship Tracking No","description":"교환 재출고 운송장번호입니다. 교환이 아니거나 아직 재출고 송장을 등록하지 않았으면 `null`입니다.","examples":["987654321098"]},"inspect_result":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Inspect Result","description":"회수한 상품의 검수 결과입니다. `pass`(합격 — 환불·교환 진행) 또는 `fail`(불합격)이며, 아직 검수하지 않았으면 `null`입니다.","examples":["pass"]},"requested_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Requested At","description":"고객이 신청한 시각(UTC)입니다.","examples":["2026-08-27T04:10:22.118400Z"]},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"신청이 최종 종료된 시각(UTC)입니다. 아직 진행 중이면 `null`입니다.","examples":["2026-08-29T07:31:55.640922Z"]},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"이 신청이 마지막으로 변경된 시각(UTC)입니다. 변경분만 주기적으로 가져올 때 `updated_at_gte` 필터의 기준으로 사용하는 값입니다.","examples":["2026-08-28T01:05:44.702311Z"]},"items":{"items":{"$ref":"#/components/schemas/OpenClaimItemOut"},"type":"array","title":"Items","description":"신청 대상 상품 목록입니다."}},"type":"object","required":["claim_no","order_no","type","status","available_actions","updated_at","items"],"title":"OpenClaimOut","description":"취소·반품·교환 신청 1건입니다. 처리 API의 응답도 같은 형식이므로, 처리 직후의 상태를\n별도 조회 없이 이 응답에서 바로 확인할 수 있습니다."},"OpenClaimRejectRequest":{"properties":{"memo":{"type":"string","maxLength":500,"minLength":1,"title":"Memo","description":"거부 사유입니다. 1자 이상 500자 이하로 보냅니다. 이미 거부된 신청에 다시 호출하면 사유 문구가 달라도 성공으로 응답하며, 저장되는 사유는 **처음 성공한 요청의 값**입니다(재시도로 사유가 덮어써지지 않습니다).","examples":["고객 요청으로 발송이 이미 완료되어 취소가 어렵습니다."]}},"type":"object","required":["memo"],"title":"OpenClaimRejectRequest","description":"취소·반품·교환 거부 요청입니다."},"OpenClaimShipmentRequest":{"properties":{"carrier_name":{"type":"string","maxLength":80,"title":"Carrier Name","description":"택배사명입니다. 허용되는 값은 `CJ대한통운` · `우체국택배` · `한진택배` · `롯데택배` · `로젠택배` 다섯 가지입니다. 목록에 없는 값을 보내면 422(`SHIPMENT_CARRIER_NOT_ALLOWED`)로 거절됩니다.","examples":["CJ대한통운"]},"tracking_no":{"type":"string","maxLength":80,"title":"Tracking No","description":"운송장번호입니다.","examples":["123456789012"]}},"type":"object","required":["carrier_name","tracking_no"],"title":"OpenClaimShipmentRequest","description":"수거 등록·교환 재출고 송장 등록 요청입니다."},"OpenCursorPage_OpenClaimOut_":{"properties":{"list":{"items":{"$ref":"#/components/schemas/OpenClaimOut"},"type":"array","title":"List","description":"이 페이지에 담긴 조회 결과입니다. 결과가 없으면 빈 배열입니다."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"다음 페이지 요청에 그대로 전달할 토큰입니다. `null`이면 마지막 페이지입니다. 페이지를 넘기는 동안 새로 변경된 데이터는 이번 조회 회차에 포함되지 않으므로(첫 요청 시점을 기준으로 고정됩니다), 다음 수집 회차를 `updated_at_gte` 기준으로 새로 시작해 가져가주세요.","examples":["eyJtIjoiMjAyNi0wOC0yNlQwMjo0MTowNy45MTMyMDQrMDA6MDAiLCJwIjoiLi4uIiwidiI6MSwidyI6Ii4uLiJ9"]}},"type":"object","required":["list"],"title":"OpenCursorPage[OpenClaimOut]","description":"목록 조회 결과 한 페이지입니다. 조회 결과는 `list`에 담기고, 다음 페이지가 있으면 `next_cursor`에 토큰이 들어옵니다."},"OpenCursorPage_OpenOrderOut_":{"properties":{"list":{"items":{"$ref":"#/components/schemas/OpenOrderOut"},"type":"array","title":"List","description":"이 페이지에 담긴 조회 결과입니다. 결과가 없으면 빈 배열입니다."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"다음 페이지 요청에 그대로 전달할 토큰입니다. `null`이면 마지막 페이지입니다. 페이지를 넘기는 동안 새로 변경된 데이터는 이번 조회 회차에 포함되지 않으므로(첫 요청 시점을 기준으로 고정됩니다), 다음 수집 회차를 `updated_at_gte` 기준으로 새로 시작해 가져가주세요.","examples":["eyJtIjoiMjAyNi0wOC0yNlQwMjo0MTowNy45MTMyMDQrMDA6MDAiLCJwIjoiLi4uIiwidiI6MSwidyI6Ii4uLiJ9"]}},"type":"object","required":["list"],"title":"OpenCursorPage[OpenOrderOut]","description":"목록 조회 결과 한 페이지입니다. 조회 결과는 `list`에 담기고, 다음 페이지가 있으면 `next_cursor`에 토큰이 들어옵니다."},"OpenCursorPage_OpenQnaOut_":{"properties":{"list":{"items":{"$ref":"#/components/schemas/OpenQnaOut"},"type":"array","title":"List","description":"이 페이지에 담긴 조회 결과입니다. 결과가 없으면 빈 배열입니다."},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"다음 페이지 요청에 그대로 전달할 토큰입니다. `null`이면 마지막 페이지입니다. 페이지를 넘기는 동안 새로 변경된 데이터는 이번 조회 회차에 포함되지 않으므로(첫 요청 시점을 기준으로 고정됩니다), 다음 수집 회차를 `updated_at_gte` 기준으로 새로 시작해 가져가주세요.","examples":["eyJtIjoiMjAyNi0wOC0yNlQwMjo0MTowNy45MTMyMDQrMDA6MDAiLCJwIjoiLi4uIiwidiI6MSwidyI6Ii4uLiJ9"]}},"type":"object","required":["list"],"title":"OpenCursorPage[OpenQnaOut]","description":"목록 조회 결과 한 페이지입니다. 조회 결과는 `list`에 담기고, 다음 페이지가 있으면 `next_cursor`에 토큰이 들어옵니다."},"OpenOrderItemOut":{"properties":{"item_code":{"type":"string","title":"Item Code","description":"주문상품번호입니다. `{주문번호}-{2자리 순번}` 형식이며 한 번 부여되면 바뀌지 않으므로 귀사 시스템의 상품 단위 식별자로 사용하기 좋습니다.","examples":["VR20260826-0000001-01"]},"item_id":{"type":"string","title":"Item Id","description":"주문 상품의 고유 ID(UUID)입니다. 발주확인·송장 등록·배송완료 API의 `item_ids`에 이 값을 그대로 넣습니다.","examples":["0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b"]},"product_name":{"type":"string","title":"Product Name","description":"주문 시점의 상품명입니다. 이후 상품명이 바뀌어도 이 값은 변하지 않습니다.","examples":["비타민C 브라이트닝 세럼 30ml"]},"option_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Option Name","description":"주문 시점의 옵션명입니다. 옵션이 없는 상품이면 `null`입니다.","examples":["30ml 단품"]},"quantity":{"type":"integer","title":"Quantity","description":"주문 수량입니다.","examples":[2]},"list_price":{"type":"integer","title":"List Price","description":"상품 1개의 정가(원)입니다. 할인 전 표시 가격입니다.","examples":[32000]},"unit_price":{"type":"integer","title":"Unit Price","description":"상품 1개의 실제 판매가(원)입니다. 회원 등급 할인 등이 반영된 가격입니다.","examples":[27000]},"line_amount":{"type":"integer","title":"Line Amount","description":"판매가 × 수량(원)입니다. 쿠폰·포인트 차감 전 금액입니다.","examples":[54000]},"discount_amount":{"type":"integer","title":"Discount Amount","description":"이 상품에 적용된 쿠폰 등 할인액(원)입니다. 할인이 없으면 0입니다.","examples":[5400]},"line_paid_amount":{"type":"integer","title":"Line Paid Amount","description":"이 상품에 대해 고객이 실제로 결제한 금액(원)입니다. `line_amount`에서 할인·포인트 사용분을 뺀 값이며 배송비는 포함하지 않습니다.","examples":[47600]},"item_status":{"type":"string","title":"Item Status","description":"이 상품의 처리 상태입니다. 값은 아래 11종 중 하나입니다.\n\n| 값 | 뜻 |\n| --- | --- |\n| `paid` | 결제완료 — 발주확인 전 |\n| `preparing` | 상품준비중 — 발주확인 완료, 송장 등록 전 |\n| `shipping` | 배송중 — 송장 등록 완료 |\n| `delivered` | 배송완료 |\n| `confirmed` | 구매확정 — 정산 대상 확정(종료 상태) |\n| `canceled` | 취소완료(종료 상태) |\n| `returned` | 반품완료(종료 상태) |\n| `exchanged` | 교환완료(종료 상태) |\n| `pending` | 결제 대기 — 결제 전 상태 |\n| `failed` | 결제 실패 — 결제 전 상태 |\n| `expired` | 결제 기한 만료 — 결제 전 상태 |\n\n오픈 API는 **결제가 완료된 주문만** 노출하므로 마지막 세 값(`pending` · `failed` · `expired`)은 실제 응답에 나타나지 않습니다. 값 사전의 완결성을 위해 함께 싣습니다.","examples":["preparing"]},"tracking_no":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracking No","description":"운송장번호입니다. 아직 송장을 등록하지 않았으면 `null`입니다.","examples":["123456789012"]},"carrier_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Carrier Name","description":"택배사명입니다. 아직 송장을 등록하지 않았으면 `null`입니다. 허용되는 값은 `CJ대한통운` · `우체국택배` · `한진택배` · `롯데택배` · `로젠택배` 다섯 가지입니다.","examples":["CJ대한통운"]},"logistics_company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logistics Company","description":"물류대행사명입니다. 택배사와는 별개로 물류를 위탁한 업체가 있을 때만 값이 들어오며, 대부분의 주문에서는 `null`입니다.","examples":["위킵"]},"is_exchange":{"type":"boolean","title":"Is Exchange","description":"교환으로 새로 만들어진 상품인지 여부입니다. `true`면 고객의 교환 신청에 따라 재발송용으로 추가된 상품이므로 별도 결제 건이 아닙니다.","examples":[false]},"has_active_claim":{"type":"boolean","title":"Has Active Claim","description":"취소·반품·교환이 진행 중인지 여부입니다. `true`인 상품은 발주확인·송장 등록·배송완료 처리가 거절(409)되므로, 클레임 조회 API로 진행 상황을 확인한 뒤 처리해주세요.","examples":[false]},"shipped_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Shipped At","description":"배송중으로 전환된 시각(UTC)입니다. 아직 발송 전이면 `null`입니다.","examples":["2026-08-26T05:22:10.884231Z"]},"delivered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Delivered At","description":"배송완료로 전환된 시각(UTC)입니다. 아직 배송 중이면 `null`입니다.","examples":["2026-08-27T02:40:18.220145Z"]},"confirmed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Confirmed At","description":"고객이 구매확정한 시각(UTC)입니다. 아직 확정 전이면 `null`입니다. 구매확정 이후에는 반품·교환을 신청할 수 없습니다.","examples":["2026-09-03T00:00:12.004311Z"]}},"type":"object","required":["item_code","item_id","product_name","quantity","list_price","unit_price","line_amount","discount_amount","line_paid_amount","item_status","is_exchange","has_active_claim"],"title":"OpenOrderItemOut","description":"주문에 포함된 상품 1건입니다. 한 주문에 여러 셀러의 상품이 섞여 있어도 요청한 API Key의\n셀러 상품만 담기며, 다른 셀러의 상품은 아예 나타나지 않습니다."},"OpenOrderOut":{"properties":{"order_no":{"type":"string","title":"Order No","description":"주문번호입니다. `VR` + 주문일(YYYYMMDD) + `-` + 7자리 순번 형식입니다.","examples":["VR20260826-0000001"]},"order_status":{"type":"string","title":"Order Status","description":"주문 전체의 진행 상태입니다. 주문에 포함된 상품들의 상태에서 자동으로 계산되며, 다른 셀러의 상품 상태도 함께 반영됩니다. 귀사 상품의 처리 판단에는 각 상품의 `item_status`를 사용해주세요. `paid`(결제완료) · `preparing`(상품준비중) · `shipping`(배송중) · `delivered`(배송완료) · `confirmed`(구매확정) · `partially_claimed`(일부 취소·반품·교환 진행 중) · `canceled`(전체 취소) 중 하나입니다.","examples":["preparing"]},"paid_at":{"type":"string","format":"date-time","title":"Paid At","description":"결제가 완료된 시각(UTC)입니다.","examples":["2026-08-26T01:12:33.482910Z"]},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"이 주문이 마지막으로 변경된 시각(UTC)입니다. 변경분만 주기적으로 가져올 때 `updated_at_gte` 필터의 기준으로 사용하는 값입니다.","examples":["2026-08-26T02:41:07.913204Z"]},"currency":{"type":"string","title":"Currency","description":"통화 코드입니다. 항상 `KRW`입니다.","examples":["KRW"]},"seller_items_amount":{"type":"integer","title":"Seller Items Amount","description":"귀사 상품들의 판매가 합계(원)입니다. 할인·포인트 차감 전 금액입니다.","examples":[54000]},"seller_discount_amount":{"type":"integer","title":"Seller Discount Amount","description":"귀사 상품들에 적용된 할인액 합계(원)입니다.","examples":[5400]},"seller_point_used_amount":{"type":"integer","title":"Seller Point Used Amount","description":"귀사 상품들에 사용된 적립금 합계(원)입니다.","examples":[1000]},"seller_paid_amount":{"type":"integer","title":"Seller Paid Amount","description":"귀사 상품들에 대해 고객이 실제로 결제한 금액 합계(원)입니다. 배송비는 포함하지 않으며, 배송비는 아래 `seller_shipping_fee_*`로 따로 확인해주세요.","examples":[47600]},"seller_shipping_fee_base":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seller Shipping Fee Base","description":"이 주문에서 귀사 상품 묶음에 부과된 기본 배송비(원)입니다. 0은 무료배송입니다.","examples":[3000]},"seller_shipping_fee_paid":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Seller Shipping Fee Paid","description":"이 주문에서 귀사 상품 묶음에 대해 고객이 실제로 부담한 배송비(원)입니다. 배송비 쿠폰이 적용되면 기본 배송비보다 작아집니다. 0은 무료배송입니다.","examples":[3000]},"orderer_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orderer Name","description":"주문한 회원의 이름입니다. 탈퇴한 회원의 주문이면 `null`입니다.","examples":["김뷰리"]},"orderer_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Orderer Phone","description":"주문한 회원의 휴대전화번호입니다(하이픈 없음). 탈퇴한 회원의 주문이면 `null`입니다.","examples":["01012345678"]},"recipient_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient Name","description":"받는 사람 이름입니다. 배송지 정보가 없는 주문이면 `null`입니다.","examples":["김뷰리"]},"recipient_phone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Recipient Phone","description":"받는 사람 휴대전화번호입니다(하이픈 없음). 배송지 정보가 없는 주문이면 `null`입니다.","examples":["01012345678"]},"zipcode":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zipcode","description":"배송지 우편번호(5자리)입니다.","examples":["06236"]},"address1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address1","description":"배송지 기본 주소입니다(도로명 또는 지번).","examples":["서울특별시 강남구 테헤란로 123"]},"address2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Address2","description":"배송지 상세 주소입니다. 고객이 입력하지 않았으면 `null`입니다.","examples":["5층 501호"]},"ship_memo":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ship Memo","description":"고객이 남긴 배송 요청사항입니다. 입력하지 않았으면 `null`입니다.","examples":["부재 시 경비실에 맡겨 주세요"]},"items":{"items":{"$ref":"#/components/schemas/OpenOrderItemOut"},"type":"array","title":"Items","description":"이 주문에 포함된 귀사 상품 목록입니다. 다른 셀러의 상품은 담기지 않습니다."}},"type":"object","required":["order_no","order_status","paid_at","updated_at","currency","seller_items_amount","seller_discount_amount","seller_point_used_amount","seller_paid_amount","items"],"title":"OpenOrderOut","description":"결제가 완료된 주문 1건입니다. 금액 필드는 모두 요청한 API Key의 셀러 상품만 합산한 값이며,\n같은 주문에 다른 셀러의 상품이 있어도 그 금액은 포함되지 않습니다."},"OpenQnaAnswerOut":{"properties":{"qna_id":{"type":"string","title":"Qna Id","description":"답변을 등록한 문의의 고유 ID입니다.","examples":["7c4a9e15-2b83-4f6d-a0c9-5e1d3f7b8a24"]},"status":{"type":"string","title":"Status","description":"답변 후의 문의 상태입니다. 정상 처리되면 항상 `answered`입니다.","examples":["answered"]},"answered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Answered At","description":"답변이 등록된 시각(UTC)입니다.","examples":["2026-08-26T06:20:31.556902Z"]},"converged":{"type":"boolean","title":"Converged","description":"이번 호출로 답변이 새로 등록됐으면 `false`, 호출 전에 이미 같은 내용의 답변이 있었으면 `true`입니다. 재시도로 인한 중복 호출이었는지 구분할 때 사용해주세요.","examples":[false]}},"type":"object","required":["qna_id","status","converged"],"title":"OpenQnaAnswerOut","description":"답변 등록 결과입니다. 문의 내용·질문자 정보는 담지 않으므로, 등록 후 전체 내용이 필요하면\n문의 목록 API로 다시 조회해주세요."},"OpenQnaAnswerRequest":{"properties":{"answer_body":{"type":"string","maxLength":2000,"minLength":1,"title":"Answer Body","description":"고객에게 보여 줄 답변 내용입니다. 1자 이상 2000자 이하로 보냅니다. 등록 후 이 API로 내용을 바꿀 수는 없습니다(수정은 파트너센터에서만 가능합니다).","examples":["안녕하세요. 주문하신 상품은 영업일 기준 1~2일 내 발송됩니다."]}},"type":"object","required":["answer_body"],"title":"OpenQnaAnswerRequest","description":"문의 답변 등록 요청입니다."},"OpenQnaOut":{"properties":{"qna_id":{"type":"string","title":"Qna Id","description":"문의의 고유 ID(UUID)입니다. 답변 등록 API의 경로에 이 값을 그대로 넣습니다.","examples":["7c4a9e15-2b83-4f6d-a0c9-5e1d3f7b8a24"]},"product_id":{"type":"string","title":"Product Id","description":"문의가 달린 상품의 고유 ID(UUID)입니다.","examples":["b2e5d418-93af-4c07-8d61-0a5f4e2c9b73"]},"product_name":{"type":"string","title":"Product Name","description":"문의가 달린 상품의 현재 상품명입니다.","examples":["비타민C 브라이트닝 세럼 30ml"]},"category":{"type":"string","title":"Category","description":"고객이 선택한 문의 유형입니다. `product`(상품) · `delivery`(배송) · `exchange_return`(교환·반품) · `usage`(사용법) · `restock`(재입고) · `etc`(기타) 중 하나입니다.","examples":["delivery"]},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title","description":"문의 제목입니다. 현재 고객 화면은 제목 없이 유형과 내용만 받으므로 최근 문의는 대부분 `null`이며, 제목 입력이 있던 시기의 문의에만 값이 있습니다.","examples":["배송 문의드립니다"]},"body":{"type":"string","title":"Body","description":"문의 내용입니다.","examples":["주문한 상품 언제 발송되나요?"]},"is_secret":{"type":"boolean","title":"Is Secret","description":"고객이 비밀글로 작성했는지 여부입니다. 비밀글은 다른 고객에게 내용이 보이지 않지만, 판매자는 응대를 위해 원문을 볼 수 있으므로 `true`여도 `body`에 내용이 그대로 들어옵니다. 귀사 시스템에서 외부에 노출하지 않도록 주의해주세요.","examples":[false]},"member_display_name":{"type":"string","title":"Member Display Name","description":"질문한 회원의 표시 이름(닉네임)입니다. 탈퇴했거나 삭제된 회원이면 `익명회원`으로 반환됩니다.","examples":["뷰리러버"]},"status":{"type":"string","title":"Status","description":"답변 상태입니다. `waiting`(답변 대기) 또는 `answered`(답변 완료)입니다.","examples":["waiting"]},"answer_body":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Answer Body","description":"등록된 답변 내용입니다. 아직 답변 전이면 `null`입니다.","examples":["안녕하세요. 주문하신 상품은 영업일 기준 1~2일 내 발송됩니다."]},"answered_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Answered At","description":"답변이 등록된 시각(UTC)입니다. 아직 답변 전이면 `null`입니다.","examples":["2026-08-26T06:20:31.556902Z"]},"image_urls":{"items":{"type":"string"},"type":"array","title":"Image Urls","description":"고객이 첨부한 이미지의 URL 목록입니다(첨부 순서). 가로 최대 1200px로 변환된 이미지이며, 첨부가 없으면 빈 배열입니다.","examples":[["https://cdn.vurity.kr/qna/2026/08/26/7c4a9e15_1200.webp"]]},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"문의가 등록된 시각(UTC)입니다.","examples":["2026-08-26T03:11:09.204118Z"]},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"이 문의가 마지막으로 변경된 시각(UTC)입니다. 변경분만 주기적으로 가져올 때 `updated_at_gte` 필터의 기준으로 사용하는 값입니다.","examples":["2026-08-26T03:11:09.204118Z"]}},"type":"object","required":["qna_id","product_id","product_name","category","body","is_secret","member_display_name","status","created_at","updated_at"],"title":"OpenQnaOut","description":"귀사 상품에 달린 고객 문의 1건입니다. 질문 내용과 현재 답변 상태를 함께 담습니다."},"OpenShipmentRequest":{"properties":{"item_ids":{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1,"title":"Item Ids","description":"처리할 주문 상품의 고유 ID(UUID) 목록입니다. 주문 조회 응답의 `items[].item_id` 값을 넣습니다. 1개 이상 200개 이하이며, 같은 값을 두 번 넣으면 422로 거절됩니다. 한 주문의 일부 상품만 처리할 수 있습니다.","examples":[["0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b"]]},"carrier_name":{"type":"string","maxLength":80,"title":"Carrier Name","description":"택배사명입니다. 허용되는 값은 `CJ대한통운` · `우체국택배` · `한진택배` · `롯데택배` · `로젠택배` 다섯 가지입니다. 목록에 없는 값을 보내면 422(`SHIPMENT_CARRIER_NOT_ALLOWED`)로 거절됩니다.","examples":["CJ대한통운"]},"tracking_no":{"type":"string","maxLength":80,"title":"Tracking No","description":"운송장번호입니다. 하이픈은 그대로 두고 공백은 제거해 저장됩니다.","examples":["123456789012"]},"logistics_company":{"anyOf":[{"type":"string","maxLength":80},{"type":"null"}],"title":"Logistics Company","description":"물류대행사명입니다. 택배사와 별도로 물류를 위탁한 업체가 있을 때만 보내고, 없으면 생략하거나 `null`로 보냅니다.","examples":["위킵"]}},"type":"object","required":["item_ids","carrier_name","tracking_no"],"title":"OpenShipmentRequest","description":"송장 등록(발송 처리) 요청입니다."},"OpenTransitionItemOut":{"properties":{"item_id":{"type":"string","title":"Item Id","description":"요청의 `item_ids`에 넣은 값 그대로입니다.","examples":["0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b"]},"item_code":{"type":"string","title":"Item Code","description":"주문상품번호입니다.","examples":["VR20260826-0000001-01"]},"item_status":{"type":"string","title":"Item Status","description":"처리 후 이 상품의 상태입니다.","examples":["shipping"]},"tracking_no":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Tracking No","description":"처리 후 등록돼 있는 운송장번호입니다. 송장이 없는 처리 단계면 `null`입니다.","examples":["123456789012"]},"carrier_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Carrier Name","description":"처리 후 등록돼 있는 택배사명입니다. 송장이 없는 처리 단계면 `null`입니다.","examples":["CJ대한통운"]},"logistics_company":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Logistics Company","description":"처리 후 등록돼 있는 물류대행사명입니다. 보내지 않았으면 `null`입니다.","examples":["위킵"]},"already_done":{"type":"boolean","title":"Already Done","description":"이번 호출로 상태가 바뀌었으면 `false`, 호출 전에 이미 요청한 상태였으면 `true`입니다. `true`여도 오류가 아니며, 재시도로 인한 중복 호출이었는지 구분할 때 사용해주세요.","examples":[false]}},"type":"object","required":["item_id","item_code","item_status","already_done"],"title":"OpenTransitionItemOut","description":"처리 후 상품 1건의 현재 상태입니다."},"OpenTransitionRequest":{"properties":{"item_ids":{"items":{"type":"string"},"type":"array","maxItems":200,"minItems":1,"title":"Item Ids","description":"처리할 주문 상품의 고유 ID(UUID) 목록입니다. 주문 조회 응답의 `items[].item_id` 값을 넣습니다. 1개 이상 200개 이하이며, 같은 값을 두 번 넣으면 422로 거절됩니다. 한 주문의 일부 상품만 처리할 수 있습니다.","examples":[["0f8b7c21-4d3e-4a55-9b16-2c7d8e9f0a1b"]]}},"type":"object","required":["item_ids"],"title":"OpenTransitionRequest","description":"발주확인·배송완료 처리 요청입니다."},"OpenTransitionResultOut":{"properties":{"order_no":{"type":"string","title":"Order No","description":"처리한 주문의 번호입니다.","examples":["VR20260826-0000001"]},"order_status":{"type":"string","title":"Order Status","description":"처리 후 주문 전체의 상태입니다. 다른 셀러의 상품 상태도 함께 반영된 값입니다.","examples":["shipping"]},"updated_at":{"type":"string","format":"date-time","title":"Updated At","description":"처리 후 주문의 마지막 변경 시각(UTC)입니다.","examples":["2026-08-26T05:22:10.884231Z"]},"items":{"items":{"$ref":"#/components/schemas/OpenTransitionItemOut"},"type":"array","title":"Items","description":"요청한 상품들의 처리 후 상태입니다."}},"type":"object","required":["order_no","order_status","updated_at","items"],"title":"OpenTransitionResultOut","description":"주문 처리(발주확인·송장 등록·배송완료)의 결과입니다. 수취인·주소 등 개인정보는 담지 않으므로,\n송장 출력용 배송지가 필요하면 주문 조회 API를 사용해주세요."},"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"}},"securitySchemes":{"X-Api-Key":{"type":"apiKey","description":"셀러가 파트너센터(설정 > API 연동)에서 발급한 API Key를 그대로 넣습니다. 실서비스 키는 `vpk_live_`, 개발(dev) 환경 키는 `vpk_test_`로 시작합니다 — 환경이 다른 키를 보내면 401(`INVALID_API_KEY`)로 거절됩니다. 예: `vpk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX`","in":"header","name":"X-Api-Key"}}},"tags":[{"name":"주문","description":"결제가 완료된 주문을 조회하고 발주확인 → 송장 등록(발송) → 배송완료 순서로 처리합니다. 결제 전 주문은 어떤 방법으로도 조회되지 않으며, 응답에는 요청한 키의 셀러 상품만 담깁니다."},{"name":"클레임","description":"취소(cancel)·반품(return)·교환(exchange) 신청을 조회하고 처리합니다. 지금 어떤 처리를 호출할 수 있는지는 조회 응답의 `available_actions`가 알려 줍니다."},{"name":"상품 문의","description":"셀러 상품에 달린 고객 문의를 조회하고 답변을 등록합니다."}]}