인증 조회와 취소

인증 상태·결과 조회와 대기 중인 인증 취소

인증 조회#

인증이 속한 프로젝트의 API 키와 verifications:read 권한이 필요합니다. 성공 시 200을 반환합니다.

bash

curl 'https://api.sendwich.kr/v1/verifications/vrf_EXAMPLE' \
  -H "Authorization: Bearer $SENDWICH_API_KEY"

json

{
  "id": "vrf_EXAMPLE",
  "status": "verified",
  "environment": "live",
  "mode": "discover",
  "phone": "+821012345678",
  "carrier": "SKT",
  "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": "2026-09-16T03:01:00.000Z",
  "server_time": "2026-09-16T03:01:02.000Z"
}

sms_text, destination, verification_url은 생성 응답에서만 제공하므로 인증이 진행되는 동안 필요한 값을 보관합니다.

상태와 결과#

상태	의미	처리
`pending`	인증 대기 중	웹훅 대기 또는 조회
`verified`	발신 번호 확인 완료	사용자·시도 대조 후 결과 반영
`expired`	유효시간 경과	새 인증 시작
`cancelled`	인증 취소	새 인증 시작

verified, expired, cancelled는 변경되지 않는 최종 상태입니다. 인증이 성공하면 phone에 E.164 형식의 번호, verified_at에 완료 시각을 반환합니다. 그 외에는 두 값이 null입니다. carrier는 SKT, KT, LGU+ 또는 null이며 성공 여부와 독립적입니다.

서버에 저장한 사용자·시도와 id, environment, mode, client_reference, state를 대조합니다. 실제 번호 인증에는 live 결과를 반영하고, 후속 작업은 인증 ID당 한 번만 처리합니다.

인증 취소#

bash

curl -X POST 'https://api.sendwich.kr/v1/verifications/vrf_EXAMPLE/cancel' \
  -H "Authorization: Bearer $SENDWICH_API_KEY"

verifications:cancel 권한이 필요하며 요청 본문은 생략합니다. 성공 시 200과 조회 API와 같은 형식의 결과를 반환합니다.

취소는 pending 상태에만 적용됩니다. 이미 최종 상태라면 해당 상태를 반환합니다. 문자 수신과 취소 요청이 동시에 처리될 경우 먼저 확정된 상태를 반환하므로 응답의 status를 확인해야 합니다.

조회와 결과 보관#

최종 상태에 도달하거나 만료 시각이 지나면 주기적인 조회를 중단합니다. 일시적인 통신 오류에는 조회 간격을 늘립니다. 호출을 줄이려면 웹훅이나 사용자 확인 버튼을 사용할 수 있습니다. 조회는 요청마다 사용량에 포함됩니다.

서비스에 필요한 최종 결과와 처리 내역은 자체 데이터베이스에 보관합니다. sendwich의 보존 기간이 지난 인증 ID는 404를 반환할 수 있습니다.