인증 시작
인증 한 건을 만들고 사용자에게 코드를 보냅니다.
v2 는 경로에 계정 ID 가 없습니다 — 계정은 API 키가 정합니다. 요청·응답 필드는 모두 camelCase 입니다.
재발송은 같은 요청을 한 번 더 부르는 것입니다
같은 번호로 다시 부르면 새 건이 생기고 앞 건도 살아 있습니다. 둘 중 어느 코드로든
통과하며, 하나가 통과하면 나머지는 자동으로 canceled 가 됩니다. 진행 중인 건이 있다고
거절하지 않습니다 — 문자를 못 받은 사용자가 만료를 기다리는 것 말고 방법이 없어지기
때문입니다.
제어는 한도가 합니다. 직전 건 생성 후 60초 안에 다시 부르면 429 이고,
같은 번호로 시간당 5건·하루 10건·동시 5건까지입니다.
코드는 응답에 실리지 않습니다
코드가 사용자에게 가는 경로는 문자 본문 하나뿐이고, 저장도 해시로만 합니다.
Authentication
API Key를 Bearer 토큰으로 전달
Request
인증 대상 번호. 문자 API 와 같은 정규화 규칙을 씁니다 — 국내 표기와 +82 E.164 를 모두 받고, 그 밖의 값은 400 invalid_phone 입니다.
인증 방식.
sms— 코드를 문자로 보냅니다.call— 전화를 걸어 코드를 두 번 읽어 줍니다. 받지 않거나 통화가 실패하면 그 건은failed로 닫히고 다시 걸지 않습니다. 미응답은 통화료가 붙지 않습니다(과금 원점이 응답 시각입니다).
둘 다 사용자가 듣거나 읽은 코드를 check 로 대조합니다 — 호출 방법이
같습니다. 계약에는 sms_inbound(사용자가 문자를 보냄)·call_inbound
(사용자가 전화를 검)도 정의돼 있으며 순차로 열립니다.
발신에 쓸 계정 보유 번호. 생략하면 계정 번호 중 하나를 고릅니다. 계정에 번호가 하나도 없으면 422 no_number 이고, 다른 계정의 번호를 주면 400 from_not_owned 입니다.
코드 자릿수. 숫자만 쓰며 앞자리 0 이 올 수 있습니다.
코드 유효 시간(초).
문자 문안 언어. 지금은 ko 하나입니다 — 값을 먼저 열어 두면 en 을 넣고도 한국어 문자를 받는 「있는데 안 되는」 상태가 됩니다. 값을 나중에 더하는 것은 하위호환입니다.
문안에 채울 값. 서비스명 을 주면 문자 앞에 [서비스명] 으로 붙습니다. 코드는 우리가 채우므로 여기 넣지 않습니다.
같은 계정에서 같은 키로 다시 요청하면 발송하지 않고 1회차 결과를 그대로 돌려줍니다. 빈 문자열은 400 입니다 — 템플릿에서 빈 값이 들어가 멱등이 조용히 꺼지는 걸 막습니다.
Response
인증 시작됨
pending— 코드를 기다리는 중verified— 통과. 1회용입니다 — 같은 건을 두 번 소비할 수 없습니다expired—ttlSeconds가 지남max_attempts— 대조 5회를 모두 사용canceled— 취소했거나, 같은 번호의 다른 건이 먼저 통과함failed— 전달 자체가 실패(문자 발송 실패, 통화 미응답·실패)
발신에 쓴 계정 보유 번호.
남은 대조 횟수. 건당 5회에서 시작합니다.
사용자에게 그대로 보여 줘야 하는 것. 발신형(sms·call)은 우리가 사용자에게 코드를 전달하므로 null 입니다. 수신형 채널이 열리면 보낼 번호와 문구가 여기 담깁니다.