{"openapi":"3.1.0","info":{"title":"AutoTransPay API","version":"1.0.0","summary":"무통장입금 자동확인 API","description":"은행 입금 알림을 해석해 가맹점 주문과 자동 매칭하고 서명된 웹훅을 보내는 API. 문서: https://www.autotranspay.com/docs","contact":{"email":"dudgns2947@gmail.com","url":"https://www.autotranspay.com/docs"}},"servers":[{"url":"https://www.autotranspay.com/api/v1"}],"security":[{"ApiKey":[]}],"tags":[{"name":"Orders","description":"주문"},{"name":"Deposits","description":"입금"},{"name":"Events","description":"이벤트 (웹훅 대사)"},{"name":"Tools","description":"문자 해석·샌드박스"},{"name":"Collect","description":"수집기 (휴대폰 → 서버)"}],"paths":{"/orders":{"post":{"tags":["Orders"],"operationId":"createOrder","summary":"주문 등록","description":"입금 대기 주문을 등록합니다. 같은 order_number 를 같은 내용(금액·입금자명)으로 다시 보내면 기존 주문을 200 으로 반환(멱등). 등록 직후 최근 7일 미매칭 입금과 역매칭을 시도하므로 status 가 이미 matched 일 수 있습니다.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOrderRequest"}}}},"responses":{"200":{"description":"같은 내용의 기존 주문 (멱등 재요청)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"201":{"description":"생성됨","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"요청 값 오류 (invalid_request_error) — parameter_invalid, bank_account_invalid, return_url_not_allowed(widget.return_url 이 https 가 아니거나 허용 도메인 밖)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"order_number_conflict — 같은 주문번호가 다른 내용으로 존재","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["Orders"],"operationId":"listOrders","summary":"주문 목록","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["pending","matched","canceled","expired"]}},{"name":"limit","in":"query","description":"한 번에 가져올 개수 (1~100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","description":"이전 응답의 next_cursor. (예전 방식인 마지막 항목의 created_at ISO 8601 시각도 받지만, 같은 시각의 항목이 빠질 수 있어 next_cursor 를 권장)","schema":{"type":"string"}}],"responses":{"200":{"description":"주문 목록 (created_at 내림차순)","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"다음 페이지를 가져올 때 starting_after 에 그대로 넘기는 값 (마지막 페이지면 null)"}}}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}":{"get":{"tags":["Orders"],"operationId":"getOrder","summary":"주문 조회","parameters":[{"name":"id","in":"path","required":true,"description":"주문 ID(uuid) 또는 주문번호(order_number)","schema":{"type":"string"}}],"responses":{"200":{"description":"주문","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"resource_missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/{id}/cancel":{"post":{"tags":["Orders"],"operationId":"cancelOrder","summary":"주문 취소","description":"pending·expired 주문을 취소합니다. 이미 취소된 주문은 그대로 반환합니다. 매칭된 주문은 409 order_already_matched.","parameters":[{"name":"id","in":"path","required":true,"description":"주문 ID(uuid) 또는 주문번호(order_number)","schema":{"type":"string"}}],"responses":{"200":{"description":"취소된 주문","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"resource_missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"order_already_matched","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deposits":{"get":{"tags":["Deposits"],"operationId":"listDeposits","summary":"입금 목록","parameters":[{"name":"status","in":"query","description":"쉼표로 구분한 상태 목록 (unmatched, review, matched, ignored). 기본값 review,unmatched","schema":{"type":"string","default":"review,unmatched","example":"review"}},{"name":"limit","in":"query","description":"한 번에 가져올 개수 (1~100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","description":"이전 응답의 next_cursor. (예전 방식인 마지막 항목의 received_at ISO 8601 시각도 받지만, 같은 시각의 항목이 빠질 수 있어 next_cursor 를 권장)","schema":{"type":"string"}}],"responses":{"200":{"description":"입금 목록 (received_at 내림차순)","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Deposit"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"다음 페이지를 가져올 때 starting_after 에 그대로 넘기는 값 (마지막 페이지면 null)"}}}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deposits/{id}":{"get":{"tags":["Deposits"],"operationId":"getDeposit","summary":"입금 조회","parameters":[{"name":"id","in":"path","required":true,"description":"입금 ID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"입금","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deposit"}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"resource_missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deposits/{id}/match":{"post":{"tags":["Deposits"],"operationId":"matchDeposit","summary":"입금 수동 매칭","description":"확인 필요·미매칭 입금을 주문에 확정합니다. 즉시 deposit.matched 웹훅(match.method=manual)이 발송됩니다. 금액이 달라도 확정됩니다.","parameters":[{"name":"id","in":"path","required":true,"description":"입금 ID","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchDepositRequest"}}}},"responses":{"200":{"description":"매칭된 입금","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deposit"}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"resource_missing (입금 또는 주문)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"order_not_pending | deposit_already_handled | quota_exceeded (Free 월 한도 초과)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/deposits/{id}/ignore":{"post":{"tags":["Deposits"],"operationId":"ignoreDeposit","summary":"입금 무시","description":"주문과 무관한 입금으로 처리합니다 (unmatched·review 만 가능).","parameters":[{"name":"id","in":"path","required":true,"description":"입금 ID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"무시 처리된 입금","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deposit"}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"resource_missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"deposit_already_handled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events":{"get":{"tags":["Events"],"operationId":"listEvents","summary":"이벤트 목록","parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["deposit.matched","deposit.review_required","order.expired"]}},{"name":"limit","in":"query","description":"한 번에 가져올 개수 (1~100)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","description":"이전 응답의 next_cursor. (예전 방식인 마지막 항목의 created_at ISO 8601 시각도 받지만, 같은 시각의 항목이 빠질 수 있어 next_cursor 를 권장)","schema":{"type":"string"}}],"responses":{"200":{"description":"이벤트 목록 (created_at 내림차순)","content":{"application/json":{"schema":{"type":"object","required":["object","data","has_more","next_cursor"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"],"description":"다음 페이지를 가져올 때 starting_after 에 그대로 넘기는 값 (마지막 페이지면 null)"}}}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/events/{id}":{"get":{"tags":["Events"],"operationId":"getEvent","summary":"이벤트 조회","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^evt_"}}],"responses":{"200":{"description":"이벤트","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"resource_missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/parse":{"post":{"tags":["Tools"],"operationId":"parseMessage","summary":"문자 해석 미리보기","description":"은행 알림 원문을 해석만 합니다 (저장·매칭 없음).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":4000}}}}}},"responses":{"200":{"description":"해석 결과","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseResult"}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sandbox/deposits":{"post":{"tags":["Tools"],"operationId":"simulateDeposit","summary":"샌드박스 입금 (테스트 키 전용)","description":"가짜 입금을 만들어 매칭·웹훅까지 실행합니다. order_number, text, 또는 amount+depositor_name 중 하나가 필요합니다. 운영 키로 호출하면 400 livemode_not_allowed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SimulateDepositRequest"}}}},"responses":{"201":{"description":"생성·매칭된 입금","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deposit"}}}},"400":{"description":"요청 값 오류 (invalid_request_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 키 없음·무효 (authentication_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"권한 없음·비활성 조직 (permission_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"resource_missing (order_number 의 주문 없음)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"요청 한도 초과 (rate_limit_error) — API 키당 분당 600회","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"다시 시도까지 초","schema":{"type":"integer"}}}},"500":{"description":"일시적 서버 오류 (api_error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/collect":{"post":{"tags":["Collect"],"operationId":"collect","summary":"입금 알림 수집","description":"수집기(휴대폰)가 은행 입금 알림을 올립니다. JSON·form·text/plain 을 받으며 필드 이름은 여러 별칭을 허용합니다 (text|msg|message|body|content, from|sender|phone|title, received_at|time|timestamp|receivedStamp). 수집된 입금은 항상 운영 모드입니다.","security":[{"CollectorToken":[]},{"CollectorBearer":[]},{"CollectorQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/CollectRequest"}},"text/plain":{"schema":{"type":"string"}}}},"responses":{"200":{"description":"처리 결과","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CollectResult"}}}},"401":{"description":"수집기 토큰 없음·무효","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/collect/heartbeat":{"post":{"tags":["Collect"],"operationId":"collectHeartbeat","summary":"수집기 하트비트","description":"본문의 원시값(문자열·숫자·불리언) 필드 최대 20개를 수집기 상태로 저장합니다.","security":[{"CollectorToken":[]},{"CollectorBearer":[]},{"CollectorQuery":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":["string","number","boolean"]}},"example":{"battery":82,"charging":true,"app_version":"1.4.2"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"const":"heartbeat"},"ok":{"const":true},"server_time":{"type":"string","format":"date-time"}}}}}},"401":{"description":"수집기 토큰 없음·무효","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"deposit.matched":{"post":{"summary":"입금이 주문에 확정됨","description":"AutoTransPay-Signature: t=<unix>,v1=<hex(HMAC-SHA256(whsec, \"t.body\"))>. 2xx=수신, 409/410/422=거절(재시도 안 함, 첫 전송이면 매칭 되돌림), 그 외=재시도(최대 12회).","parameters":[{"name":"AutoTransPay-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"AutoTransPay-Event-Id","in":"header","required":true,"schema":{"type":"string"}},{"name":"AutoTransPay-Event-Type","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositMatchedEvent"}}}},"responses":{"200":{"description":"수신 완료"}}}},"deposit.review_required":{"post":{"summary":"사람 확인이 필요한 입금","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepositReviewRequiredEvent"}}}},"responses":{"200":{"description":"수신 완료"}}}},"order.expired":{"post":{"summary":"주문 만료","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderExpiredEvent"}}}},"responses":{"200":{"description":"수신 완료"}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"atp_test_… (테스트) 또는 atp_live_… (운영). X-API-Key 헤더도 허용"},"CollectorToken":{"type":"apiKey","in":"header","name":"X-Collector-Token"},"CollectorBearer":{"type":"http","scheme":"bearer","description":"atpc_… 수집기 토큰"},"CollectorQuery":{"type":"apiKey","in":"query","name":"token"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message"],"properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","not_found_error","conflict_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"}}}}},"CreateOrderRequest":{"type":"object","required":["order_number","amount","depositor_name"],"properties":{"order_number":{"type":"string","minLength":1,"maxLength":100},"amount":{"type":"integer","minimum":1,"maximum":999999999999},"depositor_name":{"type":"string","minLength":1,"maxLength":60},"alt_names":{"type":"array","maxItems":5,"items":{"type":"string","minLength":1,"maxLength":60}},"customer":{"type":"object","properties":{"phone":{"type":["string","null"],"maxLength":30},"email":{"type":["string","null"],"maxLength":200}}},"bank_account_id":{"type":["string","null"],"format":"uuid"},"expires_at":{"type":["string","null"],"format":"date-time"},"metadata":{"type":"object","additionalProperties":true},"widget":{"type":"object","description":"결제 위젯 (선택)","properties":{"return_url":{"type":["string","null"],"format":"uri","maxLength":500,"description":"입금 확인 화면의 완료 버튼 주소. https 이고 콘솔 → 결제 위젯의 허용 도메인 안이어야 함(테스트 모드는 http://localhost·127.0.0.1 도). 아니면 400 return_url_not_allowed (param widget.return_url). 멱등 재등록 때는 처음 값이 남고 응답에는 싣지 않음"}}}},"example":{"order_number":"ORD-1042","amount":122500,"depositor_name":"홍길동","customer":{"phone":"010-1234-5678"},"metadata":{"cart_id":"c_981"}}},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"order"},"livemode":{"type":"boolean"},"order_number":{"type":"string"},"amount":{"type":"integer"},"currency":{"const":"KRW"},"depositor_name":{"type":"string"},"alt_names":{"type":"array","items":{"type":"string"}},"customer":{"type":"object","properties":{"phone":{"type":["string","null"]},"email":{"type":["string","null"]}}},"bank_account_id":{"type":["string","null"],"format":"uuid"},"status":{"type":"string","enum":["pending","matched","canceled","expired"]},"expires_at":{"type":["string","null"],"format":"date-time"},"matched_at":{"type":["string","null"],"format":"date-time"},"match_method":{"type":["string","null"],"enum":["auto","manual",null]},"deposit_id":{"type":["string","null"],"format":"uuid"},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"widget_url":{"type":["string","null"],"format":"uri","description":"구매자 입금 안내 화면 주소 (주문 생성 후 30일, 테스트 모드 24시간). 위젯이 꺼져 있거나 보여 줄 계좌가 없으면 null"}}},"Candidate":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"depositor_name":{"type":"string"},"amount":{"type":"integer"},"score":{"type":"integer","minimum":0,"maximum":100},"amount_match":{"type":"boolean"},"reasons":{"type":"array","items":{"type":"string"}}}},"Deposit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"const":"deposit"},"livemode":{"type":"boolean"},"amount":{"type":"integer"},"depositor_name":{"type":"string"},"bank_code":{"type":["string","null"]},"bank_account_id":{"type":["string","null"],"format":"uuid"},"occurred_at":{"type":["string","null"],"format":"date-time"},"received_at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["unmatched","review","matched","ignored"]},"review_reason":{"type":["string","null"],"enum":["ambiguous","weak_name","amount_mismatch","expired_order","over_limit","low_confidence","manual_mode","merchant_rejected","quota_exceeded","suspicious","reported_name",null],"description":"reported_name = 구매자가 결제 위젯에서 알린 입금자명으로만 맞음 (자동확정하지 않음, 같은 금액의 다른 주문도 후보에 남음)"},"order_id":{"type":["string","null"],"format":"uuid"},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}},"confidence":{"type":"number","minimum":0,"maximum":1},"flags":{"type":"array","items":{"type":"string"}},"created_at":{"type":"string","format":"date-time"}}},"MatchDepositRequest":{"type":"object","description":"order_id 또는 order_number 중 하나 필수","properties":{"order_id":{"type":"string","format":"uuid"},"order_number":{"type":"string","minLength":1,"maxLength":100}},"anyOf":[{"required":["order_id"]},{"required":["order_number"]}]},"SimulateDepositRequest":{"type":"object","description":"order_number, text, 또는 amount+depositor_name 중 하나 필수","properties":{"order_number":{"type":"string","minLength":1,"maxLength":100},"amount":{"type":"integer","minimum":1},"depositor_name":{"type":"string","minLength":1,"maxLength":60},"bank_code":{"type":"string","maxLength":20,"default":"WOORI"},"text":{"type":"string","minLength":1,"maxLength":2000}},"anyOf":[{"required":["order_number"]},{"required":["text"]},{"required":["amount","depositor_name"]}]},"ParseResult":{"type":"object","properties":{"object":{"const":"parse_result"},"kind":{"type":"string","enum":["deposit","withdrawal","unknown"]},"amount":{"type":["integer","null"]},"depositor_name":{"type":["string","null"]},"balance":{"type":["integer","null"]},"bank_code":{"type":["string","null"]},"account_hint":{"type":["string","null"]},"occurred_at":{"type":["string","null"],"format":"date-time"},"confidence":{"type":"number","minimum":0,"maximum":1}}},"CollectRequest":{"type":"object","properties":{"text":{"type":"string","description":"알림 원문 (별칭 msg, message, body, content)"},"from":{"type":"string","description":"발신번호·앱 이름 (별칭 sender, phone, title)"},"received_at":{"type":["string","number"],"description":"수신 시각: epoch 초/밀리초, ISO 8601, \"YYYY-MM-DD HH:mm(:ss)\"(KST)"}}},"CollectResult":{"type":"object","properties":{"object":{"const":"collect_result"},"outcome":{"type":"string","enum":["deposit","ignored","duplicate","unrouted","unparsed","rejected"]},"deposit_id":{"type":["string","null"],"format":"uuid"},"status":{"type":["string","null"],"enum":["unmatched","review","matched","ignored",null]},"order_number":{"type":["string","null"]},"parsed":{"type":"object","properties":{"kind":{"type":"string"},"amount":{"type":["integer","null"]},"depositor_name":{"type":["string","null"]},"bank_code":{"type":["string","null"]},"confidence":{"type":"number"}}}}},"Event":{"type":"object","properties":{"object":{"const":"event"},"id":{"type":"string","pattern":"^evt_"},"type":{"type":"string"},"livemode":{"type":"boolean"},"data":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"DepositMatchedEvent":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"deposit.matched"},"data":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"amount":{"type":"integer"},"depositor_name":{"type":"string"},"metadata":{"type":"object","additionalProperties":true}}},"deposit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"integer"},"depositor_name":{"type":"string"},"bank_code":{"type":["string","null"]},"occurred_at":{"type":"string","format":"date-time"}}},"match":{"type":"object","properties":{"method":{"type":"string","enum":["auto","manual"]},"actor":{"type":["string","null"],"description":"user:<id> | api_key:<id> | telegram:<id> | mcp:<id>"},"amount_matches":{"type":"boolean"}}}}}}}]},"DepositReviewRequiredEvent":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"deposit.review_required"},"data":{"type":"object","properties":{"deposit":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"type":"integer"},"depositor_name":{"type":"string"}}},"reason":{"type":"string"},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}}}}}}]},"OrderExpiredEvent":{"allOf":[{"$ref":"#/components/schemas/Event"},{"type":"object","properties":{"type":{"const":"order.expired"},"data":{"type":"object","properties":{"order":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"order_number":{"type":"string"},"amount":{"type":"integer"}}}}}}}]}}}}