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

# 브라질 Unico IDCloud(CPF + 셀피) 신분증 인증 API

> Didit의 브라질 Unico IDCloud(CPF + 셀피) 데이터베이스 조회로 공신력 있는 검증을 수행합니다. 건당 $0.20부터, 계약과 최소 사용량 없음.

Unico IDCloud 생체 검증입니다. 사용자의 셀피를 CPF에 등록된 얼굴과 대조하여 동일인인지, 동일인이 아닌지, 또는 판단할 수 없는지를 반환합니다. Didit은 이 서비스를 `POST /v3/database-validation/`을 통해 제공하므로, 제출된 데이터를 공식 데이터 소스와 대조하고 표준화된 일치 결과를 받을 수 있습니다. 입력 형식: `tax_number`에는 브라질 CPF(정확히 11자리 숫자)를 입력합니다.

## 적용 범위

* **적용 범위:** 96%
* **국가:** 브라질
* **서비스 ID:** `bra_unico_idcloud`
* **데이터 도메인:** 신원
* **카테고리:** BiometricRiskScore

브라질 CPF 보유자의 약 96%가 Unico 레지스트리에서 생체 인식 기록과 연결됩니다. 이는 정부 얼굴 대조 소스인 [Datavalid](https://docs.didit.me/ko/api-reference/database-validation/brazil/cpf-facial.md)의 약 50%보다 대략 두 배 넓은 범위입니다.

## 입력

| 필드 | 필수 여부 | 예시 |
| - | -: | - |
| `tax_number` | 예 | `11111111111` |
| `selfie` | 예 | `@./selfie.jpg` |
| `first_name` | 아니요 | `John` |
| `last_name` | 아니요 | `Doe` |
| `full_name` | 아니요 | `John Doe` |
| `date_of_birth` | 아니요 | `1990-01-01` |
| `vendor_data` | 아니요 | `user-1234` |

* **필수 입력:** `tax_number`, `selfie`
* **선택 입력:** `first_name`, `last_name`, `full_name`, `date_of_birth`, `vendor_data`
* **동의:** 필수
* **워크플로 제공 여부:** 워크플로에서 사용 가능
* **적용 범위:** 96%
* **가격:** 성공한 쿼리당 \$0.20

## 본문 파라미터

**issuing\_state** `string` *required* (default: BRA)

이 데이터베이스 서비스의 ISO 3166-1 alpha-3 국가 코드입니다.

예: `BRA`

**services** `string` *required* (default: bra\_unico\_idcloud)

이 서비스 ID를 포함하는 배열입니다. 서비스를 고정하면 요청이 이 특정 데이터베이스로만 범위가 제한됩니다.

예: `bra_unico_idcloud`

**consent** `boolean` *required* (default: true)

이 서비스에 대한 최종 사용자의 명시적 동의입니다.

예: `true`

**tax\_number** `string` *required* (default: 11111111111)

납세자 또는 세금 식별 번호입니다.

예: `11111111111`

**selfie** `file` *required*

생체 데이터베이스 검증에 업로드할 셀피 이미지 파일입니다. 허용 형식: JPEG, PNG 또는 WebP.

예: `@./selfie.jpg`

**first\_name** `string`

검증할 이름입니다.

예: `John`

**last\_name** `string`

검증할 성입니다.

예: `Doe`

**full\_name** `string`

검증할 법적 성명 전체입니다.

예: `John Doe`

**date\_of\_birth** `string`

`YYYY-MM-DD` 형식의 생년월일입니다.

예: `1990-01-01`

**vendor\_data** `string` (default: user-1234)

이 사용자를 식별하는 귀사의 고정 사용자 참조값으로, 예를 들어 내부 사용자 ID입니다. Didit은 이 값을 사용해 단독으로 수행된 검사를 같은 최종 사용자에게 연결하고 중복 탐지 노이즈를 줄입니다.

예: `user-1234`

## 입력 규칙 및 검증 참고 사항

* 브라질 CPF(정확히 11자리 숫자)
* `tax_number`에는 숫자만 포함되어야 합니다. 요청을 보내기 전에 공백, 하이픈 및 구두점을 제거하십시오.
* `tax_number`의 길이는 정확히 11자여야 합니다.

## 호출 방법

```bash cURL theme={null}
curl -X POST "https://verification.didit.me/v3/database-validation/" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "issuing_state=BRA" \
  -F "services=bra_unico_idcloud" \
  -F "vendor_data=user-1234" \
  -F "consent=true" \
  -F "tax_number=11111111111" \
  -F "selfie=@./selfie.jpg"
```

```python Python theme={null}
from didit import Didit

# Reads DIDIT_API_KEY.
client = Didit()

result = client.database_validation.validate(
    issuing_state="BRA",
    services=["bra_unico_idcloud"],
    consent=True,
    tax_number="11111111111",
    vendor_data="user-1234",
    selfie=open("selfie.jpg", "rb"),
)
print(result)
```

```javascript Node.js theme={null}
import Didit, { fileFromPath } from "@didit-protocol/sdk-node";

// Reads DIDIT_API_KEY.
const didit = new Didit();

const result = await didit.databaseValidation.validate({
  issuing_state: "BRA",
  services: ["bra_unico_idcloud"],
  consent: true,
  tax_number: "11111111111",
  vendor_data: "user-1234",
  selfie: await fileFromPath("selfie.jpg"),
});
console.log(result);
```

```go Go theme={null}
ctx := context.Background()
// Reads DIDIT_API_KEY.
client := didit.NewClient()

result, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{
	IssuingState: "BRA",
	Services:     didit.Some([]string{"bra_unico_idcloud"}),
	Consent:      didit.Bool(true),
	TaxNumber:    didit.String("11111111111"),
	VendorData:   didit.String("user-1234"),
	Selfie:       didit.Some(didit.FileFromPath("selfie.jpg")),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)
```

```java Java theme={null}
import java.nio.file.Path;
import java.util.List;
import me.didit.Didit;
import me.didit.types.DatabaseValidationValidateParams;

// Reads DIDIT_API_KEY.
Didit client = new Didit();

var result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder()
        .issuingState("BRA")
        .services(List.of("bra_unico_idcloud"))
        .consent(true)
        .taxNumber("11111111111")
        .vendorData("user-1234")
        .selfie(Path.of("selfie.jpg"))
        .build());
System.out.println(result);
```

```php PHP theme={null}
<?php

require 'vendor/autoload.php';

use Didit\DiditClient;
use Didit\File;

// Reads DIDIT_API_KEY.
$didit = new DiditClient();

$result = $didit->databaseValidation->validate([
    'issuing_state' => 'BRA',
    'services' => ['bra_unico_idcloud'],
    'consent' => true,
    'tax_number' => '11111111111',
    'vendor_data' => 'user-1234',
    'selfie' => File::fromPath('selfie.jpg'),
]);
print_r($result->toArray());
```

```ruby Ruby theme={null}
require "didit"

# Reads DIDIT_API_KEY.
didit = Didit::Client.new

result = didit.database_validation.validate(
  issuing_state: "BRA",
  services: ["bra_unico_idcloud"],
  consent: true,
  tax_number: "11111111111",
  vendor_data: "user-1234",
  selfie: Pathname("selfie.jpg")
)
puts result.to_h
```

```csharp .NET theme={null}
using System;
using System.Text.Json;
using Didit;

// Reads DIDIT_API_KEY.
using var client = new DiditClient();

var result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams
{
    IssuingState = "BRA",
    Services = new string[] { "bra_unico_idcloud" },
    Consent = true,
    TaxNumber = "11111111111",
    VendorData = "user-1234",
    Selfie = FileUpload.FromPath("selfie.jpg"),
});
Console.WriteLine(JsonSerializer.Serialize(result));
```

성공한 모든 호출은 HTTP `200`을 반환합니다. **`outcome_code`** 필드는 실제로 무슨 일이 일어났는지를 알려줍니다. 예를 들어 실제 생체 불일치(`BIOMETRIC_NO_MATCH`)와 판독할 수 없었던 셀피(`BIOMETRIC_IMAGE_UNUSABLE`)를 구분합니다. 표시된 `status`는 기본 기능 상태이며, 구성한 [Partial Match / No Match 작업](https://docs.didit.me/ko/core-technology/database-validation/database-validation-warnings.md)에 의해 재정의될 수 있습니다.

**`MATCH`**: 레지스트리가 신원을 확인했으며 검사한 모든 필드가 일치합니다.

```json 200 OK — MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Approved",
  "issuing_state": "BRA",
  "match_type": "full_match",
  "validations": [
    {
      "outcome_code": "MATCH",
      "service_id": "bra_unico_idcloud",
      "service_name": "BRA - Unico IDCloud (CPF + selfie)",
      "source_data": {
        "unico_face_match": "yes"
      },
      "validation": {
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`BIOMETRIC_NO_MATCH`**: 얼굴 대조 점수가 승인 임계값보다 낮았습니다. 셀피 속 인물은 레지스트리 사진 속 인물과 동일인이 아닙니다.

```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "BRA",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "BIOMETRIC_NO_MATCH",
      "service_id": "bra_unico_idcloud",
      "service_name": "BRA - Unico IDCloud (CPF + selfie)",
      "source_data": {
        "identification_number": "NO_MATCH"
      },
      "validation": {
        "identification_number": "no_match"
      }
    }
  ]
}
```

**`INCONCLUSIVE`**: 레지스트리가 해당 사람이 일치하는지 판단할 수 없었습니다. 결과가 실제로 불확실하며(레지스트리에 있을 수도, 없을 수도 있음), 불일치도 기술적인 이미지 문제도 아닙니다. 어떤 필드도 확인되지 않으므로 match\_type은 null이며 해당 검사는 검토 대상으로 전송됩니다.

```json 200 OK — INCONCLUSIVE theme={null}
{
  "request_id": "req_01H…",
  "status": "In Review",
  "issuing_state": "BRA",
  "match_type": null,
  "validations": [
    {
      "outcome_code": "INCONCLUSIVE",
      "service_id": "bra_unico_idcloud",
      "service_name": "BRA - Unico IDCloud (CPF + selfie)",
      "source_data": {},
      "validation": {}
    }
  ]
}
```

## 반환 데이터

`source_data`에 노출되는 정확한 필드는 레지스트리가 반환하는 내용에 따라 달라집니다. `bra_unico_idcloud`의 생성된 예시에는 현재 다음과 같은 표준화된 구조가 문서화되어 있습니다.

* `unico_face_match`

## 가격 및 SLA

BRA - Unico IDCloud(CPF + 셀피) 쿼리는 Didit이 검증 소스로부터 확정적인 결과를 받은 경우에만 과금됩니다.

* **호출당 가격:** 미화 \$0.20
* **과금:** 성공한 쿼리 건당 과금됩니다. 레지스트리에 연결할 수 없는 경우, 필수 필드가 누락된 경우, 또는 요청이 소스에 도달하기 전에 거부된 경우에는 과금되지 않습니다.
* **지연 시간:** 일반적인 p95 \< 2초
* **가용성:** Didit 측 기준 분기당 99.9%입니다. 하위 소스의 가용성은 국가 및 데이터셋에 따라 다릅니다.

## 데이터 소스 정보

[Unico](https://unico.io)는 브라질의 IDtech 기업으로, 브라질에서 가장 큰 민간 얼굴 생체 인식 등록부를 운영합니다. 이 회사의 IDCloud 플랫폼은 10억 개 이상의 얼굴 임베딩을 보관하고 있으며, 800개 이상의 브라질 기업의 온보딩 및 재인증 절차를 통해 매달 약 3,500만 개의 새로운 얼굴이 추가됩니다. 여기에는 가장 큰 은행 5곳 중 4곳도 포함됩니다. 이러한 규모 덕분에 위의 커버리지 수치가 나옵니다. CPF 조회 시 브라질 성인의 약 96%에 대해 생체 정보 기록이 확인됩니다.

Didit은 Unico와 직접 제휴하고 있으므로, 표준 데이터베이스 검증 API를 통해 IDCloud를 조회할 수 있습니다. 호출당 요금을 지불하며, 별도의 Unico 계약, 최소 사용량, 온보딩 절차가 필요하지 않습니다.

**이 소스가 정부 등록부와 다른 점.** Didit은 [Brazil - CPF + face match (Datavalid)](https://docs.didit.me/ko/api-reference/database-validation/brazil/cpf-facial.md)도 제공합니다. 이 소스는 공식 SERPRO 데이터 소스이며, 정부 등록부를 기준 데이터 원천으로 특별히 필요한 경우에 적합합니다. 그 외의 모든 경우에는 IDCloud가 더 적합합니다. 확인할 수 있는 두 가지 기준으로 비교하면, IDCloud는 성인의 약 96%에 도달하는 반면 Datavalid는 약 50%입니다. 또한 IDCloud는 사용자가 제공한 문서에서 가져온 사진이 아니라, 등록부가 직접 관리하는 생체 정보 기록과 대조하므로 문서 위조와 도난된 CPF 사기를 모두 막는 데 강합니다. 쿼리당 가격도 절반 미만입니다.

## 브라질 권장 흐름

대부분의 브라질 사용 사례에서는 문서 촬영이 전혀 필요하지 않습니다. 사용자가 CPF를 입력하면, 라이브니스 검사를 거친 셀피로 그 CPF의 소유자인지 확인합니다.

**1. CPF 수집**

유일한 텍스트 입력은 11자리 CPF입니다. 문서 사진이나 직접 입력하는 이름, 생년월일은 필요하지 않습니다.

이 흐름에서는 문서를 읽지 않으므로, 별도로 지정하지 않으면 Didit이 CPF를 가져올 곳이 없습니다. 세션을 만들 때 세션의 `metadata`로 CPF를 보내고, 데이터베이스 검증 단계의 `tax_number` 입력으로 매핑하십시오. Business Console에서는 해당 단계의 입력 매핑에서 설정하며, 워크플로 API를 사용하는 경우에는 노드의 `database_validation_field_sources`에 설정합니다:

```json theme={null}
{
  "database_validation_countries": {"BRA": {"services": ["bra_unico_idcloud"]}},
  "database_validation_field_sources": {
    "tax_number": {"source": "expected_data", "key": "metadata.cpf"}
  }
}
```

그다음 각 세션을 생성할 때 해당 키 아래에 값을 넣으십시오:

```json theme={null}
{"workflow_id": "<workflow_id>", "metadata": {"cpf": "12345678909"}}
```

매핑이 없어도 단계는 실행되지만, `tax_number`가 누락되었다고 보고하며 레지스트리를 조회하지 않습니다. 이 경우 과금은 발생하지 않으며, 세션의 `database_validations` 항목에 그 이유가 기록됩니다.

**2. 라이브니스 검사와 함께 셀피 촬영**

같은 워크플로에 [라이브니스](https://docs.didit.me/ko/core-technology/liveness/overview.md) 단계를 추가하고, 위험 허용 수준에 맞는 방식을 선택하십시오. **패시브 라이브니스**(사용자 동작 없음), **3D 플래시**, **3D 액션 & 플래시**가 있습니다. 3D 플래시와 3D 액션 & 플래시는 빛 패턴을 투사하는 능동 방식이며, 후자는 무작위 동작을 추가합니다. Business Console에서 설정하거나 워크플로 API를 통해 `face_liveness_method`(`PASSIVE`, `FLASHING`, `ACTIVE_3D`)로 지정하십시오. 어떤 방식을 선택하든 Didit이 촬영 단계를 렌더링하고 실제로 현장에 있는 사람인지 확인합니다. 이를 통해 저장된 사진이나 화면 재생 영상이 제출되는 것을 막습니다.

**3. Unico IDCloud로 CPF와 셀피 검증**

세션 흐름 안에서 Didit은 라이브니스 셀피를 자동으로 재사용하므로 이미지를 직접 다룰 필요가 없습니다. Didit은 위에서 매핑한 CPF를 읽고, IDCloud는 그 얼굴이 해당 CPF의 소유자인지 확인합니다. 이 단계에 필요한 입력은 이 두 가지뿐입니다. `metadata`에 `full_name`이나 `date_of_birth`를 함께 보내 매핑하면 교차 확인용으로 Unico에 전달되지만, 필수는 아닙니다.

> [!NOTE]
>
> 이 CPF 전용 흐름은 **세션 및 워크플로** 연동에 적용됩니다. 이 경우 Didit이 촬영을 수행하고 라이브니스 셀피를 이 서비스에 대신 전달합니다. `POST /v3/database-validation/`을 **직접** 호출하는 경우에는 `selfie`가 필수 파일 입력이며, 이미지를 직접 제공해야 합니다. 두 모드에 대한 자세한 내용은 [데이터베이스 검증 개요](https://docs.didit.me/ko/core-technology/database-validation/overview.md)를 참조하십시오.

**비용:** 패시브 라이브니스를 사용하면 인증된 사용자 1명당 약 \$0.30입니다. 이는 IDCloud 조회 \$0.20과 라이브니스 검사 \$0.10을 합산한 금액입니다. 능동 방식을 사용하면 라이브니스 검사 비용이 \$0.15이므로 약 \$0.35입니다. 이는 정가이며, 각 항목에 요금제 할인이 적용됩니다. 자세한 내용은 [요금](https://docs.didit.me/ko/getting-started/pricing.md)을 참조하십시오.

**커버리지가 없는 약 4%에 대한 대체 방법.** IDCloud가 `INCONCLUSIVE`를 반환하면, 레지스트리가 해당 CPF를 사용 가능한 생체 기록으로 연결하지 못한 것입니다. 일반적으로 해당 인물이 레지스트리에 없기 때문입니다. 이를 실패한 확인이 아니라 "응답 없음"으로 취급하고, 전체 [신분증 인증](https://docs.didit.me/ko/core-technology/id-verification/overview.md)으로 대체하십시오. 즉 문서 촬영과 문서의 초상 사진과 얼굴 대조를 수행합니다. 모든 사용자가 여전히 검증받을 수 있으며, 문서 검증 비용은 나머지 소수의 사용자에게만 발생합니다.

**거부 처리.** `BIOMETRIC_NO_MATCH`는 레지스트리가 얼굴 불일치를 명확히 판단했다는 뜻입니다. 얼굴이 해당 CPF의 소유자가 아닙니다. 이를 재시도를 유도하는 신호가 아니라 강한 부정 신호로 취급하십시오. 사용자를 바로 문서 촬영으로 보내는 것은 위조자가 원하는 경로입니다. 문서는 그들이 통제하는 자료이기 때문입니다. 다만 실제 오거부도 발생합니다. 외모 변화, 오래된 레지스트리 사진, 불량한 촬영이 원인일 수 있으므로, 이런 경우에는 자동 승인하거나 사용자를 막다른 길로 몰지 말고 수동 검토로 보내십시오. `BIOMETRIC_IMAGE_UNUSABLE`은 다릅니다. 셀피를 읽을 수 없었던 것이므로 새 셀피를 요청하십시오. 각 결과가 세션에 어떤 영향을 줄지는 [부분 일치 / 불일치 작업](https://docs.didit.me/ko/core-technology/database-validation/database-validation-warnings.md)으로 결정하고, 전체 목록은 [결과 코드](https://docs.didit.me/ko/core-technology/database-validation/database-validation-outcome-codes.md)를 참조하십시오.

**재방문 사용자.** 레지스트리 조회 비용은 한 번만 지불하면 됩니다. 사용자가 이 흐름을 통과하면 라이브니스 셀피가 `vendor_data`에 저장되므로, 이후 [생체 인증](https://docs.didit.me/ko/core-technology/biometric-auth/overview.md)으로 다시 검증할 수 있습니다. 생체 인증은 라이브니스 검사와 저장된 얼굴에 대한 얼굴 대조를 함께 수행하며, 비용은 \$0.10이고 라이브니스 방식도 동일하게 선택할 수 있습니다. 이 방법은 **재방문** 사용자에게만 해당한다는 점에 유의하십시오. 생체 인증 세션에는 저장된 얼굴(또는 직접 제공하는 `portrait_image`)이 필요하며, 둘 다 없으면 세션 생성 시 실패합니다. 따라서 처음 방문하는 사용자는 위 흐름을 먼저 거쳐야 합니다.

## 계속 읽기

* [브라질 데이터베이스 검증 개요](https://docs.didit.me/api-reference/database-validation/brazil.md)
* [데이터베이스 검증 개요](https://docs.didit.me/ko/core-technology/database-validation/overview.md)
* [결과 코드](https://docs.didit.me/ko/core-technology/database-validation/database-validation-outcome-codes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.