---
title: 퀵스타트
description: Docker로 Human Plugin과 PostgreSQL 데이터베이스를 실행하고, Human Token 프로세스를 생성한 뒤 curl로 다시 읽어 옵니다.
canonical: https://developer.unico.io/ko/human-plugin/get-started/quickstart
locale: ko
generated_by: markdown-export
---

# 퀵스타트

빈 호스트에서 시작해 몇 분 만에 첫 프로세스를 생성하고 조회합니다.

이 페이지에서는 사용 중인 환경에서 빠르게 시작할 수 있도록 임시 PostgreSQL 컨테이너와 함께 Human Plugin을 실행합니다. 배포하려면 [Docker Compose](/ko/human-plugin/self-hosting/docker-compose) 또는 [Kubernetes](/ko/human-plugin/self-hosting/kubernetes)를 참고하세요.

## 사전 요구 사항

- `linux/amd64` 또는 `linux/arm64`에서 Docker 24 이상(macOS의 Docker Desktop도 사용 가능).
- Unico에서 받은 레지스트리 자격 증명과 액세스 키. [사전 요구 사항 및 액세스](/ko/human-plugin/get-started/prerequisites)를 참고하세요.

## 1. 이미지 가져오기

호스트마다 한 번, 사용자 이름과 토큰으로 Unico 레지스트리에 로그인합니다.

```bash
echo "<token>" | docker login pkg.unico.run -u <username> --password-stdin
```

```bash
docker pull pkg.unico.run/human-plugin-api:latest
```

## 2. PostgreSQL과 Human Plugin 시작하기

```bash
docker network create human-plugin
```

```bash
docker run -d --name human-plugin-db --network human-plugin \
  -e POSTGRES_USER=human_plugin -e POSTGRES_PASSWORD=human_plugin -e POSTGRES_DB=human_plugin \
  postgres:16
```

셸에 액세스 키를 설정한 다음 Human Plugin을 시작합니다.

```bash
export HUMAN_API_ACCESS_KEY='<your access key>'
```

```bash
docker run -d --name human-plugin --network human-plugin --stop-timeout 60 -p 127.0.0.1:8080:8080 \
  -e HUMAN_API_ACCESS_KEY \
  -e POSTGRES_ADDRESS_HOST=human-plugin-db \
  -e POSTGRES_USER=human_plugin \
  -e POSTGRES_PASSWORD=human_plugin \
  -e POSTGRES_SSL_MODE=disable \
  pkg.unico.run/human-plugin-api:latest
```

`POSTGRES_SSL_MODE=disable`은 이 로컬 데이터베이스에만 사용합니다. 그 외의 데이터베이스에서는 기본값인 `require`를 유지하세요. [구성](/ko/human-plugin/self-hosting/configuration)을 참고하세요.

Human Plugin이 준비되었는지 확인합니다.

```bash
curl --fail http://127.0.0.1:8080/health/ready
```

`{"status":"ok"}`가 표시되어야 합니다. 명령이 실패하면 `docker logs human-plugin`에서 원인을 확인할 수 있습니다.

<a id="3-create-a-process"></a>

## 3. 프로세스 생성하기

