{"openapi":"3.1.0","info":{"title":"PODIZ 파트너 API","version":"1.2.0","description":"공급사가 발급한 비밀 키로 PODIZ 제품을 읽어 파트너 상품 번호와 연결하고, 고객이 편집기에서 만든 디자인을 조회하고, 결제된 주문을 PODIZ 주문함으로 보내 제작 상태·송장을 읽는 API예요. 문서: https://www.podiz.co.kr/developers/partner-api"},"servers":[{"url":"https://www.podiz.co.kr/api/partner/v1","description":"PODIZ"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"connection","description":"연결 확인"},{"name":"products","description":"제품"},{"name":"links","description":"상품 연결"},{"name":"designs","description":"디자인"},{"name":"orders","description":"주문"}],"paths":{"/me":{"get":{"operationId":"getMe","summary":"연결·키 확인","description":"이 비밀 키의 연결(이름·공개 키·사이트 주소·디자인 보관 일수)과 공급사 이름, 살아 있는 키를 돌려줘요. 키를 처음 받았을 때 서버에서 한 번 불러 확인하세요.","tags":["connection"],"responses":{"200":{"description":"연결","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Me"}}},"example":{"data":{"connection":{"id":"8efafd80-c2d0-43b0-83fe-fb7a902fc799","name":"ODIZ 견적","status":"active","publishable_key":"podiz_pk_8efafd80c2d043b083fefb7a902fc799","domains":["https://shop.example.com"],"design_ttl_days":90,"connected_at":"2026-10-14T01:00:00Z"},"supplier":{"name":"에이프린트"},"key":{"id":"069cd70a-b9cb-4a6e-bdbb-8d5540419814","name":"ODIZ 운영 서버"},"keys":[{"id":"069cd70a-b9cb-4a6e-bdbb-8d5540419814","name":"ODIZ 운영 서버","hint":"a1b2","created_at":"2026-10-14T01:00:00Z","last_used_at":"2026-10-14T01:05:00Z"}]}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/products":{"get":{"operationId":"listProducts","summary":"제품 목록","description":"이 공급사가 게시한 제품을 이름 순으로 돌려줘요. 상품을 연결할 때 고를 목록이에요. 색상·사이즈·품목 코드·인쇄 위치가 함께 와요.","tags":["products"],"parameters":[{"name":"page","in":"query","required":false,"description":"쪽 (1부터)","schema":{"type":"integer","minimum":1,"default":1},"example":1},{"name":"per_page","in":"query","required":false,"description":"쪽마다 (1 ~ 100, 기본 20)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"example":20},{"name":"q","in":"query","required":false,"description":"이름 검색","schema":{"type":"string","maxLength":100},"example":"티셔츠"}],"responses":{"200":{"description":"제품 쪽","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProductPage"}}},"example":{"data":{"products":[{"id":"c3b25e5b-f222-43fd-a615-b5c72a978af9","name":"반팔 라운드 티셔츠","status":"published","product_mode":"mockup","base_price":8000,"thumbnail_url":"https://cdn.example.com/mockups/tshirt-front.webp","updated_at":"2026-10-13T09:00:00Z","colors":[{"id":"1e48f712-8351-4682-b38f-983ce5bf5ba7","name":"화이트","hex":"#FFFFFF","available":true},{"id":"b6ca129a-59c8-4527-8cfe-4f78c4b8ead5","name":"블랙","hex":"#111111","available":true}],"sizes":[{"id":"fb189095-a238-48e4-b82e-5b255eca88ae","name":"M","extra_price":0,"available":true},{"id":"17de7f5a-0d2f-4550-a261-afed17ca0cf0","name":"L","extra_price":1000,"available":true}],"variants":[{"code":"PL-064d02c3d65c40f1a97d1f20e450d73c","color_id":"1e48f712-8351-4682-b38f-983ce5bf5ba7","size_id":"fb189095-a238-48e4-b82e-5b255eca88ae","available":true},{"code":"PL-10ef6ee5a7164ed9ac9b3e8fe1f47753","color_id":"1e48f712-8351-4682-b38f-983ce5bf5ba7","size_id":"17de7f5a-0d2f-4550-a261-afed17ca0cf0","available":true},{"code":"PL-8f4a4da67c7c4000866499fbd6ac33f8","color_id":"b6ca129a-59c8-4527-8cfe-4f78c4b8ead5","size_id":"fb189095-a238-48e4-b82e-5b255eca88ae","available":true},{"code":"PL-1b39af989ba646078eff5d34757a3ce2","color_id":"b6ca129a-59c8-4527-8cfe-4f78c4b8ead5","size_id":"17de7f5a-0d2f-4550-a261-afed17ca0cf0","available":false}],"print_areas":[{"id":"83bbf205-41ec-4881-9d9f-bbe9a6d49d19","key":"front","name":"앞면","width_mm":300,"height_mm":400,"extra_price":0}],"linked_product_nos":[1000000015]}],"page":1,"per_page":20,"total":1}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/products/{product_id}":{"get":{"operationId":"getProduct","summary":"제품 하나","description":"이 공급사의 게시중·일시중지 제품 하나. 다른 공급사 제품이나 게시 전 제품은 404예요.","tags":["products"],"parameters":[{"name":"product_id","in":"path","required":true,"description":"PODIZ 제품 id","schema":{"type":"string","format":"uuid"},"example":"c3b25e5b-f222-43fd-a615-b5c72a978af9"}],"responses":{"200":{"description":"제품","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Product"}}},"example":{"data":{"id":"c3b25e5b-f222-43fd-a615-b5c72a978af9","name":"반팔 라운드 티셔츠","status":"published","product_mode":"mockup","base_price":8000,"thumbnail_url":"https://cdn.example.com/mockups/tshirt-front.webp","updated_at":"2026-10-13T09:00:00Z","colors":[{"id":"1e48f712-8351-4682-b38f-983ce5bf5ba7","name":"화이트","hex":"#FFFFFF","available":true},{"id":"b6ca129a-59c8-4527-8cfe-4f78c4b8ead5","name":"블랙","hex":"#111111","available":true}],"sizes":[{"id":"fb189095-a238-48e4-b82e-5b255eca88ae","name":"M","extra_price":0,"available":true},{"id":"17de7f5a-0d2f-4550-a261-afed17ca0cf0","name":"L","extra_price":1000,"available":true}],"variants":[{"code":"PL-064d02c3d65c40f1a97d1f20e450d73c","color_id":"1e48f712-8351-4682-b38f-983ce5bf5ba7","size_id":"fb189095-a238-48e4-b82e-5b255eca88ae","available":true},{"code":"PL-10ef6ee5a7164ed9ac9b3e8fe1f47753","color_id":"1e48f712-8351-4682-b38f-983ce5bf5ba7","size_id":"17de7f5a-0d2f-4550-a261-afed17ca0cf0","available":true},{"code":"PL-8f4a4da67c7c4000866499fbd6ac33f8","color_id":"b6ca129a-59c8-4527-8cfe-4f78c4b8ead5","size_id":"fb189095-a238-48e4-b82e-5b255eca88ae","available":true},{"code":"PL-1b39af989ba646078eff5d34757a3ce2","color_id":"b6ca129a-59c8-4527-8cfe-4f78c4b8ead5","size_id":"17de7f5a-0d2f-4550-a261-afed17ca0cf0","available":false}],"print_areas":[{"id":"83bbf205-41ec-4881-9d9f-bbe9a6d49d19","key":"front","name":"앞면","width_mm":300,"height_mm":400,"extra_price":0}],"linked_product_nos":[1000000015]}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/links":{"get":{"operationId":"listLinks","summary":"연결한 상품 목록","description":"이 연결에서 연결 중인 파트너 상품 번호를 번호 순으로 돌려줘요.","tags":["links"],"responses":{"200":{"description":"연결 목록","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/LinkList"}}},"example":{"data":{"links":[{"external_product_no":1000000015,"product":{"id":"c3b25e5b-f222-43fd-a615-b5c72a978af9","name":"반팔 라운드 티셔츠","status":"published"},"name":"단체 티셔츠 (견적)","code":"ODZ-TEE-01","variants":4,"created_at":"2026-10-14T01:20:00Z","updated_at":"2026-10-14T01:20:00Z"}]}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/links/{external_product_no}":{"get":{"operationId":"getLink","summary":"상품 연결 하나","description":"그 파트너 상품 번호의 연결. 연결하지 않은 번호는 404예요.","tags":["links"],"parameters":[{"name":"external_product_no","in":"path","required":true,"description":"파트너 상품 번호","schema":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"파트너 상품 번호 (1 ~ 9007199254740991)"},"example":1000000015}],"responses":{"200":{"description":"연결","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Link"}}},"example":{"data":{"external_product_no":1000000015,"product":{"id":"c3b25e5b-f222-43fd-a615-b5c72a978af9","name":"반팔 라운드 티셔츠","status":"published"},"name":"단체 티셔츠 (견적)","code":"ODZ-TEE-01","variants":4,"created_at":"2026-10-14T01:20:00Z","updated_at":"2026-10-14T01:20:00Z"}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}},"put":{"operationId":"putLink","summary":"상품 연결하기","description":"파트너 상품 번호에 PODIZ 제품을 연결해요(멱등 — 다시 불러도 같아요). 품목(색상 × 사이즈)은 PODIZ가 제품의 모든 변형으로 맞추니 고를 것이 없어요. 제품에 색상·사이즈를 더하면 다시 불러 주세요(매일 한 번 저절로도 맞춰요). 이름·코드는 받은 값으로 바꾸고 빼면 비워요. 기다리는 디자인이 있는 번호를 다른 제품으로 바꾸면 409 LINK_IN_USE예요.","tags":["links"],"parameters":[{"name":"external_product_no","in":"path","required":true,"description":"파트너 상품 번호","schema":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"파트너 상품 번호 (1 ~ 9007199254740991)"},"example":1000000015}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkInput"},"example":{"product_id":"c3b25e5b-f222-43fd-a615-b5c72a978af9","name":"단체 티셔츠 (견적)","code":"ODZ-TEE-01"}}}},"responses":{"200":{"description":"이미 연결된 번호 — 제품·이름·코드를 맞췄어요","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Link"}}},"example":{"data":{"external_product_no":1000000015,"product":{"id":"c3b25e5b-f222-43fd-a615-b5c72a978af9","name":"반팔 라운드 티셔츠","status":"published"},"name":"단체 티셔츠 (견적)","code":"ODZ-TEE-01","variants":4,"created_at":"2026-10-14T01:20:00Z","updated_at":"2026-10-14T01:20:00Z"}}}}},"201":{"description":"새로 연결했어요 (해제했던 번호를 다시 포함)","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Link"}}},"example":{"data":{"external_product_no":1000000015,"product":{"id":"c3b25e5b-f222-43fd-a615-b5c72a978af9","name":"반팔 라운드 티셔츠","status":"published"},"name":"단체 티셔츠 (견적)","code":"ODZ-TEE-01","variants":4,"created_at":"2026-10-14T01:20:00Z","updated_at":"2026-10-14T01:20:00Z"}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"409":{"description":"PRODUCT_UNAVAILABLE · LINK_IN_USE","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"PRODUCT_UNAVAILABLE":{"summary":"게시하지 않은 제품을 연결하려 했어요","value":{"error":{"code":"PRODUCT_UNAVAILABLE","message":"게시하지 않은 제품은 연결할 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}},"LINK_IN_USE":{"summary":"기다리는 디자인(확정·만료 전)이 있는 번호를 다른 제품으로 바꾸려 했어요","value":{"error":{"code":"LINK_IN_USE","message":"주문을 기다리는 디자인이 있는 상품 번호라 다른 제품으로 바꿀 수 없어요. 새 상품 번호로 연결해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"415":{"description":"UNSUPPORTED_MEDIA_TYPE","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNSUPPORTED_MEDIA_TYPE":{"summary":"본문이 JSON이 아니에요","value":{"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"본문은 JSON으로 보내 주세요 (content-type: application/json).","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}},"delete":{"operationId":"deleteLink","summary":"상품 연결 해제","description":"연결을 해제해요. 이미 만든 디자인·주문은 그대로예요. 연결하지 않은 번호는 404예요.","tags":["links"],"parameters":[{"name":"external_product_no","in":"path","required":true,"description":"파트너 상품 번호","schema":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"파트너 상품 번호 (1 ~ 9007199254740991)"},"example":1000000015}],"responses":{"204":{"description":"해제했어요 (본문 없음)","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/designs/{design_no}":{"get":{"operationId":"getDesign","summary":"디자인 조회","description":"고객이 편집기에서 받은 디자인 번호로 미리보기·제품·색상·디자인한 인쇄 위치·보관 기한·인쇄 파일 요청 시각을 돌려줘요. 견적은 이것으로 내요. 주문됐거나 인쇄 파일을 요청한 디자인은 만료가 없어 expires_at이 null이에요. 다른 연결의 번호는 404예요.","tags":["designs"],"parameters":[{"name":"design_no","in":"path","required":true,"description":"디자인 번호 (대소문자·하이픈 무시)","schema":{"type":"string"},"example":"PL-7K2M9Q4XHAA"}],"responses":{"200":{"description":"디자인","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Design"}}},"example":{"data":{"design_no":"PL-7K2M9Q4XHAA","status":"finalized","external_product_no":1000000015,"product":{"id":"c3b25e5b-f222-43fd-a615-b5c72a978af9","name":"반팔 라운드 티셔츠"},"color":{"id":"1e48f712-8351-4682-b38f-983ce5bf5ba7","name":"화이트","hex":"#FFFFFF"},"areas":[{"key":"front","name":"앞면","width_mm":300,"height_mm":400}],"preview_url":"https://www.pod-labs.co.kr/api/embed/partner/design-preview?k=podiz_pk_8efafd80c2d043b083fefb7a902fc799&code=PL-7K2M9Q4XHAA","finalized_at":"2026-10-14T02:05:00Z","expires_at":"2027-01-12T02:05:00Z","ordered_at":null,"print_requested_at":null,"orders":[],"source_design_no":null}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/designs/{design_no}/extend":{"post":{"operationId":"extendDesign","summary":"디자인 보관 연장","description":"견적이 길어질 때 보관 기한을 오늘부터 보관 일수만큼 늘려요(확정 + 365일까지, 줄지 않아요). 본문은 비우거나 {}. 주문됐거나 인쇄 파일을 요청한 디자인은 만료가 없어 expires_at이 null이고, 이미 만료됐으면 410이에요.","tags":["designs"],"parameters":[{"name":"design_no","in":"path","required":true,"description":"디자인 번호 (대소문자·하이픈 무시)","schema":{"type":"string"},"example":"PL-7K2M9Q4XHAA"}],"responses":{"200":{"description":"새 보관 기한","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/DesignExtension"}}},"example":{"data":{"design_no":"PL-7K2M9Q4XHAA","status":"finalized","expires_at":"2027-01-14T03:00:00Z"}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"410":{"description":"DESIGN_EXPIRED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"DESIGN_EXPIRED":{"summary":"보관 기한이 지난 디자인을 연장하려 했어요","value":{"error":{"code":"DESIGN_EXPIRED","message":"보관 기간이 지난 디자인이에요. 고객이 다시 디자인해야 해요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"415":{"description":"UNSUPPORTED_MEDIA_TYPE","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNSUPPORTED_MEDIA_TYPE":{"summary":"본문이 JSON이 아니에요","value":{"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"본문은 JSON으로 보내 주세요 (content-type: application/json).","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/designs/{design_no}/print-files":{"post":{"operationId":"requestPrintFiles","summary":"인쇄 파일 요청","description":"주문을 보내지 않는(견적용) 연동에서 이 디자인의 인쇄 파일을 요청해요. 공급사가 PODIZ 콘솔 [인쇄 파일 요청]에서 만들면(화면을 열어 두면 자동으로) GET으로 내려받아요. 같은 요청을 다시 보내도 같고(처음 요청 시각 그대로), 요청한 디자인은 만료되지 않아요. 주문된 디자인도 되고, 주문함에서 이미 만들었으면 바로 ready예요. 본문은 비우거나 {}. 만료된 디자인은 410이에요.","tags":["designs"],"parameters":[{"name":"design_no","in":"path","required":true,"description":"디자인 번호 (대소문자·하이픈 무시)","schema":{"type":"string"},"example":"PL-7K2M9Q4XHAA"}],"responses":{"200":{"description":"인쇄 파일 상태 (보통 pending)","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PrintFiles"}}},"example":{"data":{"design_no":"PL-7K2M9Q4XHAA","status":"pending","requested_at":"2026-10-14T05:00:00Z","areas":[{"key":"front","name":"앞면","width_mm":300,"height_mm":400,"bleed_mm":2,"dpi":300,"files":[],"missing":["print"]}],"urls_expire_at":null}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"410":{"description":"DESIGN_EXPIRED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"DESIGN_EXPIRED":{"summary":"보관 기한이 지난 디자인을 연장하려 했어요","value":{"error":{"code":"DESIGN_EXPIRED","message":"보관 기간이 지난 디자인이에요. 고객이 다시 디자인해야 해요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"415":{"description":"UNSUPPORTED_MEDIA_TYPE","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNSUPPORTED_MEDIA_TYPE":{"summary":"본문이 JSON이 아니에요","value":{"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"본문은 JSON으로 보내 주세요 (content-type: application/json).","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}},"get":{"operationId":"getPrintFiles","summary":"인쇄 파일 상태·내려받기","description":"디자인한 인쇄 위치마다 만든 파일과 아직 없는 파일을 돌려줘요. ready면 모두 있어요. 파일 주소는 서명 주소라 키 없이 받고, 1시간 뒤 끝나요(urls_expire_at — 지나면 다시 GET). 규격은 PNG(RGBA·dpi 기록·블리드 포함)이고, 칼선형은 칼선 SVG와 (투명 재질이면) 화이트 레이어 PNG도 있어요. 만료된 디자인은 410이에요.","tags":["designs"],"parameters":[{"name":"design_no","in":"path","required":true,"description":"디자인 번호 (대소문자·하이픈 무시)","schema":{"type":"string"},"example":"PL-7K2M9Q4XHAA"}],"responses":{"200":{"description":"인쇄 파일 상태","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/PrintFiles"}}},"example":{"data":{"design_no":"PL-7K2M9Q4XHAA","status":"ready","requested_at":"2026-10-14T05:00:00Z","areas":[{"key":"front","name":"앞면","width_mm":300,"height_mm":400,"bleed_mm":2,"dpi":300,"files":[{"kind":"print","file_name":"PL-7K2M9Q4XHAA_front_300x400mm_300dpi.png","url":"https://files.example.supabase.co/storage/v1/object/sign/channel-print-files/…?token=…&download=PL-7K2M9Q4XHAA_front_300x400mm_300dpi.png","width_px":3591,"height_px":4772}],"missing":[]}],"urls_expire_at":"2026-10-14T06:10:00Z"}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"410":{"description":"DESIGN_EXPIRED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"DESIGN_EXPIRED":{"summary":"보관 기한이 지난 디자인을 연장하려 했어요","value":{"error":{"code":"DESIGN_EXPIRED","message":"보관 기간이 지난 디자인이에요. 고객이 다시 디자인해야 해요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/designs/{design_no}/assets":{"get":{"operationId":"listDesignAssets","summary":"고객 원본 이미지","description":"고객이 편집기에 올린 원본 이미지를 내려받기 주소(서명 1시간)·크기·쓴 인쇄 위치와 함께 돌려줘요. 바로 받을 수 있어요(공급사가 만들 필요 없음). 글자·클립아트는 원본 파일이 아니라 디자인 데이터라 없어요. 만료된 디자인은 원본이 지워져 410이에요.","tags":["designs"],"parameters":[{"name":"design_no","in":"path","required":true,"description":"디자인 번호 (대소문자·하이픈 무시)","schema":{"type":"string"},"example":"PL-7K2M9Q4XHAA"}],"responses":{"200":{"description":"원본 이미지","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/DesignAssets"}}},"example":{"data":{"design_no":"PL-7K2M9Q4XHAA","assets":[{"id":"2c8e4f0a-7b1d-4c3e-9f5a-6d2b8e1c4a70","file_name":"PL-7K2M9Q4XHAA_원본_1.png","mime":"image/png","width_px":2400,"height_px":2400,"bytes":1834221,"areas":["front"],"url":"https://files.example.supabase.co/storage/v1/object/sign/customer-assets/…?token=…&download=PL-7K2M9Q4XHAA_%EC%9B%90%EB%B3%B8_1.png"}],"urls_expire_at":"2026-10-14T06:10:00Z"}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"410":{"description":"DESIGN_EXPIRED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"DESIGN_EXPIRED":{"summary":"보관 기한이 지난 디자인을 연장하려 했어요","value":{"error":{"code":"DESIGN_EXPIRED","message":"보관 기간이 지난 디자인이에요. 고객이 다시 디자인해야 해요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/orders":{"post":{"operationId":"createOrder","summary":"주문 보내기","description":"결제된 주문을 PODIZ 주문함으로 보내요. 줄마다 디자인 번호·사이즈(품목 코드)·수량 — 한 디자인을 여러 사이즈로 나눠 보내면 돼요. 주문 번호가 열쇠예요: 같은 줄로 다시 보내면 200(replayed), 다른 줄이면 409 ORDER_EXISTS. 보낸 주문은 바꾸지 않아요(취소만). 수령인·주문자 정보는 받지 않아요 — 배송지는 파트너 앱에서 확인해요.","tags":["orders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderInput"},"example":{"order_id":"Q20261014-0001","paid_at":"2026-10-14T12:00:00+09:00","items":[{"item_id":"1","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-064d02c3d65c40f1a97d1f20e450d73c","quantity":20},{"item_id":"2","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-10ef6ee5a7164ed9ac9b3e8fe1f47753","quantity":10}]}}}},"responses":{"200":{"description":"같은 주문을 다시 보냈어요 (그대로)","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/OrderResult"}}},"example":{"data":{"order":{"order_id":"Q20261014-0001","status":"received","hold_reason":null,"ordered_at":"2026-10-14T03:00:00Z","paid_at":"2026-10-14T03:00:00Z","shipped_at":null,"cancelled_at":null,"shipment":null,"items":[{"item_id":"1","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-064d02c3d65c40f1a97d1f20e450d73c","color":"화이트","size":"M","quantity":20,"status":"active"},{"item_id":"2","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-10ef6ee5a7164ed9ac9b3e8fe1f47753","color":"화이트","size":"L","quantity":10,"status":"active"}],"updated_at":"2026-10-14T03:00:00Z"},"replayed":true}}}}},"201":{"description":"주문함에 들어갔어요","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/OrderResult"}}},"example":{"data":{"order":{"order_id":"Q20261014-0001","status":"received","hold_reason":null,"ordered_at":"2026-10-14T03:00:00Z","paid_at":"2026-10-14T03:00:00Z","shipped_at":null,"cancelled_at":null,"shipment":null,"items":[{"item_id":"1","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-064d02c3d65c40f1a97d1f20e450d73c","color":"화이트","size":"M","quantity":20,"status":"active"},{"item_id":"2","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-10ef6ee5a7164ed9ac9b3e8fe1f47753","color":"화이트","size":"L","quantity":10,"status":"active"}],"updated_at":"2026-10-14T03:00:00Z"},"replayed":false}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"409":{"description":"ORDER_EXISTS","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ORDER_EXISTS":{"summary":"같은 주문 번호에 다른 줄을 보냈어요 (같은 줄이면 200 재전송)","value":{"error":{"code":"ORDER_EXISTS","message":"같은 주문 번호로 내용이 다른 주문을 이미 받았어요. 주문 번호를 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"415":{"description":"UNSUPPORTED_MEDIA_TYPE","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNSUPPORTED_MEDIA_TYPE":{"summary":"본문이 JSON이 아니에요","value":{"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"본문은 JSON으로 보내 주세요 (content-type: application/json).","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"422":{"description":"ORDER_ITEMS_INVALID","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ORDER_ITEMS_INVALID":{"summary":"주문 줄이 틀렸어요 — details에 [{index, item_id, code}]","value":{"error":{"code":"ORDER_ITEMS_INVALID","message":"주문 줄 중 맞지 않는 것이 있어요. 줄마다 이유를 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","details":[{"index":0,"item_id":"1","code":"DESIGN_EXPIRED"}]}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}},"get":{"operationId":"listOrders","summary":"바뀐 주문 목록","description":"주문을 수정 순(오래된 것부터)으로 돌려줘요. 받은 next_cursor를 저장해 두고 다음에 그 커서로 부르면 그 뒤에 바뀐 주문(제작 시작·보류·발송·취소)만 와요 — 상태·송장을 주기적으로 맞출 때 쓰세요. has_more면 곧바로 다음 쪽을 불러요.","tags":["orders"],"parameters":[{"name":"cursor","in":"query","required":false,"description":"앞 응답의 next_cursor (처음엔 빼요)","schema":{"type":"string","maxLength":200},"example":"WyIyMDI2LTEwLTE0VDAzOjAwOjAwLjAwMFoiLCIyZjFjOGEzZS02YjBkLTRmNWUtOWE3Yy0zZDJiMWUwZjlhODQiXQ"},{"name":"limit","in":"query","required":false,"description":"쪽마다 (1 ~ 100, 기본 50)","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"example":50}],"responses":{"200":{"description":"주문 쪽","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/OrderPage"}}},"example":{"data":{"orders":[{"order_id":"Q20261014-0001","status":"shipped","hold_reason":null,"ordered_at":"2026-10-14T03:00:00Z","paid_at":"2026-10-14T03:00:00Z","shipped_at":"2026-10-16T08:30:00Z","cancelled_at":null,"shipment":{"carrier":{"code":"0006","name":"CJ대한통운"},"tracking_no":"640012345678"},"items":[{"item_id":"1","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-064d02c3d65c40f1a97d1f20e450d73c","color":"화이트","size":"M","quantity":20,"status":"shipped"},{"item_id":"2","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-10ef6ee5a7164ed9ac9b3e8fe1f47753","color":"화이트","size":"L","quantity":10,"status":"shipped"}],"updated_at":"2026-10-16T08:30:00Z"}],"next_cursor":"WyIyMDI2LTEwLTE2VDA4OjMwOjAwLjAwMFoiLCIyZjFjOGEzZS02YjBkLTRmNWUtOWE3Yy0zZDJiMWUwZjlhODQiXQ","has_more":false}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/orders/{order_id}":{"get":{"operationId":"getOrder","summary":"주문 조회","description":"주문 하나의 제작 상태·보류 사유·송장. 공급사가 발송 처리하면 shipment에 택배사·송장번호가 들어와요.","tags":["orders"],"parameters":[{"name":"order_id","in":"path","required":true,"description":"파트너 주문 번호","schema":{"type":"string","pattern":"^[0-9A-Za-z-]{1,40}$"},"example":"Q20261014-0001"}],"responses":{"200":{"description":"주문","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}},"example":{"data":{"order_id":"Q20261014-0001","status":"shipped","hold_reason":null,"ordered_at":"2026-10-14T03:00:00Z","paid_at":"2026-10-14T03:00:00Z","shipped_at":"2026-10-16T08:30:00Z","cancelled_at":null,"shipment":{"carrier":{"code":"0006","name":"CJ대한통운"},"tracking_no":"640012345678"},"items":[{"item_id":"1","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-064d02c3d65c40f1a97d1f20e450d73c","color":"화이트","size":"M","quantity":20,"status":"shipped"},{"item_id":"2","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-10ef6ee5a7164ed9ac9b3e8fe1f47753","color":"화이트","size":"L","quantity":10,"status":"shipped"}],"updated_at":"2026-10-16T08:30:00Z"}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}},"/orders/{order_id}/cancel":{"post":{"operationId":"cancelOrder","summary":"주문 취소","description":"제작을 시작하기 전(접수) 주문만 취소해요 — 다시 불러도 같아요. 제작 중·보류면 409 ORDER_IN_PRODUCTION, 발송 뒤면 409 ORDER_STATUS_LOCKED예요(공급사와 직접 이야기하세요).","tags":["orders"],"parameters":[{"name":"order_id","in":"path","required":true,"description":"파트너 주문 번호","schema":{"type":"string","pattern":"^[0-9A-Za-z-]{1,40}$"},"example":"Q20261014-0001"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelInput"},"example":{"reason":"고객 변심"}}}},"responses":{"200":{"description":"취소한 주문","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Order"}}},"example":{"data":{"order_id":"Q20261014-0001","status":"cancelled","hold_reason":null,"ordered_at":"2026-10-14T03:00:00Z","paid_at":"2026-10-14T03:00:00Z","shipped_at":null,"cancelled_at":"2026-10-14T04:00:00Z","shipment":null,"items":[{"item_id":"1","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-064d02c3d65c40f1a97d1f20e450d73c","color":"화이트","size":"M","quantity":20,"status":"cancelled"},{"item_id":"2","design_no":"PL-7K2M9Q4XHAA","variant_code":"PL-10ef6ee5a7164ed9ac9b3e8fe1f47753","color":"화이트","size":"L","quantity":10,"status":"cancelled"}],"updated_at":"2026-10-14T04:00:00Z"}}}}},"400":{"description":"VALIDATION_FAILED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"VALIDATION_FAILED":{"summary":"본문·주소·질의 값이 틀렸어요 — fields에 칸마다 문구","value":{"error":{"code":"VALIDATION_FAILED","message":"요청 값이 올바르지 않아요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10","fields":{"items[0].quantity":"수량은 1 ~ 100,000 정수예요."}}}}}}}},"401":{"description":"UNAUTHENTICATED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"www-authenticate":{"description":"Bearer","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNAUTHENTICATED":{"summary":"키가 없거나 모르는 키·폐기한 키 (연결을 해제하면 키를 모두 폐기해요)","value":{"error":{"code":"UNAUTHENTICATED","message":"비밀 키가 없거나 맞지 않아요. Authorization: Bearer podiz_sk_… 헤더를 확인해 주세요. 폐기했거나 연결을 해제한 키는 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"403":{"description":"FORBIDDEN","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"FORBIDDEN":{"summary":"공급사 이용이 정지됐어요","value":{"error":{"code":"FORBIDDEN","message":"공급사 이용이 정지돼 API를 쓸 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"404":{"description":"NOT_FOUND","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"NOT_FOUND":{"summary":"이 연결의 제품·연결·디자인·주문이 아니에요 (없는 경로도)","value":{"error":{"code":"NOT_FOUND","message":"찾을 수 없어요. 이 연결의 것인지 확인해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"409":{"description":"ORDER_IN_PRODUCTION · ORDER_STATUS_LOCKED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"ORDER_IN_PRODUCTION":{"summary":"제작을 시작했거나 보류 중인 주문을 취소하려 했어요","value":{"error":{"code":"ORDER_IN_PRODUCTION","message":"이미 제작을 시작한 주문이라 취소할 수 없어요. 공급사에 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}},"ORDER_STATUS_LOCKED":{"summary":"발송한 주문을 취소하려 했어요","value":{"error":{"code":"ORDER_STATUS_LOCKED","message":"발송된 주문은 취소할 수 없어요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"415":{"description":"UNSUPPORTED_MEDIA_TYPE","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"UNSUPPORTED_MEDIA_TYPE":{"summary":"본문이 JSON이 아니에요","value":{"error":{"code":"UNSUPPORTED_MEDIA_TYPE","message":"본문은 JSON으로 보내 주세요 (content-type: application/json).","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"429":{"description":"RATE_LIMITED","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}},"retry-after":{"description":"다시 부를 때까지 초","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"RATE_LIMITED":{"summary":"요청 한도를 넘었어요 — retry-after(초) 뒤 다시","value":{"error":{"code":"RATE_LIMITED","message":"요청이 너무 많아요. retry-after 헤더의 초만큼 기다린 뒤 다시 시도해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}},"500":{"description":"INTERNAL_ERROR","headers":{"x-request-id":{"description":"요청 id (UUID) — 오류 본문의 request_id와 같다","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"examples":{"INTERNAL_ERROR":{"summary":"일시적인 오류 — 계속되면 request_id와 함께 문의","value":{"error":{"code":"INTERNAL_ERROR","message":"일시적인 오류예요. 잠시 뒤 다시 시도해 주세요. 계속되면 요청 id와 함께 문의해 주세요.","request_id":"5b0f3c7e-2d41-4a8e-9a43-1f6c2b7d9e10"}}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"비밀 키 podiz_sk_… — 공급사가 PODIZ 콘솔 [판매 채널 › 파트너 앱 연결]에서 발급해요. 서버에서만 쓰고 브라우저에 넣지 마세요"}},"schemas":{"Me":{"type":"object","description":"이 키의 연결·공급사와 살아 있는 키","required":["connection","supplier","key","keys"],"properties":{"connection":{"type":"object","required":["id","name","status","publishable_key","domains","design_ttl_days","connected_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","description":"공급사가 정한 연결 이름"},"status":{"type":"string","enum":["active","disconnected"]},"publishable_key":{"type":"string","pattern":"^podiz_pk_[0-9a-f]{32}$","description":"공개 키 — 편집기 SDK에 넣는 값 (비밀이 아니다)"},"domains":{"type":"array","items":{"type":"string"},"description":"편집기를 띄울 사이트 출처"},"design_ttl_days":{"type":"integer","description":"디자인 보관 일수 (기본 90)"},"connected_at":{"type":["string","null"],"format":"date-time"}}},"supplier":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}},"key":{"type":"object","description":"이 요청에 쓴 키","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"keys":{"type":"array","description":"살아 있는 키 (원문 없이 끝 4자만)","items":{"type":"object","required":["id","name","hint","created_at","last_used_at"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"hint":{"type":"string","description":"끝 4자"},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":["string","null"],"format":"date-time"}}}}}},"Product":{"type":"object","description":"게시한 제품. 색상·사이즈는 켜 둔 것만(정렬 순), 인쇄 위치는 게시로 잠긴 것만. available은 판매 중인 변형이 있는지","required":["id","name","status","product_mode","base_price","thumbnail_url","updated_at","colors","sizes","variants","print_areas","linked_product_nos"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["published","paused"],"description":"목록은 게시중만, 하나 조회는 일시중지도"},"product_mode":{"type":"string","enum":["mockup","die_cut"],"description":"mockup 사진 목업 · die_cut 칼선형(아크릴 굿즈 등)"},"base_price":{"type":"integer","description":"공급사 기본가 (원 — 참고)"},"thumbnail_url":{"type":["string","null"],"description":"대표 사진 (칼선형은 null)"},"updated_at":{"type":"string","format":"date-time"},"colors":{"type":"array","items":{"type":"object","required":["id","name","hex","available"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"hex":{"type":"string","pattern":"^#[0-9A-Fa-f]{6}$"},"available":{"type":"boolean"}}}},"sizes":{"type":"array","items":{"type":"object","required":["id","name","extra_price","available"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"extra_price":{"type":"integer","description":"사이즈 추가금 (원 — 참고)"},"available":{"type":"boolean"}}}},"variants":{"type":"array","description":"품목 = 색상 × 사이즈. 주문 줄의 variant_code","items":{"type":"object","required":["code","color_id","size_id","available"],"properties":{"code":{"type":"string","pattern":"^PL-[0-9a-f]{32}$","description":"품목 코드 (색상 × 사이즈 — GET /products의 variants.code)"},"color_id":{"type":"string","format":"uuid"},"size_id":{"type":"string","format":"uuid"},"available":{"type":"boolean","description":"켜짐·품절 아님"}}}},"print_areas":{"type":"array","items":{"type":"object","required":["id","key","name","width_mm","height_mm","extra_price"],"properties":{"id":{"type":"string","format":"uuid"},"key":{"type":"string"},"name":{"type":"string"},"width_mm":{"type":"number"},"height_mm":{"type":"number"},"extra_price":{"type":"integer","description":"인쇄 위치 추가금 (원 — 참고)"}}}},"linked_product_nos":{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"파트너 상품 번호 (1 ~ 9007199254740991)"},"description":"이 연결에서 이 제품에 연결한 파트너 상품 번호"}}},"ProductPage":{"type":"object","required":["products","page","per_page","total"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"page":{"type":"integer","minimum":1},"per_page":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer","minimum":0}}},"Link":{"type":"object","description":"파트너 상품 번호 ↔ PODIZ 제품 연결","required":["external_product_no","product","name","code","variants","created_at","updated_at"],"properties":{"external_product_no":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"파트너 상품 번호 (1 ~ 9007199254740991)"},"product":{"type":"object","required":["id","name","status"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"}}},"name":{"type":["string","null"],"description":"파트너 상품 이름 (보낸 그대로)"},"code":{"type":["string","null"],"description":"파트너 상품 코드 (보낸 그대로)"},"variants":{"type":"integer","description":"연결된 품목 수"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"LinkList":{"type":"object","required":["links"],"properties":{"links":{"type":"array","items":{"$ref":"#/components/schemas/Link"}}}},"LinkInput":{"type":"object","required":["product_id"],"properties":{"product_id":{"type":"string","format":"uuid","description":"PODIZ 제품 id (GET /products의 id)"},"name":{"type":["string","null"],"maxLength":250,"description":"파트너 상품 이름 (빼면 비운다)"},"code":{"type":["string","null"],"maxLength":40,"description":"파트너 상품 코드 (빼면 비운다)"}}},"Design":{"type":"object","description":"고객이 편집기에서 확정한 디자인 (견적 디자인은 색상까지 — 사이즈는 주문 줄이 정한다)","required":["design_no","status","external_product_no","product","color","areas","preview_url","finalized_at","expires_at","ordered_at","print_requested_at","orders","source_design_no"],"properties":{"design_no":{"type":"string","pattern":"^PL-[0-9A-HJKMNP-TV-Z]{11}$","description":"디자인 번호 — 받을 때는 대소문자·하이픈을 무시하고, 돌려줄 때는 이 모양"},"status":{"type":"string","enum":["finalized","ordered","expired"],"description":"finalized 확정 · ordered 주문됨(만료 없음) · expired 보관 기한 지남"},"external_product_no":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"파트너 상품 번호 (1 ~ 9007199254740991)"},"product":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}},"color":{"type":["object","null"],"required":["id","name","hex"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"hex":{"type":"string"}}},"areas":{"type":"array","description":"디자인한 인쇄 위치만","items":{"type":"object","required":["key","name","width_mm","height_mm"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"width_mm":{"type":"number"},"height_mm":{"type":"number"}}}},"preview_url":{"type":["string","null"],"description":"미리보기 그림 주소 (키 없이 <img>로 — 만료되면 null)"},"finalized_at":{"type":"string","format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time","description":"보관 기한 — 주문됐거나 인쇄 파일을 요청한 디자인은 null (만료 없음)"},"ordered_at":{"type":["string","null"],"format":"date-time"},"print_requested_at":{"type":["string","null"],"format":"date-time","description":"주문 없이 인쇄 파일을 처음 요청한 시각 (POST /designs/{design_no}/print-files)"},"orders":{"type":"array","items":{"type":"string"},"description":"이 디자인을 쓴 이 연결의 주문 번호"},"source_design_no":{"type":["string","null"],"pattern":"^PL-[0-9A-HJKMNP-TV-Z]{11}$","description":"편집기 SDK 수정하기(openEditor({ designNo }))로 고쳐 만든 디자인이면 연 원본 번호 — 원본은 그대로 남는다"}}},"DesignExtension":{"type":"object","required":["design_no","status","expires_at"],"properties":{"design_no":{"type":"string","pattern":"^PL-[0-9A-HJKMNP-TV-Z]{11}$","description":"디자인 번호 — 받을 때는 대소문자·하이픈을 무시하고, 돌려줄 때는 이 모양"},"status":{"type":"string","enum":["finalized","ordered"]},"expires_at":{"type":["string","null"],"format":"date-time","description":"새 보관 기한 — 주문됐거나 인쇄 파일을 요청한 디자인은 null"}}},"PrintFile":{"type":"object","required":["kind","file_name","url"],"properties":{"kind":{"type":"string","enum":["print","cut","white"],"description":"print 인쇄 파일 PNG · cut 칼선 SVG (칼선형) · white 화이트 레이어 PNG (칼선형 투명 재질)"},"file_name":{"type":"string","description":"내려받기 이름 — {디자인 번호}_{위치 키}_{W}x{H}mm_{dpi}dpi.png · …_칼선.svg · …_화이트.png"},"url":{"type":"string","description":"내려받기 주소 (서명 주소 — 키 없이 GET, urls_expire_at까지)"},"width_px":{"type":"integer","description":"픽셀 크기 (인쇄 파일만 — 블리드 포함)"},"height_px":{"type":"integer","description":"픽셀 크기 (인쇄 파일만 — 블리드 포함)"}}},"PrintFileArea":{"type":"object","required":["key","name","width_mm","height_mm","bleed_mm","dpi","files","missing"],"properties":{"key":{"type":"string"},"name":{"type":"string"},"width_mm":{"type":"number"},"height_mm":{"type":"number"},"bleed_mm":{"type":"number","description":"재단 여유 — 인쇄 파일은 사방으로 이만큼 크다"},"dpi":{"type":"integer"},"files":{"type":"array","items":{"$ref":"#/components/schemas/PrintFile"},"description":"만든 파일"},"missing":{"type":"array","items":{"type":"string","enum":["print","cut","white"]},"description":"아직 없는 파일 — 공급사가 만들면 빈다"}}},"PrintFiles":{"type":"object","description":"디자인의 인쇄 파일 (주문 없이 요청·내려받기 — 공급사가 PODIZ 콘솔에서 만든다)","required":["design_no","status","requested_at","areas","urls_expire_at"],"properties":{"design_no":{"type":"string","pattern":"^PL-[0-9A-HJKMNP-TV-Z]{11}$","description":"디자인 번호 — 받을 때는 대소문자·하이픈을 무시하고, 돌려줄 때는 이 모양"},"status":{"type":"string","enum":["not_requested","pending","ready"],"description":"not_requested 요청 전 · pending 요청됨(또는 주문됨) — 공급사가 만드는 중 · ready 디자인한 위치의 파일이 모두 있음"},"requested_at":{"type":["string","null"],"format":"date-time","description":"처음 요청한 시각"},"areas":{"type":"array","items":{"$ref":"#/components/schemas/PrintFileArea"},"description":"디자인한 인쇄 위치 (위치 순서)"},"urls_expire_at":{"type":["string","null"],"format":"date-time","description":"파일 주소가 끝나는 시각 (1시간 — 지나면 다시 GET). 파일이 없으면 null"}}},"DesignAsset":{"type":"object","required":["id","file_name","mime","width_px","height_px","bytes","areas","url"],"properties":{"id":{"type":"string","format":"uuid"},"file_name":{"type":"string","description":"내려받기 이름 — {디자인 번호}_원본_{순번}.{jpg|png|webp}"},"mime":{"type":"string","enum":["image/jpeg","image/png","image/webp"]},"width_px":{"type":"integer"},"height_px":{"type":"integer"},"bytes":{"type":"integer"},"areas":{"type":"array","items":{"type":"string"},"description":"이 이미지를 쓴 인쇄 위치 키"},"url":{"type":"string","description":"내려받기 주소 (서명 주소 — 키 없이 GET, urls_expire_at까지)"}}},"DesignAssets":{"type":"object","description":"고객이 편집기에 올린 원본 이미지 (글자·클립아트는 원본 파일이 아니라 디자인 데이터라 없다)","required":["design_no","assets","urls_expire_at"],"properties":{"design_no":{"type":"string","pattern":"^PL-[0-9A-HJKMNP-TV-Z]{11}$","description":"디자인 번호 — 받을 때는 대소문자·하이픈을 무시하고, 돌려줄 때는 이 모양"},"assets":{"type":"array","items":{"$ref":"#/components/schemas/DesignAsset"},"description":"올린 순서"},"urls_expire_at":{"type":["string","null"],"format":"date-time","description":"파일 주소가 끝나는 시각 (1시간 — 지나면 다시 GET). 이미지가 없으면 null"}}},"OrderItemInput":{"type":"object","required":["item_id","design_no","quantity"],"properties":{"item_id":{"type":"string","pattern":"^[0-9A-Za-z-]{1,40}$","description":"주문 안에서 겹치지 않는 품목 번호"},"design_no":{"type":"string","pattern":"^PL-[0-9A-HJKMNP-TV-Z]{11}$","description":"디자인 번호 — 받을 때는 대소문자·하이픈을 무시하고, 돌려줄 때는 이 모양"},"variant_code":{"type":"string","pattern":"^PL-[0-9a-f]{32}$","description":"사이즈를 정하는 품목 코드 — 디자인과 같은 제품·색상. 빼면 그 색상의 사이즈가 하나뿐일 때만"},"quantity":{"type":"integer","minimum":1,"maximum":100000}}},"OrderInput":{"type":"object","required":["order_id","items"],"properties":{"order_id":{"type":"string","pattern":"^[0-9A-Za-z-]{1,40}$","description":"파트너 주문 번호 — 같은 번호는 한 주문(멱등 열쇠)"},"ordered_at":{"type":"string","format":"date-time","description":"주문 시각 (빼면 받은 시각)"},"paid_at":{"type":"string","format":"date-time","description":"결제 시각 (빼면 받은 시각)"},"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/OrderItemInput"}}}},"OrderItem":{"type":"object","required":["item_id","design_no","variant_code","color","size","quantity","status"],"properties":{"item_id":{"type":"string","pattern":"^[0-9A-Za-z-]{1,40}$"},"design_no":{"type":"string","pattern":"^PL-[0-9A-HJKMNP-TV-Z]{11}$","description":"디자인 번호 — 받을 때는 대소문자·하이픈을 무시하고, 돌려줄 때는 이 모양"},"variant_code":{"type":"string","pattern":"^PL-[0-9a-f]{32}$","description":"품목 코드 (색상 × 사이즈 — GET /products의 variants.code)"},"color":{"type":["string","null"]},"size":{"type":["string","null"]},"quantity":{"type":"integer","minimum":1},"status":{"type":"string","enum":["active","shipped","cancelled"]}}},"Order":{"type":"object","required":["order_id","status","hold_reason","ordered_at","paid_at","shipped_at","cancelled_at","shipment","items","updated_at"],"properties":{"order_id":{"type":"string","pattern":"^[0-9A-Za-z-]{1,40}$"},"status":{"type":"string","enum":["received","in_production","on_hold","shipped","cancelled"],"description":"접수 · 제작 중 · 보류 · 발송 · 취소"},"hold_reason":{"type":["string","null"],"description":"공급사가 적은 보류 사유"},"ordered_at":{"type":"string","format":"date-time"},"paid_at":{"type":["string","null"],"format":"date-time"},"shipped_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"shipment":{"type":["object","null"],"description":"발송 뒤 택배사·송장번호","required":["carrier","tracking_no"],"properties":{"carrier":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string"},"name":{"type":"string"}}},"tracking_no":{"type":"string"}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItem"}},"updated_at":{"type":"string","format":"date-time"}}},"OrderResult":{"type":"object","required":["order","replayed"],"properties":{"order":{"$ref":"#/components/schemas/Order"},"replayed":{"type":"boolean","description":"같은 주문 번호·같은 줄을 다시 보냈으면 true"}}},"OrderPage":{"type":"object","required":["orders","next_cursor","has_more"],"properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"next_cursor":{"type":["string","null"],"description":"다음에 넣을 커서 (이 쪽의 마지막 주문 자리 — 쪽이 비면 받은 커서 그대로)"},"has_more":{"type":"boolean","description":"true면 곧바로 다음 쪽"}}},"CancelInput":{"type":"object","properties":{"reason":{"type":["string","null"],"maxLength":500,"description":"취소 사유 (기록에만)"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","description":"오류 코드 (오류 표)"},"message":{"type":"string","description":"한국어 문구 — 화면에 그대로 써도 된다"},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"VALIDATION_FAILED — 칸 이름 → 문구 (예 items[0].quantity)"},"details":{"type":"array","description":"ORDER_ITEMS_INVALID — 틀린 줄","items":{"type":"object","required":["index","item_id","code"],"properties":{"index":{"type":"integer","minimum":0},"item_id":{"type":"string"},"code":{"type":"string","enum":["DESIGN_NOT_FOUND","DESIGN_EXPIRED","VARIANT_REQUIRED","VARIANT_MISMATCH"]}}}},"request_id":{"type":"string","format":"uuid","description":"응답 헤더 x-request-id와 같다 — 문의할 때"}}}}}}}}