---
title: 백엔드 연동
description: 백엔드 서비스가 Human Plugin을 호출하는 방법 — 저장할 항목, 폴링 방법, 결과 확인 방법, 실패 처리 방법을 설명합니다.
canonical: https://developer.unico.io/ko/human-plugin/integrations/backend
locale: ko
generated_by: markdown-export
---

# 백엔드 연동

서버 측 서비스에서 Human Plugin을 호출하기 위한 체크리스트입니다.

Human Plugin은 백엔드에서만 호출하도록 설계되었습니다. 인바운드 인증이 없으므로 브라우저나 모바일 앱에 노출하지 마세요.

## 1. 생성

### curl

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

### Node.js

```javascript
const response = await fetch(`${process.env.HUMAN_PLUGIN_URL}/v1/processes`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    flow: 'api+humantoken',
    clientId: 'client-a',
    correlationId: 'onboarding-001',
    credential: { type: 'DUI_TYPE_NG_BVN', value: documentNumber },
    imageBase64,
  }),
  signal: AbortSignal.timeout(60_000),
});

const body = await response.json();
if (response.status !== 201) {
  // body is { message, details }
  throw new Error(`Human Plugin ${response.status} ${body.message}`);
}
const { id, state, data } = body;
```

클라이언트 타임아웃은 **최소 60초**로 설정하세요. 생성 요청은 처리에 최대 30초가 걸릴 수 있고, 여기에 데이터베이스 단계가 더해집니다. `id`는 생성 응답에서만 전달되므로, 클라이언트가 너무 일찍 포기하면 완료되는 프로세스를 놓칠 수 있습니다.

## 2. 나중에 필요한 항목 저장

| 저장할 항목 | 이유 |
| --- | --- |
| `id` | `GET` 호출에 사용하는 식별자입니다 |
| Journey `token`과 `link` (있는 경우) | 생성 응답에서만 반환되며 Human Plugin은 저장하지 않습니다 |
| 사용자의 `correlationId` | 고유해야 합니다. `503` 이후를 제외하고, 재시도를 포함해 모든 시도마다 새로 생성하세요 |

## 3. 결과 확인

1. `state`가 `PROCESS_STATE_FINISHED`이면 `data`에서 결과를 읽습니다. `humanToken`(재검증에서는 `humanTokenMatch`), `liveness`, `ndocs`가 들어 있습니다. 완료되었다고 해서 승인된 것은 아닙니다.
2. `state`가 `PROCESS_STATE_CREATED`이면 상태가 바뀔 때까지 백오프를 두고 `GET /v1/processes/{id}`를 폴링합니다. 프로세스를 진행시키는 것은 이 외에 없습니다.
3. `state`가 `PROCESS_STATE_FAILED`이면 프로세스가 결과 없이 종료된 것입니다. 플로우가 허용하면 새 프로세스를 시작하세요.

## 4. 인텔리전스 활용

`data.ndocs`는 해당 사용자가 귀사와 어떤 활동을 했는지 알려줍니다. 귀사의 고객사와 문서 중 몇 건에서, 언제 확인되었는지가 담겨 있습니다. 판단에 Human Token과 함께 활용하되, 값이 없을 수 있다는 점을 염두에 두세요. [인텔리전스](/ko/human-plugin/get-started/intelligence)를 참고하세요.

## 5. 실패 처리

- 생성 시 `500` 또는 `502`는 자동으로 재시도하지 마세요. [오류 및 재시도](/ko/human-plugin/api-reference/errors-and-retries)를 참고하세요.
- 생성 시 `503`은 동일한 `correlationId`로, `GET`의 모든 실패는 백오프를 두고 재시도하세요.
- `409`는 `correlationId`가 이미 사용 중이라는 의미입니다. 절대 재사용하지 마세요.
- `503`이 반복되면 알림을 설정하세요. Human Plugin이 데이터베이스에 접근하지 못한다는 뜻입니다.

## 운영 시 유의사항

- Human Plugin은 컨테이너와 같은 네트워크에서 호출하세요. 경로가 신뢰할 수 없는 네트워크를 지나는 경우 앞단에서 TLS를 종료하세요.
- Human Plugin 설치 한 개는 하나의 격리 경계입니다. 인텔리전스를 공유하면 안 되는 서로 다른 고객사, 브랜드, 환경은 각각 별도의 설치와 데이터베이스를 사용해야 하며, 각자의 인텔리전스를 가집니다.