API로 직접 연동하기
웹·앱·봇에서 인증 흐름을 직접 구현하는 방법
연동 흐름#
웹사이트, 앱, Discord 봇에서 인증 화면과 결과 처리를 직접 구현할 수 있습니다. Free와 Plus 모두 지원합니다.
- 서버에서
POST https://api.sendwich.kr/v1/verifications를 호출합니다. - 응답의
destination,sms_text,expires_at을 사용자에게 표시합니다. - 사용자가 자신의 휴대폰에서 인증 문자를 전송합니다.
- 서버에서 웹훅 또는 조회 API로 결과를 받습니다.
연결 설정#
API 직접 연동에서는 생성 요청의 parent_origin과 return_url을 생략합니다. 프로젝트의 허용 도메인과 인증 후 돌아갈 URL도 비워 둘 수 있습니다. 두 설정은 인증 창의 팝업 알림과 복귀 이동에 사용됩니다.
API 조회로 결과를 받는 봇은 공개 URL 없이 운영할 수 있습니다. 웹훅을 사용하려면 외부에서 접근 가능한 HTTPS 수신 주소가 필요합니다.
서버와 화면 구성#
| 위치 | 역할 |
|---|---|
| 서비스 서버·봇 프로세스 | API 키 보관, 인증 생성, 사용자와 인증 ID 연결, 결과 처리 |
| 웹·앱 화면·비공개 봇 메시지 | 받는 번호, 인증 문자, 만료 시각 표시 |
| sendwich | SMS 수신, 발신 번호 확인, 인증 상태 관리, 웹훅 전송 |
클라이언트는 서비스 서버를 통해 인증을 생성하고 조회합니다. 서버는 로그인한 사용자가 자신의 인증에만 접근하도록 제한합니다. 자세한 구성은 직접 만든 인증 화면을 참고합니다.
API 목록#
| 메서드 | 경로 | 기능 |
|---|---|---|
| POST | /v1/verifications |
인증 생성 |
| GET | /v1/verifications/{id} |
인증 조회 |
| POST | /v1/verifications/{id}/cancel |
인증 취소 |
결과 수신#
웹훅은 인증의 최종 상태를 서버에 전송합니다. 조회 API는 주기적으로 호출하거나 사용자가 인증 확인을 누를 때 호출할 수 있습니다. 주기적으로 조회할 경우 최종 상태에 도달하거나 만료 시각이 지나면 중단합니다.
조회와 재시도는 각각 API 사용량에 포함됩니다. 실행 코드는 Node.js·Python과 Discord 봇 예제에서 확인할 수 있습니다.