> ## Documentation Index
> Fetch the complete documentation index at: https://developers.argosidentity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 추가 프로세스 (Injection) 가이드

> 추가 프로세스(Injection)는 기존 submission에 대해 별도 경로를 통해 정보를 업데이트하는 프로세스입니다. 이 프로세스를 통해 기존 카테고리의 정보가 새로운 정보로 대체됩니다.

## 1. 전제조건

<Note>
  Injection 진행을 위해서는 사전에 라이브폼 또는 API를 통해 submission이 생성되어 있어야 합니다.
</Note>

## 2. Query String 옵션 (Injection)

Query String으로 전송한 추가 정보는 API 호출 시 응답 데이터 값에 포함됩니다. 이를 통해 다음과 같은 기능을 활용할 수 있습니다:

* KYC 제출자 식별을 위한 고유 유저 ID 생성
* 최대 3개까지의 커스텀 필드 추가

## 3. 적용 방법

Query String 옵션은 ARGOS ID check 라이브폼을 이용하여 적용할 수 있습니다. 모든 쿼리 스트링 값은 URL에 인코딩되어야 합니다.

## 4.URL 구조

* 기본 폼 URL: `https://form.argosidentity.com?pid={project_Id}`
* Injection 포함 URL: `https://form.argosidentity.com?pid={project_id}&action=addveri&sid={submission_id}`
* 암호화가 적용된 Injection 포함 URL: `https://form.argosidentity.com?pid={project_id}&encrypted={encrypted_values}`

