# 개인통관고유부호 인증 요청 이름·생년월일·휴대전화번호와 간편인증 방식을 입력하면 사용자에게 간편인증 요청을 보내고, 결과 조회에 사용할 tx_id 를 즉시 반환합니다. 인증: Authorization: Bearer $APICK_API_KEY 본문 있는 REST 요청: multipart/form-data. GET 본문 및 MCP JSON-RPC 규격은 해당 명세를 따릅니다. 인증키는 서버에 보관하세요. 모든 예제는 정적 자료입니다. ## POST /rest/req_pccc 응답 필드 - `data` (object): 인증 접수 결과 - `data.tx_id` (string): 결과 조회에 사용하는 트랜잭션 ID - `data.status` (string): 처리 상태 (pending: 인증 대기) - `data.message` (string): 상태 메시지 (고정값: "인증 대기중입니다.") - `data.provider` (string): 사용한 간편인증 방식 - `data.expires_at` (string): 인증 유효 기한(ISO 8601). 이 시각까지 승인하지 못하면 인증 실패 처리됩니다. - `data.success` (integer): 과금 여부0: 실패 또는 재사용(무과금)1: 발송 성공(과금)3: 실패(timeout) - `api` (object): API 호출 공통 데이터 - `api.success` (boolean): API 서버 정상 응답 여부 - `api.cost` (integer): API 호출 요금 - `api.ms` (integer): API 응답 시간 - `api.pl_id` (integer): API 결제 로그 ID ## 인증 요청: POST /rest/req_pccc ### 입력 - `name` (string, 필수): 이름 - `birthday` (string, 필수): 생년월일 8자리 (YYYYMMDD) - `phone` (string, 필수): 휴대전화 번호 (본인 명의, 숫자만) - `provider` (string, 필수): 간편인증 방식 (kakao, naver, toss, pass, samsung, kb, shinhan, hana, woori, ibk, nh, kakaobank, banksalad) ### 응답 명세 ```json { "type": "object", "properties": { "data": { "type": "object", "properties": { "tx_id": { "type": "string", "description": "결과 조회에 사용하는 트랜잭션 ID" }, "status": { "type": "string", "description": "처리 상태 (pending: 인증 대기)" }, "message": { "type": "string", "description": "상태 메시지 (고정값: \"인증 대기중입니다.\")" }, "provider": { "type": "string", "description": "사용한 간편인증 방식" }, "expires_at": { "type": "string", "description": "인증 유효 기한(ISO 8601). 이 시각까지 승인하지 못하면 인증 실패 처리됩니다." }, "success": { "type": "integer", "description": "과금 여부0: 실패 또는 재사용(무과금)1: 발송 성공(과금)3: 실패(timeout)" } }, "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 호출 공통 데이터" } } } ``` ### 정적 응답 예시 ```json { "data": { "tx_id": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a", "status": "pending", "message": "인증 대기중입니다.", "provider": "kakao", "expires_at": "2026-09-19T20:24:07+09:00", "success": 1 }, "api": { "success": true, "cost": 30, "ms": 1284, "pl_id": 4902 } } ``` ### curl ```curl curl --fail-with-body --request POST 'https://apick.app/rest/req_pccc' \ --header "Authorization: Bearer $APICK_API_KEY" \ --form-string 'name="홍길동"' \ --form-string 'birthday="19900101"' \ --form-string 'phone="01011112222"' \ --form-string 'provider="kakao"' ``` ### Node.js (서버 ESM) ```javascript const form = new FormData(); form.append("name", "\"홍길동\""); form.append("birthday", "\"19900101\""); form.append("phone", "\"01011112222\""); form.append("provider", "\"kakao\""); const response = await fetch("https://apick.app/rest/req_pccc", { method: "POST", headers: { Authorization: "Bearer " + process.env.APICK_API_KEY }, body: form, signal: AbortSignal.timeout(120_000), }); if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`); const result = await response.json(); console.log(result); ``` ### python ```python import os import requests parts = [ ("name", (None, "\"홍길동\"")), ("birthday", (None, "\"19900101\"")), ("phone", (None, "\"01011112222\"")), ("provider", (None, "\"kakao\"")), ] response = requests.request("POST", "https://apick.app/rest/req_pccc", headers={"Authorization": "Bearer " + os.environ["APICK_API_KEY"]}, files=parts, timeout=(10, 120)) response.raise_for_status() result = response.json() print(result) ``` ### php ```php '"홍길동"', 'birthday' => '"19900101"', 'phone' => '"01011112222"', 'provider' => '"kakao"', ]; $curl = curl_init('https://apick.app/rest/req_pccc'); curl_setopt_array($curl, [ CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => $form, CURLOPT_RETURNTRANSFER => true, CURLOPT_CONNECTTIMEOUT => 10, CURLOPT_TIMEOUT => 120, ]); $body = curl_exec($curl); if ($body === false) { throw new RuntimeException(curl_error($curl)); } $status = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); if ($status >= 400) { throw new RuntimeException($body); } $result = json_decode($body, true, 512, JSON_THROW_ON_ERROR); print_r($result); ``` ## 코드·오류 ## 상세 기능·요금 Method URL POST https://apick.app/rest/req_pccc 요청하면 지정한 휴대전화번호로 간편인증 요청이 발송되고, 응답을 기다리지 않고 tx_id 를 즉시 반환합니다. 사용자가 휴대폰에서 승인한 뒤 get_pccc 에 tx_id 를 넣어 결과를 확인합니다. 승인 전 조회는 과금되지 않고 "인증 대기중입니다." 를 반환합니다. 인증 요청이 실제 발송된 접수 시점에 과금됩니다. 이미 대기 중인 요청을 다시 보내면 인증을 재발송하지 않고 기존 tx_id 를 반환하며 과금도 되지 않습니다. 정해진 시간(5분) 안에 승인하지 못하면 해당 요청은 인증 실패로 처리되어 다시 요청해야 합니다. ## 상세 요청 Header 이름 필수 설명 Authorization O Bearer 인증키 간편인증 방식(provider) 값 인증 방식 kakao 카카오톡 naver 네이버 toss 토스 pass 통신사 PASS samsung 삼성패스 kb KB국민은행 shinhan 신한은행 hana 하나은행 woori 우리은행 ibk IBK기업은행 nh NH농협은행 kakaobank 카카오뱅크 banksalad 뱅크샐러드 ## 상세 응답 Body 이름 타입 설명 data Object 인증 접수 결과 tx_id String 결과 조회에 사용하는 트랜잭션 ID status String 처리 상태 (pending: 인증 대기) message String 상태 메시지 (고정값: "인증 대기중입니다.") provider String 사용한 간편인증 방식 expires_at String 인증 유효 기한(ISO 8601). 이 시각까지 승인하지 못하면 인증 실패 처리됩니다. success Integer 과금 여부0: 실패 또는 재사용(무과금)1: 발송 성공(과금)3: 실패(timeout) api Object API 호출 공통 데이터 success Boolean API 서버 정상 응답 여부 cost Integer API 호출 요금 ms Integer API 응답 시간 pl_id Integer API 결제 로그 ID ## 상세 예제 요청 예시 form-data 전체 예제 보기 응답 예시 { "data": { "tx_id": "9f2c4a7b1d8e35c60a4f7b2d1e9c803a", "status": "pending", "message": "인증 대기중입니다.", "provider": "kakao", "expires_at": "2026-09-19T20:24:07+09:00", "success": 1 }, "api": { "success": true, "cost": 30, "ms": 1284, "pl_id": 4902 } }