--- title: KYC Magic Link description: 멕시코에서 신원 확인 프로세스를 실행하며, 고유 링크를 통해 배포되는 호스팅된 여정으로 국가 신분증(INE)과 얼굴 생체 정보를 수집합니다. canonical: https://developer.unico.io/ko/dual-api/products/sign-up/kyc-magic-link/index locale: ko generated_by: markdown-export --- - [/ko/](/ko/) - [구축](/ko/dual-api/products/) - 지역별 가이드 - KYC Magic Link **이 페이지에서# KYC Magic Link 별도의 지역 계약이 사용 사례는 Unico의 `POST /v1/process` 엔드포인트나 API 계약을 **사용하지 않습니다**. 통합은 **Trully.ai**(호스트 `api.trully.ai`)와 이루어지며, Bearer JWT 대신 **`x-api-key`를 통한 인증**과 **독자적인 응답 스키마**를 사용합니다. 다른 국가의 경우 온보딩(글로벌)을 사용하십시오. ### 이 사용 사례가 해결하는 문제​ KYC Magic Link는 멕시코에서 신원 확인 프로세스를 실행하고, 국가 신분증(INE)과 얼굴 생체 정보를 수집하는 문제를 해결합니다. Unico가 호스팅하는 여정을 통해 WhatsApp, SMS, 이메일 등 자체 채널로 전송하는 링크로 프론트엔드 개발 부담을 없앱니다. **이 사용 사례를 사용하는 경우:** **멕시코**에서 운영하며 신분증이 **INE(필수)**인 경우. **이 사용 사례를 사용하지 않는 경우:** 사용자가 멕시코 외부에 있거나 다른 문서를 사용하는 경우 → 다른 온보딩 사용 사례를 참조하십시오. ### 관련 기능​ 단일 프로세스 내에서 실행되는 파이프라인: [문서 캡처 (INE)](/ko/capabilities/document-reuse-and-capture)[Liveness](/ko/capabilities/liveness)[사기 위험 분류](/ko/capabilities/fraud-risk-classification)[신원 확인](/ko/capabilities/identity-verification) 기능필수 여부흐름에서의 역할**문서 캡처**필수INE 문서 이미지를 캡처합니다. 이 사용 사례에서는 문서 재사용이 **불가**합니다 — 매 세션마다 새로운 캡처가 필요합니다.**Liveness**필수생체 인증 확인 — 프로세스를 고정하는 필수 셀피입니다.**위험 분류**필수행동 신호를 교차 참조하여 CPF와 관련된 사기 위험을 표시합니다.**신원 확인**선택(계약 시)트랜잭션 얼굴이 제공된 정부 식별자의 소유자에게 속하는지를 Unico의 신원 데이터베이스와 추가 신호를 활용하여 확인합니다.**[RENAPO Verification](/ko/capabilities/renapo-verification)**선택(계약 시)멕시코의 국가 인구 등록부인 RENAPO에 사용자의 CURP로 조회하고, 신원 확인 결과와 함께 등록부 기록을 반환합니다. ### 사전 요구 사항​ **API 키** — Unico의 온보딩 프로젝트 매니저가 프로비저닝합니다. `x-api-key` 헤더로 전송됩니다. **웹훅을 수신할 공개 HTTPS 엔드포인트** (선택 사항, 권장). **CORS 구성** — 웹훅을 수신하는 서버에서 `https://verification.unico.app`(운영) 및 `https://verification.uat.unico.app`(샌드박스) 출처를 허용합니다. ### 단계별 구현​ 다른 사용 사례와 달리, Magic Link에는 `flow` 필드가 **없습니다** — Trully API와 직접 통합됩니다. 이 엔드포인트는 자체 채널을 통해 사용자에게 배포하는 고유한 검증 링크를 생성합니다. ### 1. Magic Link 생성​ **엔드포인트:** `POST https://sandbox.trully.ai/v2/magic-link` **헤더:** 헤더필수 여부설명`x-api-key`예Unico의 온보딩 프로젝트 매니저가 프로비저닝한 API 키.`Content-Type`예`application/json` **본문(application/json):** 필드유형필수 여부설명`external_id`string아니오추적 및 참조 목적으로 사용되는 요청의 외부 식별자.`metadata`object아니오구성 매개변수의 컨테이너.`metadata.phone`string아니오국제 형식의 사용자 전화번호(예: `521234567890`).`metadata.redirect_url`string아니오KYC 프로세스 완료 후 사용자를 리디렉션할 URL.`metadata.webhook_url`string아니오KYC 프로세스 완료 후 KYC 프로세스 데이터를 전송할 URL. 이 웹훅은 클라이언트 측에서 호출됩니다. 보안상의 이유로 엔드포인트는 HTTPS를 사용해야 합니다. 컴포넌트는 웹훅 서버의 응답을 1분간 기다리며, 이후 통신을 중단합니다. 웹훅 통신에 의해 프로세스는 어떠한 영향도 받지 않습니다. CORS 구성에서 운영 환경은 `https://verification.unico.app`, 샌드박스 환경은 `https://verification.uat.unico.app`을 허용해야 합니다.`metadata.track_webhook_url`string아니오사용자가 처리한 각 KYC 단계를 전송할 URL(아래 웹훅 이벤트 참조). 이 웹훅은 클라이언트 측에서 호출됩니다. 보안상의 이유로 엔드포인트는 HTTPS를 사용해야 합니다. 컴포넌트는 웹훅 서버의 응답을 1분간 기다리며, 이후 통신을 중단합니다. 웹훅 통신에 의해 프로세스는 어떠한 영향도 받지 않습니다. CORS 구성에서 운영 환경은 `https://verification.unico.app`, 샌드박스 환경은 `https://verification.uat.unico.app`을 허용해야 합니다. `track_webhook_url`로 전송되는 `data.step`은 웹훅 V2에서 추적되는 것과 동일한 단계를 보고합니다 — 아래 [지원되는 단계 표](#webhook-v2)를 참조하십시오. **요청 예시:** ``` curl -X POST https://sandbox.trully.ai/v2/magic-link \ -H "x-api-key: $TRULLY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "external_id": "user-mx-12345", "metadata": { "phone": "521234567890", "redirect_url": "https://app.client.com.mx/kyc-done", "webhook_url": "https://app.client.com.mx/webhook/result", "track_webhook_url": "https://app.client.com.mx/webhook/track" } }' ``` ### 2. 토큰 및 링크 URL 수신​ **응답 필드:** 필드유형설명`data.external_id`string (nullable)추적 및 참조 목적으로 사용되는 요청의 외부 식별자.`data.created_on`string (date-time)magic link가 생성된 날짜.`data.is_active`boolean`true`이면 magic link가 활성 상태입니다.`data.token`stringKYC 프로세스를 magic link에 연결하는 데 사용되는 magic link의 토큰.`data.magic_link_url`string (URI)KYC 프로세스를 시작하기 위한 magic URL 링크.`data.metadata.redirect_url`string (nullable)KYC 프로세스 완료 후 사용자를 리디렉션할 URL.`data.metadata.webhook_url`string (nullable)KYC 프로세스 완료 후 KYC 프로세스 데이터를 전송할 URL. 이 웹훅은 클라이언트 측에서 호출됩니다.`data.metadata.track_webhook_url`string (nullable)사용자가 처리한 각 KYC 단계를 전송할 URL. 이 웹훅은 클라이언트 측에서 호출됩니다.`data.version`stringmagic link의 버전.`version`string요청을 처리한 API 버전으로, 변경 사항 추적 및 호환성 확인에 유용합니다.`status`string작업의 성공 또는 실패를 나타내는 응답 상태의 텍스트 표현.`status_code`integer요청 결과의 표준화된 지표를 제공하는 응답의 HTTP 상태 코드.`request_date`string (date-time)ISO 8601 형식으로 요청이 이루어진 날짜 및 시간.`request.metadata.redirect_url`string (nullable)KYC 프로세스 완료 후 사용자를 리디렉션할 URL(요청의 에코).`request.metadata.webhook_url`string (nullable)완료 후 KYC 프로세스 데이터를 전송할 URL(요청의 에코).`request.metadata.track_webhook_url`string (nullable)사용자가 처리한 각 KYC 단계를 전송할 URL(요청의 에코). **응답 예시:** ``` { "data": { "external_id": null, "created_on": "2025-07-28T18:11:54.430048399Z", "is_active": true, "token": "3f6dbcc1-49ba-4935-be90-dd8dd59b5530", "magic_link_url": "https://verification.uat.unico.app/link/v2/3f6dbcc1-49ba-4935-be90-dd8dd59b5530", "metadata": { "redirect_url": null, "webhook_url": null, "track_webhook_url": null }, "version": "v2" }, "version": "v1.4.2", "status": "ok", "status_code": 200, "request_date": "2025-07-28T18:11:54+0000", "request": { "metadata": { "redirect_url": null, "webhook_url": null, "track_webhook_url": null } }} ``` **오류 응답 — POST /v2/magic-link**코드메시지설명`400 Bad Request``data provided in the field is invalid`요청 페이로드의 잘못된 데이터 구조 또는 필드 값. 필수 필드와 형식을 확인하십시오.`403 Forbidden``Forbidden`API 키가 없거나 만료되었거나 권한이 없습니다. `x-api-key` 헤더를 확인하십시오.`500 Internal Server Error``internal server error`서버 측 처리 실패. 지수 백오프로 재시도하십시오. 지속되면 지원팀에 보고하십시오.**400 응답 예시:**``` { "data": { "error": "data provided in the field is invalid" }, "version": "v1.4.2", "status": "bad request", "status_code": 400, "request_date": "2025-07-28T20:22:29+0000", "request": { "metadata": null }} ``` ### 3. 사용자에게 magic_link_url 배포​ WhatsApp, SMS, 이메일을 통해 전송하거나 임베드합니다. 사용자는 자신의 디바이스에서 링크에 접근하여 호스팅된 여정을 완료합니다. 브라우저에서 링크를 여는 대신 자체 앱 안에 여정을 임베드하려는 경우, WebView 또는 CustomTab을 통해 이를 수행할 수 있습니다. 참고용 PoC: **Android/Kotlin:** [TrullyAi-AndroidMagicLink](https://github.com/unico-labs/TrullyAi-AndroidMagicLink) **React Native:** [TrullyAI-ReactNativeMagicLink](https://github.com/unico-labs/TrullyAI-ReactNativeMagicLink) ### 4. 결과 수신​ KYC 프로세스의 최종 결과를 수신하는 방법은 전적으로 자유롭게 결정할 수 있습니다 — 시스템 아키텍처에 가장 적합한 전략을 선택하십시오. 결과를 능동적으로 폴링(GET)하거나, 알림(웹훅)을 통해 수동적으로 수신할 수 있습니다. **옵션 A — GET을 통한 능동적 폴링** `GET /v2/history/request?magic_link_token={token}`을 호출하여 결과를 가져옵니다(아래 [GET을 통한 폴링](#polling-via-get) 참조). 최종 결정은 `data.response.unico.result`에 채워집니다. GET 사용 모범 사례링크가 생성된 시점부터 주기적으로 폴링하는 대신, 추적 웹훅(아래 [웹훅 V2](#webhook-v2) 참조)을 사용하여 정확히 언제 조회해야 하는지 파악하십시오. `form_decision_maker` 단계를 수신하면, 바로 그 시점이 이 GET 호출을 실행할 정확하고 안전한 시점입니다. **옵션 B — 웹훅을 통한 자동 수신** 최종 결과가 준비되는 즉시 시스템이 자동으로 알림을 받도록 합니다(아래 [웹훅 V2](#webhook-v2) 참조). 두 가지 버전을 사용할 수 있습니다: **웹훅 V1** — 토큰 생성 시 전송된 `metadata.webhook_url`의 URL로 결과를 수신합니다. **웹훅 V2** — 온보딩 PM과 사전에 구성합니다. `MAGIC_LINK_RESULTS` 이벤트를 수신하여 최종 판정을 받습니다. 복원력 — 폴백웹훅(옵션 B)이 주요 방법인 경우, 폴백으로 GET 조회(옵션 A)도 함께 구현하십시오. 이를 통해 네트워크 장애, 일시적인 서버 중단, 또는 처리에 실패한 웹훅이 있는 경우에도 재조정(reconciliation) 루틴을 통해 결과를 복구할 수 있습니다. ### GET을 통한 폴링​ **엔드포인트:** `GET https://sandbox.trully.ai/v2/history/request` **쿼리 매개변수:** 매개변수유형필수 여부설명`magic_link_token`string예Magic Link 생성 시 반환된 토큰. **헤더:** 헤더필수 여부설명`x-api-key`예Unico의 온보딩 프로젝트 매니저가 프로비저닝한 API 키. **요청 예시:** ``` curl "https://sandbox.trully.ai/v2/history/request?magic_link_token=$TOKEN" \ -H "x-api-key: $TRULLY_API_KEY" ``` **응답 예시:** ``` { "data": { "images": { "document_image": "/9j/4ASu7bmV[...]fyPjOKfgif//Z", "document_image_back": "/9j/4ASu7bmV[...]fyPjOKfgif//Z", "selfie": "/9j/4ASu7bmV[...]fyPjOKfgif//Z" }, "response": { "curp": { "age": 58, "curp": "GOCJ850627HDFRRL09", "date_of_birth": "14/11/1956", "deceased": false, "gender": "M", "government_name": "LUKE SKYWALKER", "government_valid": true, "is_mexican": true, "name_to_CURP_valid": true, "state_iso": "MX-NLE", "state_of_birth": "Nuevo León" }, "document": { "back": { "cic": "237457894", "citizen_id": "237457894", "mrz": "IDMEX999999999999<9 VADER