{"openapi":"3.0.3","info":{"title":"APICK 전기요금 납부내역 결과조회","version":"1.0.0","description":"transactionId 로 처리 상태를 확인하고, 조회가 끝난 뒤에는 표준화된 결과를 반환합니다. 인증 대기·조회 중·실패 응답은 과금되지 않으며, 실제 결과가 최초로 반환될 때만 1회 과금됩니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/get_power_bill":{"post":{"summary":"전기요금 납부내역 결과조회","description":"transactionId 로 처리 상태를 확인하고, 조회가 끝난 뒤에는 표준화된 결과를 반환합니다. 인증 대기·조회 중·실패 응답은 과금되지 않으며, 실제 결과가 최초로 반환될 때만 1회 과금됩니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"schemaVersion":{"type":"string","description":"결과 스키마 버전 (고정값: \"1.0\")"},"transactionId":{"type":"string","description":"트랜잭션 ID"},"product":{"type":"string","description":"조회 항목 코드. 인증요청 응답과 같은 값입니다."},"status":{"type":"string","description":"처리 상태 (위 표 참고)"},"resultAvailable":{"type":"boolean","description":"실제 결과 포함 여부. 과금 여부도 이 값으로 결정됩니다."},"charged":{"type":"boolean","description":"이번 호출의 과금 발생 여부. 최초 결과 반환에서만 true 입니다."},"sources":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"type":{"type":"string"},"status":{"type":"string"}}},"description":"항상 포함됩니다. 값이 없으면 빈 배열 [] 입니다. 항목이 여러 개인 상품에서 어느 것이 성공·실패했는지 알려줍니다. 각 항목은 source(제공 기관명), type(데이터 종류), status(SUCCESS/FAILED). 수집이 끝나기 전에는 아직 확정되지 않은 기관이 FAILED 로 보일 수 있습니다."},"message":{"type":"string","description":"상태 메시지"},"expiresAt":{"type":"string"},"success":{"type":"integer","description":"과금 여부0: 결과 없음 또는 재조회(무과금)1: 최초 결과 반환(과금)"},"progress":{"type":"object","properties":{"total":{"type":"integer"},"completed":{"type":"integer"}},"description":"진행률(COLLECTING 일 때). total(전체 항목), completed(완료 항목)"},"checkedAt":{"type":"string","description":"실제 정보를 확인한 시각. 한국시간(UTC+09:00) ISO 8601 이며 재조회 유효기간의 기준입니다."},"resultExpiresAt":{"type":"string","description":"결과 재조회 만료 시각. 한국시간(UTC+09:00) ISO 8601 입니다."},"result":{"type":"object","properties":{"powerBill":{"type":"object","properties":{"청구년월":{"type":"string","description":"조회한 청구년월 6자리"},"청구금액":{"type":"string","description":"해당 월 청구 금액.원 단위 금액이 숫자가 아닌 문자열로 온다."},"납부내역":{"type":"object","items":{"type":"object","properties":{"납부일자":{"type":"string"},"납부금액":{"type":"string"},"납부방법":{"type":"string"}}},"description":"납부 항목. 기관이 항목 이름을 정하므로 아래는 실제로 오는 대표 항목이다.","properties":{"납부일자":{"type":"string","description":"납부일"},"납부금액":{"type":"string","description":"납부 금액.원 단위 금액이 숫자가 아닌 문자열로 온다."},"납부방법":{"type":"string","description":"납부 방법"}}},"조회결과":{"type":"string","description":"고객번호 등 입력값이 맞지 않으면 기관 안내 문구가 온다. 정상 조회면 담기지 않는다."}},"description":"이 조회 항목의 결과입니다. 항목은 결과 규격을 참고하세요."}},"description":"조회된 결과 묶음. 실제 데이터가 있을 때만 포함됩니다."},"errorCode":{"type":"string","description":"오류 구분. RESULT_EXPIRED(재조회 기간 만료) / AUTH_EXPIRED / AUTH_REJECTED / COLLECT_FAILED"}},"description":"상태·결과"},"api":{"type":"object","properties":{"success":{"type":"boolean","description":"API 서버 정상 응답 여부"},"cost":{"type":"integer","description":"API 호출 요금"},"ms":{"type":"integer","description":"API 응답 시간"},"pl_id":{"type":"integer","description":"API 결제 로그 ID"}},"description":"API 호출 공통 데이터"}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"transactionId":{"type":"string","description":"/rest/req_power_bill 가 반환한 트랜잭션 ID (string)","example":"9f2c4a7b1d8e35c60a4f7b2d1e9c803a"}},"required":["transactionId"]}}}}}}},"x-code-tables":[{"title":"공통 오류 응답","columns":["상황","확인할 값","대응"],"rows":[["인증키 누락·오류","api.success=false","Header Authorization: Bearer 를 확인하세요. 과금되지 않습니다."],["입력값 누락·형식 오류","오류 메시지에 어느 항목이 잘못됐는지 표시됩니다.","이름·생년월일·휴대전화번호·인증방식을 다시 확인하세요."],["조회 항목에 필요한 추가 입력 누락","오류 메시지에 필요한 입력 이름이 표시됩니다.","아래 요청 표의 추가 입력 항목을 채우세요."],["없는 transactionId · 만료된 요청","요청을 찾을 수 없다는 응답 또는 status AUTH_EXPIRED","인증요청부터 다시 하세요."],["처리 중 재요청","HTTP 424 · 요청 처리 중 또는 처리 잠금 획득 실패 · api.cost=0","같은 사용자·같은 조회 항목의 접수는 서버가 한 건씩 처리합니다. 앞선 요청이 끝난 뒤 같은 transactionId 로 다시 조회하세요."],["결과 재조회 기한 만료","errorCode=RESULT_EXPIRED","24시간이 지났습니다. 인증요청부터 다시 하세요."],["사용자 인증 거부","errorCode=AUTH_REJECTED","사용자에게 다시 시도할지 안내하세요. 과금되지 않습니다."],["정보 조회 실패","errorCode=COLLECT_FAILED · status FAILED","잠시 후 인증요청부터 다시 시도하세요. 결과 단가는 과금되지 않습니다."],["보유 포인트 부족","HTTP 402 · data.error 에 사유 · api.cost=0","이 호출은 과금되지 않습니다. 요금과 포인트를 확인한 뒤 충전하고 다시 요청하세요."],["처리 시간 초과","HTTP 408 · data.success=3","서버가 제한 시간 안에 끝내지 못했습니다. 과금되지 않습니다. 잠시 후 같은 요청을 다시 보내세요."]]},{"title":"상태와 성공 판정","columns":["필드","의미","판단 기준"],"rows":[["HTTP 상태 코드","전송 계층의 결과","200 이 정상, 402 는 포인트 부족, 408 은 처리 시간 초과, 424 는 동일 요청 처리 중. 성공 판정에 쓰지 마세요."],["api.success","APICK 서버가 요청을 정상 처리했는지","포인트 부족(402)이나 시간 초과(408)에도 true 입니다. 업무 성공 판정에 쓰지 마세요."],["data.status","조회 진행 상태","AUTH_WAITING(승인 대기) · AUTH_COMPLETED · COLLECTING(조회 중) · SUCCESS(완료) · FAILED · AUTH_EXPIRED · AUTH_REJECTED · PARTIAL_SUCCESS. resultAvailable=true이면 결과를 사용하세요. RESULT_EXPIRED는 errorCode입니다."],["data.resultAvailable","지금 응답에 쓸 수 있는 결과가 들어 있는지","true 이면 폴링을 멈추고 result 를 사용하세요. false는 대기 또는 종료 상태일 수 있으므로 status를 함께 확인하세요."],["data.success","이 응답이 결과 제공 응답인지 (1/0)","새 유료 결과 제공에서는 1, 무료 재조회에서는 0일 수 있습니다. 결과 유무는 resultAvailable로 판단하세요. 처리 시간 초과(408)에서는 3 이 오므로 \"1 인지\"로 비교하세요."],["data.charged · api.cost","이번 호출의 과금 여부·금액","과금 회계 확인용입니다. 성공 판정에 쓰지 마세요."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}