인증 생성

인증 생성 요청·응답과 Idempotency-Key 사용 규칙

요청#

http

POST https://api.sendwich.kr/v1/verifications
Authorization: Bearer YOUR_LIVE_SECRET_KEY
Idempotency-Key: attempt_93a7_create
Content-Type: application/json

json

{
  "mode": "discover",
  "client_reference": "attempt_93a7",
  "state": "SERVER_GENERATED_RANDOM_STATE"
}

필드	기본값·조건	설명
`mode`	`discover`	`discover` 또는 `match`
`expected_phone`	`match` 전용·필수	일치 여부를 확인할 010 휴대폰 번호
`client_reference`	빈 문자열	서비스의 시도 식별자, 최대 160자
`state`	빈 문자열	서버에서 생성한 무작위 연결 값, 최대 256자
`parent_origin`	선택	팝업 알림을 받을 출처. 프로젝트 등록값과 일치해야 함
`return_url`	선택	인증 후 돌아갈 URL. 프로젝트 등록값과 일치해야 함

프로젝트와 환경은 API 키로 결정됩니다. 코드 형식과 유효시간은 프로젝트 설정을 따릅니다. 정의되지 않은 필드는 거절합니다.

응답#

최초 생성은 201, 동일 요청의 재시도는 200을 반환합니다.

json

{
  "id": "vrf_EXAMPLE",
  "status": "pending",
  "environment": "live",
  "mode": "discover",
  "phone": null,
  "carrier": null,
  "client_reference": "attempt_93a7",
  "state": "SERVER_GENERATED_RANDOM_STATE",
  "created_at": "2026-09-16T03:00:00.000Z",
  "expires_at": "2026-09-16T03:05:00.000Z",
  "verified_at": null,
  "server_time": "2026-09-16T03:00:00.000Z",
  "verification_url": "https://id.it.kr/#/verify/SESSION_TOKEN",
  "destination": "16661629",
  "sms_text": "하늘바다"
}

필드	설명
`id`	인증 ID. 서버에서 사용자·시도와 연결해 저장
`status`	최초 생성 시 `pending`
`environment`	실제 SMS 프로젝트는 `live`, 기존 테스트 프로젝트는 `test`
`mode`, `client_reference`, `state`	요청한 인증 모드와 연결 값
`phone`, `carrier`, `verified_at`	최초 생성 시 `null`
`created_at`, `expires_at`, `server_time`	UTC ISO 8601 시각
`verification_url`	sendwich 인증 창 URL
`destination`	인증 문자를 보낼 수신 번호
`sms_text`	사용자가 보낼 전체 문자

사용자에게 안내할 번호와 문자는 응답값을 사용합니다. 인증 창을 사용하는 경우 verification_url을 엽니다.

중복 생성 방지#

Idempotency-Key는 영문, 숫자, _, ., :, -로 구성한 8~128자의 필수 헤더입니다. 응답을 받지 못했을 때는 같은 키와 같은 본문으로 재시도합니다. 같은 키로 본문을 변경하면 409 idempotency_conflict를 반환합니다.

재시도 응답에는 Idempotent-Replayed: true 헤더와 최초 생성 응답이 포함됩니다. 인증 ID, 코드, URL, 만료 시각이 유지되며 유효시간은 연장되지 않습니다.

생성 응답은 24시간 보존됩니다. 보존 기간 이후에는 같은 키로 새 인증이 생성될 수 있습니다. 별도의 인증 시도를 시작할 때는 새 키를 사용합니다.

현재 상태는 조회 API로 확인합니다. 이미 완료된 인증도 생성 요청을 재시도하면 최초의 pending 응답을 반환합니다. 재시도 요청도 API 사용량에 포함됩니다.

웹훅 적용 시점#

인증을 생성할 때 프로젝트의 웹훅 설정이 저장됩니다. 알림을 받으려면 생성 전에 웹훅 수신 설정을 완료해야 합니다.