{"openapi":"3.1.0","info":{"title":"Pepper Public API","version":"1.0.0","description":"AI 에이전트가 한국 오프라인 매장의 배달·픽업 주문과 방문 예약을 실행하는 공개 API. 금액은 정수 원, 시각은 ISO 8601 +09:00. 쓰기 요청은 Idempotency-Key 필수. 같은 기능을 MCP(POST /mcp)와 A2A(/.well-known/agent-card.json)로도 제공한다."},"servers":[{"url":"https://api.pepper.ai.kr"}],"tags":[{"name":"stores"},{"name":"orders"},{"name":"pickup"},{"name":"reservations"},{"name":"payments"},{"name":"links"},{"name":"owner-auth"}],"paths":{"/v1/stores":{"get":{"operationId":"listStores","summary":"공개 매장 목록","tags":["stores"],"security":[],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","pattern":"^str_[A-Za-z0-9_]{1,64}$"}},{"name":"q","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":40}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/stores/{storeRef}":{"get":{"operationId":"getStore","summary":"매장 프로필(ETag)","tags":["stores"],"security":[],"parameters":[{"name":"storeRef","in":"path","required":true,"schema":{"type":"string","pattern":"^(str_[A-Za-z0-9_]{1,64}|[a-z0-9-]{1,64})$"}},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"ETag 일치"},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/stores/{storeRef}/menu":{"get":{"operationId":"getMenu","summary":"구조화 메뉴(ETag)","tags":["stores"],"security":[],"parameters":[{"name":"storeRef","in":"path","required":true,"schema":{"type":"string","pattern":"^(str_[A-Za-z0-9_]{1,64}|[a-z0-9-]{1,64})$"}},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"304":{"description":"ETag 일치"},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/phone-tokens":{"post":{"operationId":"issuePhoneToken","summary":"전화번호 토큰 발급(어테스테이션)","tags":["orders"],"security":[{"agentKey":[]}],"x-pepper-scope":"order:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"attestation":{"type":"string","minLength":20,"maxLength":4096},"agent_user_ref":{"type":"string","maxLength":100}},"required":["attestation"],"additionalProperties":false}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/stores/{storeId}/delivery-quotes":{"post":{"operationId":"quoteDelivery","summary":"배달 견적","tags":["orders"],"security":[{"agentKey":[]}],"x-pepper-scope":"store:read","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"object","properties":{"road":{"type":"string","minLength":4,"maxLength":200},"detail":{"default":"","type":"string","maxLength":100},"zip":{"type":"string","pattern":"^\\d{5}$"}},"required":["road","zip"],"additionalProperties":false},"items_amount":{"default":0,"type":"integer","minimum":0,"maximum":10000000}},"required":["address"],"additionalProperties":false}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/stores/{storeId}/cart/price":{"post":{"operationId":"priceCart","summary":"장바구니 서버 금액","tags":["orders"],"security":[{"agentKey":[]}],"x-pepper-scope":"store:read","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"menu_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"qty":{"type":"integer","minimum":1,"maximum":99},"options":{"default":[],"maxItems":20,"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"option_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"qty":{"type":"number","const":1}},"required":["group_id","option_id"],"additionalProperties":false}}},"required":["menu_id","qty"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/stores/{storeId}/orders/validate":{"post":{"operationId":"validateOrder","summary":"주문 검증(부작용 없음)","tags":["orders"],"security":[{"agentKey":[]}],"x-pepper-scope":"order:write","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"fulfillment":{"type":"string","const":"delivery"},"delivery":{"type":"object","properties":{"quote_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"address":{"type":"object","properties":{"road":{"type":"string","minLength":4,"maxLength":200},"detail":{"default":"","type":"string","maxLength":100},"zip":{"type":"string","pattern":"^\\d{5}$"}},"required":["road","zip"],"additionalProperties":false}},"required":["address"],"additionalProperties":false},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"menu_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"qty":{"type":"integer","minimum":1,"maximum":99},"options":{"default":[],"maxItems":20,"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"option_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"qty":{"type":"number","const":1}},"required":["group_id","option_id"],"additionalProperties":false}}},"required":["menu_id","qty"],"additionalProperties":false}},"contact":{"default":{},"type":"object","properties":{"phone_token":{"type":"string","pattern":"^pt_[A-Za-z0-9_]{8,80}$"},"phone":{"type":"string","pattern":"^(\\+82[- ]?)?0?1[016789][- ]?\\d{3,4}[- ]?\\d{4}$"}},"additionalProperties":false},"payment":{"type":"object","properties":{"method":{"type":"string","enum":["onsite","card","kakaopay","tosspay","naverpay"]}},"required":["method"],"additionalProperties":false},"request_note":{"type":"string","maxLength":200},"utensils":{"type":"boolean"},"human_confirmation":{"type":"object","properties":{"confirmed":{"type":"boolean","const":true},"confirmed_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d{1,3})?(\\+09:00|Z)$"},"confirmed_by":{"type":"string","enum":["user"]},"shown_total_amount":{"type":"integer","minimum":0,"maximum":10000000},"shown_summary":{"type":"string","minLength":1,"maxLength":300}},"required":["confirmed","confirmed_at","confirmed_by","shown_total_amount","shown_summary"],"additionalProperties":false},"expected_total_amount":{"type":"integer","minimum":0,"maximum":10000000}},"required":["fulfillment","delivery","items","payment"],"additionalProperties":false},{"type":"object","properties":{"fulfillment":{"type":"string","const":"pickup"},"pickup":{"type":"object","properties":{"slot_hold_id":{"type":"string","pattern":"^hld_[A-Za-z0-9_]{8,64}$"}},"required":["slot_hold_id"],"additionalProperties":false},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"menu_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"qty":{"type":"integer","minimum":1,"maximum":99},"options":{"default":[],"maxItems":20,"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"option_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"qty":{"type":"number","const":1}},"required":["group_id","option_id"],"additionalProperties":false}}},"required":["menu_id","qty"],"additionalProperties":false}},"contact":{"default":{},"type":"object","properties":{"phone_token":{"type":"string","pattern":"^pt_[A-Za-z0-9_]{8,80}$"},"phone":{"type":"string","pattern":"^(\\+82[- ]?)?0?1[016789][- ]?\\d{3,4}[- ]?\\d{4}$"}},"additionalProperties":false},"payment":{"type":"object","properties":{"method":{"type":"string","enum":["onsite","card","kakaopay","tosspay","naverpay"]}},"required":["method"],"additionalProperties":false},"request_note":{"type":"string","maxLength":200},"utensils":{"type":"boolean"},"human_confirmation":{"type":"object","properties":{"confirmed":{"type":"boolean","const":true},"confirmed_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d{1,3})?(\\+09:00|Z)$"},"confirmed_by":{"type":"string","enum":["user"]},"shown_total_amount":{"type":"integer","minimum":0,"maximum":10000000},"shown_summary":{"type":"string","minLength":1,"maxLength":300}},"required":["confirmed","confirmed_at","confirmed_by","shown_total_amount","shown_summary"],"additionalProperties":false},"expected_total_amount":{"type":"integer","minimum":0,"maximum":10000000}},"required":["fulfillment","pickup","items","payment"],"additionalProperties":false}]}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/stores/{storeId}/orders":{"post":{"operationId":"createOrder","summary":"주문 생성(배달·픽업)","tags":["orders"],"security":[{"agentKey":[]}],"x-pepper-scope":"order:write","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"fulfillment":{"type":"string","const":"delivery"},"delivery":{"type":"object","properties":{"quote_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"address":{"type":"object","properties":{"road":{"type":"string","minLength":4,"maxLength":200},"detail":{"default":"","type":"string","maxLength":100},"zip":{"type":"string","pattern":"^\\d{5}$"}},"required":["road","zip"],"additionalProperties":false}},"required":["address"],"additionalProperties":false},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"menu_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"qty":{"type":"integer","minimum":1,"maximum":99},"options":{"default":[],"maxItems":20,"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"option_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"qty":{"type":"number","const":1}},"required":["group_id","option_id"],"additionalProperties":false}}},"required":["menu_id","qty"],"additionalProperties":false}},"contact":{"default":{},"type":"object","properties":{"phone_token":{"type":"string","pattern":"^pt_[A-Za-z0-9_]{8,80}$"},"phone":{"type":"string","pattern":"^(\\+82[- ]?)?0?1[016789][- ]?\\d{3,4}[- ]?\\d{4}$"}},"additionalProperties":false},"payment":{"type":"object","properties":{"method":{"type":"string","enum":["onsite","card","kakaopay","tosspay","naverpay"]}},"required":["method"],"additionalProperties":false},"request_note":{"type":"string","maxLength":200},"utensils":{"type":"boolean"},"human_confirmation":{"type":"object","properties":{"confirmed":{"type":"boolean","const":true},"confirmed_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d{1,3})?(\\+09:00|Z)$"},"confirmed_by":{"type":"string","enum":["user"]},"shown_total_amount":{"type":"integer","minimum":0,"maximum":10000000},"shown_summary":{"type":"string","minLength":1,"maxLength":300}},"required":["confirmed","confirmed_at","confirmed_by","shown_total_amount","shown_summary"],"additionalProperties":false},"expected_total_amount":{"type":"integer","minimum":0,"maximum":10000000}},"required":["fulfillment","delivery","items","payment"],"additionalProperties":false},{"type":"object","properties":{"fulfillment":{"type":"string","const":"pickup"},"pickup":{"type":"object","properties":{"slot_hold_id":{"type":"string","pattern":"^hld_[A-Za-z0-9_]{8,64}$"}},"required":["slot_hold_id"],"additionalProperties":false},"items":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"menu_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"qty":{"type":"integer","minimum":1,"maximum":99},"options":{"default":[],"maxItems":20,"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"option_id":{"type":"string","pattern":"^[a-z]{2,4}_[A-Za-z0-9_]{1,64}$"},"qty":{"type":"number","const":1}},"required":["group_id","option_id"],"additionalProperties":false}}},"required":["menu_id","qty"],"additionalProperties":false}},"contact":{"default":{},"type":"object","properties":{"phone_token":{"type":"string","pattern":"^pt_[A-Za-z0-9_]{8,80}$"},"phone":{"type":"string","pattern":"^(\\+82[- ]?)?0?1[016789][- ]?\\d{3,4}[- ]?\\d{4}$"}},"additionalProperties":false},"payment":{"type":"object","properties":{"method":{"type":"string","enum":["onsite","card","kakaopay","tosspay","naverpay"]}},"required":["method"],"additionalProperties":false},"request_note":{"type":"string","maxLength":200},"utensils":{"type":"boolean"},"human_confirmation":{"type":"object","properties":{"confirmed":{"type":"boolean","const":true},"confirmed_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d{1,3})?(\\+09:00|Z)$"},"confirmed_by":{"type":"string","enum":["user"]},"shown_total_amount":{"type":"integer","minimum":0,"maximum":10000000},"shown_summary":{"type":"string","minLength":1,"maxLength":300}},"required":["confirmed","confirmed_at","confirmed_by","shown_total_amount","shown_summary"],"additionalProperties":false},"expected_total_amount":{"type":"integer","minimum":0,"maximum":10000000}},"required":["fulfillment","pickup","items","payment"],"additionalProperties":false}]}}}},"responses":{"201":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/orders/{orderId}":{"get":{"operationId":"getOrder","summary":"주문 상태","tags":["orders"],"security":[{"agentKey":[]}],"x-pepper-scope":"order:write","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/orders/{orderId}/cancel":{"post":{"operationId":"cancelOrder","summary":"주문 취소","tags":["orders"],"security":[{"agentKey":[]}],"x-pepper-scope":"order:write","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason_code":{"default":"changed_mind","type":"string","enum":["changed_mind","wrong_order","too_slow","other"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/orders/{orderId}/switch-to-pickup":{"post":{"operationId":"switchOrderToPickup","summary":"배차 실패 시 픽업 전환","tags":["orders"],"security":[{"agentKey":[]}],"x-pepper-scope":"order:write","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/stores/{storeId}/pickup-slots":{"get":{"operationId":"listPickupSlots","summary":"픽업 가능 시각","tags":["pickup"],"security":[{"agentKey":[]}],"x-pepper-scope":"availability:read","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}},{"name":"date","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/stores/{storeId}/slot-holds":{"post":{"operationId":"holdPickupSlot","summary":"픽업 슬롯 120초 홀드","tags":["pickup"],"security":[{"agentKey":[]}],"x-pepper-scope":"order:write","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slot_start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d{1,3})?(\\+09:00|Z)$"}},"required":["slot_start"],"additionalProperties":false}}}},"responses":{"201":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/slot-holds/{holdId}/release":{"post":{"operationId":"releasePickupSlot","summary":"홀드 해제","tags":["pickup"],"security":[{"agentKey":[]}],"x-pepper-scope":"order:write","parameters":[{"name":"holdId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/stores/{storeId}/availability":{"get":{"operationId":"getAvailability","summary":"예약 잔여석","tags":["reservations"],"security":[{"agentKey":[]}],"x-pepper-scope":"availability:read","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}},{"name":"date","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}},{"name":"party","in":"query","required":true,"schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/stores/{storeId}/reservations":{"post":{"operationId":"createReservation","summary":"예약 생성","tags":["reservations"],"security":[{"agentKey":[]}],"x-pepper-scope":"reservation:write","parameters":[{"name":"storeId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"slot_start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d{1,3})?(\\+09:00|Z)$"},"party":{"type":"integer","minimum":1,"maximum":50},"guest":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":30},"phone_token":{"type":"string","pattern":"^pt_[A-Za-z0-9_]{8,80}$"},"phone":{"type":"string","pattern":"^(\\+82[- ]?)?0?1[016789][- ]?\\d{3,4}[- ]?\\d{4}$"}},"required":["name"],"additionalProperties":false},"requests":{"default":[],"maxItems":5,"type":"array","items":{"type":"string","minLength":1,"maxLength":40}},"occasion":{"type":"string","enum":["birthday","anniversary","business","other"]},"human_confirmation":{"type":"object","properties":{"confirmed":{"type":"boolean","const":true},"confirmed_at":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d{1,3})?(\\+09:00|Z)$"},"confirmed_by":{"type":"string","enum":["user"]},"shown_summary":{"type":"string","minLength":1,"maxLength":300}},"required":["confirmed","confirmed_at","confirmed_by","shown_summary"],"additionalProperties":false}},"required":["slot_start","party","guest"],"additionalProperties":false}}}},"responses":{"201":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/reservations/{id}":{"get":{"operationId":"getReservation","summary":"예약 조회","tags":["reservations"],"security":[{"agentKey":[]}],"x-pepper-scope":"reservation:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"modifyReservation","summary":"예약 변경","tags":["reservations"],"security":[{"agentKey":[]}],"x-pepper-scope":"reservation:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"party":{"type":"integer","minimum":1,"maximum":50},"slot_start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d{1,3})?(\\+09:00|Z)$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"cancelReservation","summary":"예약 취소","tags":["reservations"],"security":[{"agentKey":[]}],"x-pepper-scope":"reservation:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason_code":{"default":"changed_mind","type":"string","enum":["changed_mind","schedule","other"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/payments/{paymentId}":{"get":{"operationId":"getPayment","summary":"결제 상태","tags":["payments"],"security":[{"agentKey":[]}],"x-pepper-scope":"order:write","parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z]{3}_[A-Za-z0-9_]{1,64}$"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/payments/by-token/{token}":{"get":{"operationId":"getPaymentByToken","summary":"결제 링크 조회","tags":["payments"],"security":[],"x-pepper-auth":"access token in path (bearer link)","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{20,64}$"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/payments/by-token/{token}/checkout":{"post":{"operationId":"checkoutPayment","summary":"결제창 주소 발급","tags":["payments"],"security":[],"x-pepper-auth":"access token in path (bearer link)","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{20,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/order-status/{token}":{"get":{"operationId":"getOrderByToken","summary":"손님 주문 상태 링크","tags":["links"],"security":[],"x-pepper-auth":"access token in path (bearer link)","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{20,64}$"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/order-status/{token}/cancel":{"post":{"operationId":"cancelOrderByToken","summary":"손님 링크로 취소","tags":["links"],"security":[],"x-pepper-auth":"access token in path (bearer link)","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{20,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason_code":{"default":"changed_mind","type":"string","enum":["changed_mind","wrong_order","too_slow","other"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/order-status/{token}/switch-to-pickup":{"post":{"operationId":"switchToPickupByToken","summary":"손님 링크로 픽업 전환","tags":["links"],"security":[],"x-pepper-auth":"access token in path (bearer link)","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{20,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/reservation-status/{token}":{"get":{"operationId":"getReservationByToken","summary":"손님 예약 링크","tags":["links"],"security":[],"x-pepper-auth":"access token in path (bearer link)","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{20,64}$"}}],"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/reservation-status/{token}/modify":{"post":{"operationId":"modifyReservationByToken","summary":"손님 링크로 예약 변경","tags":["links"],"security":[],"x-pepper-auth":"access token in path (bearer link)","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{20,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"party":{"type":"integer","minimum":1,"maximum":50},"slot_start":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}(:\\d{2})?(\\.\\d{1,3})?(\\+09:00|Z)$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/reservation-status/{token}/cancel":{"post":{"operationId":"cancelReservationByToken","summary":"손님 링크로 예약 취소","tags":["links"],"security":[],"x-pepper-auth":"access token in path (bearer link)","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{20,64}$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason_code":{"default":"changed_mind","type":"string","enum":["changed_mind","schedule","other"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/owner/auth/magic-links":{"post":{"operationId":"requestOwnerMagicLink","summary":"점주 로그인 링크 요청","tags":["owner-auth"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["email"],"additionalProperties":false}}}},"responses":{"202":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}},"/v1/owner/auth/magic-links/consume":{"post":{"operationId":"consumeOwnerMagicLink","summary":"점주 로그인 링크 사용","tags":["owner-auth"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","pattern":"^[A-Za-z0-9_-]{40,64}$"}},"required":["token"],"additionalProperties":false}}}},"responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"agentKey":{"type":"http","scheme":"bearer","description":"에이전트 키 pk_..."}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}},"responses":{"Error":{"description":"오류(§7.6) — code 로 분기, retryable·recovery 를 따른다","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"schemas":{"ErrorCode":{"type":"string","enum":["STORE_NOT_FOUND","STORE_CLOSED","STORE_PAUSED","FULFILLMENT_NOT_SUPPORTED","MENU_ITEM_NOT_FOUND","OPTION_INVALID","ITEM_SOLD_OUT","PRICE_CHANGED","VALIDATION_FAILED","ADDRESS_INVALID","OUT_OF_DELIVERY_AREA","MIN_ORDER_NOT_MET","PARTY_TOO_LARGE","LEAD_TIME_NOT_MET","MAX_DAYS_EXCEEDED","PICKUP_SLOT_UNAVAILABLE","SLOT_HOLD_EXPIRED","SLOT_UNAVAILABLE","CAPACITY_FULL","RESERVATION_CLOSED","WAITLIST_FULL","PAYMENT_DECLINED","PAYMENT_TIMEOUT","DEPOSIT_REQUIRED","PAYMENT_ALREADY_COMPLETED","REFUND_FAILED","PAYMENT_METHOD_UNAVAILABLE","DISPATCH_UNAVAILABLE","DISPATCH_CANCELED","DUPLICATE_ORDER","IDEMPOTENCY_KEY_REUSED","IDEMPOTENCY_IN_PROGRESS","ORDER_STATE_CONFLICT","CANCEL_NOT_ALLOWED","RESERVATION_NOT_MODIFIABLE","SOURCE_OWNED_EXTERNALLY","AGENT_UNAUTHORIZED","AGENT_SCOPE_DENIED","AGENT_PHONE_ATTESTATION_REQUIRED","AGENT_SUSPENDED","RATE_LIMITED","UPSTREAM_UNAVAILABLE","INTERNAL_ERROR","NOT_FOUND","CONNECTOR_AUTH_FAILED","CONNECTOR_IP_DENIED","CONNECTOR_SCOPE_DENIED","CONNECTOR_RATE_LIMITED","CONNECTOR_SCHEMA_UNSUPPORTED","CONNECTOR_BODY_TOO_LARGE","EXTERNAL_ID_UNMAPPED","EXTERNAL_ID_CONFLICT","CATALOG_VERSION_STALE","CAPACITY_OVERCOMMITTED","DELIVERY_ALREADY_ACKED","EXTERNAL_SYSTEM_UNAVAILABLE"]},"ErrorBody":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","user_message_ko","retryable","details","recovery","request_id","docs"],"properties":{"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string"},"user_message_ko":{"type":"string"},"retryable":{"type":"boolean"},"details":{"type":"object"},"recovery":{"type":"array","items":{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["try_slot","add_items","switch_fulfillment","change_party","use_onsite","retry","contact_store","reuse_order"]}}}},"request_id":{"type":["string","null"]},"docs":{"type":"string"}}}}}}}}