# 인증 조회와 취소

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

문서: https://sendwich.kr/docs/api/retrieve-and-cancel/

## 인증 조회

인증이 속한 프로젝트의 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`를 확인해야 합니다.

## 조회와 결과 보관

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

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