# API로 직접 연동하기

> 웹·앱·봇에서 인증 흐름을 직접 구현하는 방법

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

## 연동 흐름

웹사이트, 앱, Discord 봇에서 인증 화면과 결과 처리를 직접 구현할 수 있습니다. Free와 Plus 모두 지원합니다.

1. 서버에서 `POST https://api.sendwich.kr/v1/verifications`를 호출합니다.
2. 응답의 `destination`, `sms_text`, `expires_at`을 사용자에게 표시합니다.
3. 사용자가 자신의 휴대폰에서 인증 문자를 전송합니다.
4. 서버에서 [웹훅](https://sendwich.kr/docs/webhooks/) 또는 [조회 API](https://sendwich.kr/docs/api/retrieve-and-cancel/)로 결과를 받습니다.

## 연결 설정

API 직접 연동에서는 생성 요청의 `parent_origin`과 `return_url`을 생략합니다. 프로젝트의 **허용 도메인**과 **인증 후 돌아갈 URL**도 비워 둘 수 있습니다. 두 설정은 [인증 창의 팝업 알림과 복귀 이동](https://sendwich.kr/docs/verification-window/)에 사용됩니다.

API 조회로 결과를 받는 봇은 공개 URL 없이 운영할 수 있습니다. 웹훅을 사용하려면 외부에서 접근 가능한 HTTPS 수신 주소가 필요합니다.

## 서버와 화면 구성

| 위치 | 역할 |
| --- | --- |
| 서비스 서버·봇 프로세스 | API 키 보관, 인증 생성, 사용자와 인증 ID 연결, 결과 처리 |
| 웹·앱 화면·비공개 봇 메시지 | 받는 번호, 인증 문자, 만료 시각 표시 |
| sendwich | SMS 수신, 발신 번호 확인, 인증 상태 관리, 웹훅 전송 |

클라이언트는 서비스 서버를 통해 인증을 생성하고 조회합니다. 서버는 로그인한 사용자가 자신의 인증에만 접근하도록 제한합니다. 자세한 구성은 [직접 만든 인증 화면](https://sendwich.kr/docs/examples/custom-ui/)을 참고합니다.

## API 목록

| 메서드 | 경로 | 기능 |
| --- | --- | --- |
| POST | `/v1/verifications` | [인증 생성](https://sendwich.kr/docs/api/create/) |
| GET | `/v1/verifications/{id}` | [인증 조회](https://sendwich.kr/docs/api/retrieve-and-cancel/) |
| POST | `/v1/verifications/{id}/cancel` | [인증 취소](https://sendwich.kr/docs/api/retrieve-and-cancel/) |

## 결과 수신

웹훅은 인증의 최종 상태를 서버에 전송합니다. 조회 API는 주기적으로 호출하거나 사용자가 **인증 확인**을 누를 때 호출할 수 있습니다. 주기적으로 조회할 경우 최종 상태에 도달하거나 만료 시각이 지나면 중단합니다.

조회와 재시도는 각각 [API 사용량](https://sendwich.kr/docs/usage/)에 포함됩니다. 실행 코드는 [Node.js·Python](https://sendwich.kr/docs/examples/node-python/)과 [Discord 봇](https://sendwich.kr/docs/examples/discord/) 예제에서 확인할 수 있습니다.