<Warning>
  **암호화가 적용된 Injection 포함 URL** 로 사용할 시에는 sid 와 action 값도 암호화가 필요합니다.

  [https://form.argosidentity.com?pid=\{project\_id}\&encrypted=\{encrypted\_values}](https://form.argosidentity.com?pid=\{project_id}\&encrypted=\{encrypted_values}) (O)

  [https://form.argosidentity.com?pid=\{project\_id}\&action=addveri\&sid=\{submission\_id}\&encrypted=\{encrytped\_values}](https://form.argosidentity.com?pid=\{project_id}\&action=addveri\&sid=\{submission_id}\&encrypted=\{encrytped_values}) (X)

  예시를 (X)와 같이 지정시, 암호화 파라미터가 무시되며, 암호화 되지 않은 addveri(Address Verification) action과 동일하게 동작합니다.
</Warning>

<Note>
  암호화를 적용하는 방법은 이 [링크](https://developers.argosidentity.com/getting-started/en/encrypt-and-decrypt-data/overview)를 참조하세요.
</Note>

### 4-1. 주요 파라미터

<ResponseField name="pid" type="string" required="true">
  프로젝트 고유 구분자
</ResponseField>

<ResponseField name="sid" type="string" required="true">
  submission 고유 구분자. 암호화가 적용된 Injection 포함 URL 로 사용시 `sid` 도 암호화 적용이 필요.
</ResponseField>

<ResponseField name="action" type="string" required="true">
  Injection 옵션 실행 `addveri `암호화가 적용된 Injection 포함 URL 로 사용시 `action` 도 암호화 적용이 필요.
</ResponseField>

<ResponseField name="cf1" type="string">
  사용자 정의 옵션 필드 #1
</ResponseField>

<ResponseField name="cf2" type="string">
  사용자 정의 옵션 필드 #2
</ResponseField>

<ResponseField name="cf3" type="string">
  사용자 정의 옵션 필드 #3
</ResponseField>

<ResponseField name="userid" type="string">
  **암호화가 적용된 Injection 포함 URL에서만 지원.** 사용자 지정 고유 식별자
</ResponseField>

<ResponseField name="ipRiskCategory" type="string">
  **암호화가 적용된 Injection 포함 URL에서만 지원.** IP 라우팅 서비스를 기반으로 위험을 탐지할 수 있습니다. 지원되는 옵션은 `vpn` 과 `proxy` 그리고 `vpn` 파라미터가 있습니다. 파라미터 기재시 콤마와 옵션 사이에는 공백이 없어야 합니다. 이 옵션은  `ipRiskDurationHours` 옵션과 함께 사용합니다. `ipRiskDurationHours` 누락 시 해당 옵션을 사용하실 수 없습니다.
</ResponseField>

<ResponseField name="ipRiskDurationHours" type="int">
  **암호화가 적용된 Injection 포함 URL에서만 지원.** 위험이 탐지되었을 때 해당 IP 의 접근을 바로 제한할 수 있는 시간을 설정할 수 있습니다. 한번 탐지된 위험 IP는 설정된 시간 동안 재검사 없이 즉시 차단됩니다. 반드시 `ipRiskCategory` 옵션과 함께 사용해야 됩니다.
</ResponseField>

<ResponseField name="distanceCheckSource" type="string">
  **암호화가 적용된 Injection 포함 URL에서만 지원.** 접속한 IP 와 입력한 주소 거리가 상이할 경우 진행을 제한시킬 수 있습니다. 현재는 `ipGeo` 파라미터 옵션만 제공 됩니다. `distanceMaxDistanceKm` 과 함께 사용합니다. `distanceMaxDistanceKm` 누락 시 해당 옵션을 사용하실 수 없습니다.
</ResponseField>

<ResponseField name="distanceMaxDistanceKm" type="int">
  **암호화가 적용된 Injection 포함 URL에서만 지원.** 접속한 IP 와 입력한 주소 거리를 km 단위로 설정할 수 있습니다. 반드시 `distanceCheckSource` 옵션과 함께 사용해야 됩니다.
</ResponseField>

<ResponseField name="blacklistCountries" type="bool">
  **암호화가 적용된 Injection 포함 URL에서만 지원.** Dashboard 에서 설정한 블랙리스트 국가를 금지하기 위해서는 `blacklistCountries` 값이 true 로 설정되어야 합니다. 기본 설정 값은 false 입니다.
</ResponseField>

<Note>
  blacklistCountires 는 Injection 을 통해 입력한 국가 기준으로 차단을 진행합니다.

  IP 위치와 제출된 국가와는 관련이 없습니다.
</Note>

## 4-2. 거절 사유 응답

| 오류 코드                  | 설명                                   |
| ---------------------- | ------------------------------------ |
| `ipRisk_failCategory`  | 선택된 ipRisk 검증 카테고리에서 위험이 감지되어 실패한 경우 |
| `distanceChecks_ipGeo` | ipGeo 로 측정 시 정한 거리보다 먼 주소가 입력되었을 경우  |
| `blackliskCountries`   | 대시보드에 설정된 블랙리스트 국가의 Submission 인 경우  |

## 4-3. 응답 오류

| 오류 코드                        | 설명                         |
| ---------------------------- | -------------------------- |
| `Invalid required`           | 필수 파라미터 누락                 |
| `Required field is missing`  | sid, pid, 주소데이터 중 1개 이상 누락 |
| `Invalid submissionId`       | 존재하지 않는 sid                |
| `Invalid projectId`          | 존재하지 않는 pid                |
| `Error in injecting address` | 정의되지 않은 불특정 에러             |

## 5. 주소 업데이트 결과

### 5-1-a. 성공 시

* 결과 페이지로 이동
* `주소지 인증이 완료되었습니다.` 메시지 표시

### 5-1-b. 성공 시 (webhook)

[웹훅 이벤트의 Data Injection](https://developers.argosidentity.com/webhooks/ko/idcheck-injection)을 참고하세요.

### 5-2. 실패 시

* 오류 페이지 호출
  * `ipRiskCategory` 로 위험이 감지됐을 시, `VPN/프록시 감지, VPN 또는 프록시를 비활성화한 후 일반적인 네트워크로 다시 시도해 주세요.` 메시지 표시
  * `distanceCheckSource` 로 입력된 주소와 IP 거리가 설정한 km 보다 떨어져 있을 경우 `주소 확인 실패, 주소를 다시 확인하거나 거주지 인근 네트워크에서 시도해 주세요`  메시지 표시
  * 처리 중 오류가 발생 된 경우 `주소지 정보를 처리하는 중 오류가 발생하였습니다. 다시 시도해주세요.` 메시지 표시 후 재인증 진행

### 5-2-b. 실패 시 (Webhook)

IP risk 탐지에 관해선 별도의 Webhook 은 없습니다. 다만 거리 확인 혹은 블랙리스트 국가 관련 Fail 이 발생된 경우 다음과 같이 Webhook 을 발송합니다. 실패 예시는 [웹훅 이벤트의 Data Injection](https://developers.argosidentity.com/webhooks/ko/idcheck-injection)을 참고하세요.

이 가이드를 통해 ID check의 추가 프로세스(Injection) 기능과 Query String 옵션을 효과적으로 활용하여 ID check 프로세스를 보다 유연하게 관리하고 커스터마이즈할 수 있습니다.