[플로우](/ko/human-plugin/api-reference/create-process#flows) 중 하나를 선택하세요. `clientId`, `correlationId`, `credential`은 모든 플로우에서 동일합니다.

### humantoken (사용자가 직접 촬영)

사용자가 캡처 저니에서 셀카를 촬영합니다. 응답에는 해당 저니로 연결되는 `link`가 포함됩니다.

```bash
curl -s -X POST http://127.0.0.1:8080/v1/processes \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "humantoken",
    "clientId": "client-a",
    "correlationId": "quickstart-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "callbackUri": "https://example.com/callback"
  }'
```

```json
{
  "id": "b063041c-7529-4e70-a2b4-c71c00f19801",
  "state": "PROCESS_STATE_CREATED",
  "token": "<SDK token>",
  "link": "https://…"
}
```

휴대폰에서 `link`를 열고 셀카를 촬영합니다. `token`과 `link`는 여기서만 반환되며, Human Plugin은 이를 저장하지 않습니다.

### api+humantoken (셀카를 직접 전송)

백엔드에 이미 셀카가 있다면 `imageBase64`로 전송합니다. 응답은 Human Token과 인텔리전스가 포함된 최종 결과입니다.

```bash
curl -s -X POST http://127.0.0.1:8080/v1/processes \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "quickstart-002",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'
```

```json
{
  "id": "5d1f7c2e-1b8a-4e0f-9a4b-2f6c3d9e8a71",
  "state": "PROCESS_STATE_FINISHED",
  "data": {
    "humanToken": { "value": "6d3d71…", "status": "validated" },
    "ndocs": {
      "distinctClientsCount": 1,
      "transactionsCount": 1,
      "firstSeen": "2026-11-03",
      "lastSeen": "2026-11-03",
      "credentials": [
        { "type": "DUI_TYPE_NG_BVN", "countryCode": "NGA", "distinctCredentialCount": 1 }
      ]
    }
  }
}
```

- `id`는 Human Plugin이 프로세스에 부여한 자체 ID입니다. 나중에 프로세스를 읽을 수 있는 유일한 방법이므로 보관하세요.
- `correlationId`는 귀사의 참조 값이며 고유해야 합니다. 이미 사용한 값을 다시 쓰면 `409 CORRELATION_ID_ALREADY_USED`가 반환됩니다.
- `credential`은 사용자의 문서입니다. 문서가 없으면 `null`을 보내세요. 사용할 수 있는 유형은 [속성 카탈로그](/ko/human-plugin/additional-resources/attribute-catalog)에 있습니다.
- `data.humanToken`은 사용자가 누구인지를, `data.ndocs`는 사용자의 인텔리전스, 즉 귀사와 어떤 활동을 했는지를 나타냅니다. [인텔리전스](/ko/human-plugin/get-started/intelligence)를 참고하세요.
- Journey를 사용하면 완료된 프로세스에 `data.liveness`도 포함됩니다. 캡처가 실제 사람에게서 이루어졌다면 `live`, 그렇지 않다면 `not_live`입니다. [`data`의 결과](/ko/human-plugin/api-reference/create-process#result)를 참고하세요.

## 4. 다시 읽어 오기

ID를 응답에서 받은 값으로 바꾸세요.

```bash
curl -s http://127.0.0.1:8080/v1/processes/b063041c-7529-4e70-a2b4-c71c00f19801
```

Journey는 사용자가 캡처를 마칠 때까지 `PROCESS_STATE_CREATED` 상태로 유지됩니다. 캡처가 끝난 뒤 다시 읽으면 응답이 `PROCESS_STATE_FINISHED`로 바뀌며 `data.humanToken`, `data.liveness`, `data.ndocs`가 포함됩니다. 결과를 신뢰하기 전에 `data.liveness.value`가 `live`인지 확인하세요.

## 5. 정리하기

```bash
docker rm -f human-plugin human-plugin-db && docker network rm human-plugin
```

## 다음 단계

- [플로우](/ko/human-plugin/api-reference/create-process#flows): 어떤 플로우를 사용할지, 각 플로우에 무엇이 필요한지.
- [프로세스 생성](/ko/human-plugin/api-reference/create-process): 모든 필드와 규칙.
- [백엔드 통합](/ko/human-plugin/integrations/backend): 무엇을 저장하고 실패를 어떻게 처리할지.
- [Human Token Journey](/ko/human-plugin/integrations/human-token-journey): 캡처 저니.
- 프런트엔드 측 캡처를 위한 가이드: [Web](/ko/human-plugin/integrations/web), [Android](/ko/human-plugin/integrations/android), [iOS](/ko/human-plugin/integrations/ios), [Ionic](/ko/human-plugin/integrations/ionic), [React Native](/ko/human-plugin/integrations/react-native), [Flutter](/ko/human-plugin/integrations/flutter).
- [인프라에서 Human Plugin 실행하기](/ko/human-plugin/self-hosting/overview)