# 인증 생성

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

문서: https://sendwich.kr/docs/api/create/

## 요청

```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 키로 결정됩니다. 코드 형식과 유효시간은 [프로젝트 설정](https://sendwich.kr/docs/verification-codes/)을 따릅니다. 정의되지 않은 필드는 거절합니다.

## 응답

최초 생성은 `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](https://sendwich.kr/docs/api/retrieve-and-cancel/)로 확인합니다. 이미 완료된 인증도 생성 요청을 재시도하면 최초의 `pending` 응답을 반환합니다. 재시도 요청도 API 사용량에 포함됩니다.

## 웹훅 적용 시점

인증을 생성할 때 프로젝트의 웹훅 설정이 저장됩니다. 알림을 받으려면 생성 전에 [웹훅 수신 설정](https://sendwich.kr/docs/webhooks/)을 완료해야 합니다.