{"openapi":"3.0.3","info":{"title":"APICK 개인통관고유부호 인증 요청","version":"1.0.0","description":"이름·생년월일·휴대전화번호와 간편인증 방식을 입력하면 사용자에게 간편인증 요청을 보내고, 결과 조회에 사용할 tx_id 를 즉시 반환합니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/req_pccc":{"post":{"summary":"개인통관고유부호 인증 요청","description":"이름·생년월일·휴대전화번호와 간편인증 방식을 입력하면 사용자에게 간편인증 요청을 보내고, 결과 조회에 사용할 tx_id 를 즉시 반환합니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tx_id":{"type":"string","description":"결과 조회에 쓰는 거래 ID(32자리 영소문자·숫자)입니다. get_pccc에 그대로 넣습니다."},"status":{"type":"string","description":"새로 보냈으면 pending(승인 대기)입니다. 기존 요청을 돌려줬으면 그 요청의 현재 상태이므로 결과는 get_pccc로 확인합니다."},"message":{"type":"string","description":"상태 안내 문구입니다. 예: 인증 대기중입니다."},"provider":{"type":"string","description":"사용한 간편인증 방식(허용값 표의 값)입니다. 새로 보냈을 때만 옵니다."},"expires_at":{"type":"string","description":"인증 유효 기한(ISO 8601, UTC Z 표기)입니다. 이 시각까지 승인하지 않으면 만료됩니다. 새로 보냈을 때만 옵니다."},"success":{"type":"integer","description":"1: 새로 발송(과금), 0: 기존 요청 재사용 또는 실패(과금 없음)."}}},"api":{"type":"object","properties":{"success":{"type":"boolean"},"cost":{"type":"integer","description":"차감된 포인트입니다. 재사용·실패는 0입니다."},"ms":{"type":"integer"},"pl_id":{"type":"integer","description":"결제 기록 번호입니다. 재사용 응답은 -1입니다."}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"name":{"type":"string","description":"조회 대상의 이름입니다. 간편인증·개인 조회에서는 성명, 기업 조회에서는 법인명·상호를 뜻합니다. 생년월일·전화번호 같은 보조 식별자와 함께 확인하세요. (string)","example":"홍길동"},"birthday":{"type":"string","description":"대상자의 생년월일 8자리입니다. 예: 19900101. 하이픈 없이 숫자만 보내며, 인증 대상자와 정확히 일치해야 합니다. (string)","example":"19900101"},"phone":{"type":"string","description":"본인 명의 휴대전화 번호입니다. 하이픈 없이 숫자만 입력하며(예: 01012341234), 인증 문자를 받을 수 있는 번호여야 합니다. (string)","example":"01012345678"},"provider":{"type":"string","description":"간편인증 방식 (kakao, naver, toss, pass, samsung, kb, shinhan, hana, woori, ibk, nh, kakaobank, banksalad) (string)","example":"kakao"},"telco":{"type":"string","description":"통신사 코드입니다. provider=pass(통신사 PASS)로 보낼 때 필수입니다. 빠지면 휴대폰 인증 요청 없이 400(입력 항목이 잘못됐습니다.(통신사))으로 거절합니다. S(SKT)·K(KT)·L(LGU+)·SA(SKT알뜰폰)·KA(KT알뜰폰)·LA(LGU+알뜰폰) (string)"}},"required":["name","birthday","phone","provider"]}}}}}}},"x-code-tables":[{"title":"provider 허용값","columns":["값","인증 방식"],"rows":[["kakao","카카오톡"],["naver","네이버"],["toss","토스"],["pass","통신사 PASS"],["samsung","삼성패스"],["kb","KB국민은행"],["shinhan","신한은행"],["hana","하나은행"],["woori","우리은행"],["ibk","IBK기업은행"],["nh","NH농협은행"],["kakaobank","카카오뱅크"],["banksalad","뱅크샐러드"]]},{"title":"오류와 복구","columns":["상황","HTTP","data.error","해결"],"rows":[["name이 비었거나 2~40자가 아님","400","입력 항목이 잘못됐습니다.(이름)","이름을 넣어 다시 요청합니다."],["birthday가 비었거나 8자리 날짜가 아님","400","입력 항목이 잘못됐습니다.(생년월일 8자리)","YYYYMMDD로 보냅니다."],["phone이 비었거나 휴대전화 번호 형식이 아님","400","입력 항목이 잘못됐습니다.(휴대전화 번호)","01로 시작하는 10~11자리로 보냅니다."],["provider가 허용값이 아니거나 지금 쓸 수 없는 인증방식","400","입력 항목이 잘못됐습니다.(인증방식)","허용값 표의 값으로 보냅니다. API 인증키 문제가 아니므로 키를 바꾸지 마세요."],["provider=pass인데 telco가 비었거나 허용값이 아님","400","입력 항목이 잘못됐습니다.(통신사)","S·K·L·SA·KA·LA 중 하나로 보냅니다. 다른 인증방식에서는 보내지 않아도 됩니다."],["인증 앱이 입력한 사용자 정보를 받지 않음","400","인증 정보가 올바르지 않습니다.","이름·생년월일·휴대전화 번호와 인증 앱 가입 여부를 사용자에게 확인한 뒤 다시 요청합니다."],["같은 계정의 앞선 접수를 처리하는 중","429","앞선 요청을 처리하고 있습니다. 잠시 후 다시 시도해 주세요.","몇 초 뒤 다시 요청합니다. 앞 요청이 끝나면 그 tx_id가 돌아올 수 있습니다."],["발송 실패","424","서비스 요청에 실패했습니다.","잠시 후 다시 요청합니다."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}