> ## 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.

# Проверка национального ID Финляндии по базам данных (API)

> Проверка национального ID Финляндии по официальным базам данных через Didit. Оплата за вызов от $3.50, без контрактов и минимумов.

Проверяет входные данные по данным официального ведомства, выдающего финскую идентификационную карту. Didit предоставляет этот сервис через `POST /v3/database-validation/`, чтобы вы могли сверить отправленные данные с авторитетным источником и получить нормализованные результаты сравнения.

## Покрытие

* **Покрытие:** \~ 100%
* **Страна:** Финляндия
* **ID сервиса:** `fin_national_id`
* **Домен данных:** Идентификация
* **Категория:** NationalIDRegistry

## Входные данные

| Поле | Обязательное | Пример |
| - | -: | - |
| `first_name` | Да | `John` |
| `last_name` | Да | `Doe` |
| `date_of_birth` | Да | `1990-01-01` |
| `national_id` | Да | `010190-123A` |
| `address.street_1` | Нет | `123 Sample Street` |
| `address.street_2` | Нет | `Unit 4` |
| `address.city` | Нет | `Sample City` |
| `address.region` | Нет | `Sample State` |
| `address.postal_code` | Нет | `10001` |
| `vendor_data` | Нет | `user-1234` |

* **Обязательные входные данные:** `first_name`, `last_name`, `date_of_birth`, `national_id`
* **Необязательные входные данные:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `vendor_data`
* **Согласие:** Обязательно
* **Доступность в сценарии:** Доступно в сценарии
* **Покрытие:** \~ 100%
* **Цена:** \$3.50 за успешный запрос

Не каждый документ, который принимает этот сервис, содержит идентификатор, по которому выполняется запрос. Если идентификатор не извлечён из документа, проверка фиксируется как **неприменимая**: база данных не запрашивается, и с вас не взимается плата. Для некоторых стран это составляет значительную долю реальных пользователей. Чтобы охватить их, также получайте идентификатор из ответа на анкету, из поля извлечения Document AI или из значения, которое вы передаёте при создании сессии, и сопоставьте его на шаге проверки по базам данных.

## Параметры тела запроса

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

Код страны ISO 3166-1 alpha-3 для этого сервиса базы данных.

Пример: `FIN`

**services** `string` *required* (default: fin\_national\_id)

Массив, содержащий ID этого сервиса. Указание сервиса ограничивает запрос этой конкретной базой данных.

Пример: `fin_national_id`

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

Явное согласие конечного пользователя на использование этого сервиса.

Пример: `true`

**first\_name** `string` *required* (default: John)

Имя, которое нужно проверить.

Пример: `John`

**last\_name** `string` *required* (default: Doe)

Фамилия, которую нужно проверить.

Пример: `Doe`

**date\_of\_birth** `string` *required* (default: 1990-01-01)

Дата рождения в формате `YYYY-MM-DD`.

Пример: `1990-01-01`

**national\_id** `string` *required* (default: 010190-123A)

Национальный идентификационный номер для этого сервиса.

Пример: `010190-123A`

**address** `object`

Структурированный объект адреса места жительства. Используйте `street_1`, `street_2`, `city`, `region`, `postal_code` и `country`. Полная строка адреса в устаревшем формате по-прежнему принимается, но не рекомендуется.

Пример: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`

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

Ваш постоянный идентификатор этого пользователя, например внутренний ID пользователя. Didit использует его, чтобы связывать отдельные проверки с одним и тем же конечным пользователем и снижать количество ложных срабатываний при поиске дубликатов.

Пример: `user-1234`

## Правила входных данных и примечания по валидации

* `address` для этого сервиса необязателен. Можно передать одну полную строку `address`, и Didit разделит её на структурированные элементы адреса, когда это возможно, или передать структурированные поля явно.
* `national_id` должен соответствовать шаблону `(?:\d{6}[-+A]\d{3}[0-9A-Z]|\d{6}\d{3}[0-9A-Z])`.
* Для сервисов, работающих с адресом, по возможности передавайте структурированные поля адреса вместо одной строки `address`.
* `address.street_1`: адрес улицы, включая номер дома и тип улицы.
* `address.street_2`: квартира, офис, корпус, этаж или дополнительная строка адреса. Передавайте её, только если она у вас есть.
* `address.city`: город, пригород, район, населённый пункт или квартал.
* `address.region`: штат, провинция, регион или город.
* `address.postal_code`: почтовый индекс.
* Сервисы баз данных, работающие с адресом, требуют как минимум адрес улицы и почтовый индекс. Запросы, отклонённые до обращения к источнику, не тарифицируются.

## Как вызвать API

```bash cURL theme={null}
curl -X POST "https://verification.didit.me/v3/database-validation/" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "issuing_state=FIN" \
  -F "services=fin_national_id" \
  -F "vendor_data=user-1234" \
  -F "consent=true" \
  -F "first_name=John" \
  -F "last_name=Doe" \
  -F "date_of_birth=1990-01-01" \
  -F "national_id=010190-123A"
```

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

# Reads DIDIT_API_KEY.
client = Didit()

result = client.database_validation.validate(
    issuing_state="FIN",
    services=["fin_national_id"],
    consent=True,
    first_name="John",
    last_name="Doe",
    date_of_birth="1990-01-01",
    national_id="010190-123A",
    vendor_data="user-1234",
)
print(result)
```

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

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

const result = await didit.databaseValidation.validate({
  issuing_state: "FIN",
  services: ["fin_national_id"],
  consent: true,
  first_name: "John",
  last_name: "Doe",
  date_of_birth: "1990-01-01",
  national_id: "010190-123A",
  vendor_data: "user-1234",
});
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: "FIN",
	Services:     didit.Some([]string{"fin_national_id"}),
	Consent:      didit.Bool(true),
	FirstName:    didit.String("John"),
	LastName:     didit.String("Doe"),
	DateOfBirth:  didit.String("1990-01-01"),
	NationalID:   didit.String("010190-123A"),
	VendorData:   didit.String("user-1234"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%+v\n", result)
```

```java Java theme={null}
import java.time.LocalDate;
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("FIN")
        .services(List.of("fin_national_id"))
        .consent(true)
        .firstName("John")
        .lastName("Doe")
        .dateOfBirth(LocalDate.parse("1990-01-01"))
        .nationalId("010190-123A")
        .vendorData("user-1234")
        .build());
System.out.println(result);
```

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

require 'vendor/autoload.php';

use Didit\DiditClient;

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

$result = $didit->databaseValidation->validate([
    'issuing_state' => 'FIN',
    'services' => ['fin_national_id'],
    'consent' => true,
    'first_name' => 'John',
    'last_name' => 'Doe',
    'date_of_birth' => '1990-01-01',
    'national_id' => '010190-123A',
    'vendor_data' => 'user-1234',
]);
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: "FIN",
  services: ["fin_national_id"],
  consent: true,
  first_name: "John",
  last_name: "Doe",
  date_of_birth: "1990-01-01",
  national_id: "010190-123A",
  vendor_data: "user-1234"
)
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 = "FIN",
    Services = new string[] { "fin_national_id" },
    Consent = true,
    FirstName = "John",
    LastName = "Doe",
    DateOfBirth = "1990-01-01",
    NationalId = "010190-123A",
    VendorData = "user-1234",
});
Console.WriteLine(JsonSerializer.Serialize(result));
```

Каждый успешный вызов возвращает HTTP `200`. Поле **`outcome_code`** показывает, что именно произошло. Например, оно отличает реальное несовпадение биометрии (`BIOMETRIC_NO_MATCH`) от селфи, которое не удалось прочитать (`BIOMETRIC_IMAGE_UNUSABLE`). Показанный `status` — это статус функции по умолчанию. Ваши настроенные [действия для частичного совпадения / отсутствия совпадения](https://docs.didit.me/ru/core-technology/database-validation/database-validation-warnings.md) могут его переопределить.

**`MATCH`** — Реестр подтвердил личность, и все проверенные поля совпали.

```json 200 OK — MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Approved",
  "issuing_state": "FIN",
  "match_type": "full_match",
  "validations": [
    {
      "outcome_code": "MATCH",
      "service_id": "fin_national_id",
      "service_name": "Finland National ID",
      "source_data": {
        "address": "123 Sample Street",
        "date_of_birth": "1990-01-01",
        "first_name": "John",
        "identification_number": "SAMPLE-ID-12345",
        "last_name": "Doe"
      },
      "validation": {
        "date_of_birth": "full_match",
        "full_name": "full_match",
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`PARTIAL_MATCH`** — Идентификационный номер найден, но одно или несколько персональных полей (обычно имя или дата рождения) не полностью совпали.

```json 200 OK — PARTIAL_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "In Review",
  "issuing_state": "FIN",
  "match_type": "partial_match",
  "validations": [
    {
      "outcome_code": "PARTIAL_MATCH",
      "service_id": "fin_national_id",
      "service_name": "Finland National ID",
      "source_data": {
        "address": "123 Sample Street",
        "date_of_birth": "1990-01-01",
        "first_name": "John",
        "identification_number": "SAMPLE-ID-12345",
        "last_name": "Doe"
      },
      "validation": {
        "date_of_birth": "full_match",
        "full_name": "no_match",
        "identification_number": "full_match"
      }
    }
  ]
}
```

**`NO_MATCH`** — Реестр не вернул совпадений по переданным данным.

```json 200 OK — NO_MATCH theme={null}
{
  "request_id": "req_01H…",
  "status": "Declined",
  "issuing_state": "FIN",
  "match_type": "no_match",
  "validations": [
    {
      "outcome_code": "NO_MATCH",
      "service_id": "fin_national_id",
      "service_name": "Finland National ID",
      "source_data": {
        "date_of_birth": "NO_MATCH",
        "full_name": "NO_MATCH",
        "identification_number": "NO_MATCH"
      },
      "validation": {
        "date_of_birth": "no_match",
        "full_name": "no_match",
        "identification_number": "no_match"
      }
    }
  ]
}
```

## Возвращаемые данные

Конкретные поля, которые выводятся в `source_data`, зависят от того, что возвращает реестр. Сгенерированный пример для `fin_national_id` сейчас описывает следующую нормализованную структуру:

* `address`
* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Цены и SLA

Запросы по национальному удостоверению личности Финляндии тарифицируются только тогда, когда Didit получает окончательный результат от источника проверки.

* **Цена за вызов:** \$3.50 USD.
* **Тарификация:** за каждый успешный запрос. Плата не взимается, если реестр недоступен, если не заполнены обязательные поля или если запрос отклонён до отправки в источник.
* **Задержка:** типичный p95 \< 2 с.
* **Доступность:** 99.9% за квартал со стороны Didit. Доступность источника данных зависит от страны и набора данных.

## Продолжить чтение

* [Обзор проверки баз данных для Финляндии](https://docs.didit.me/api-reference/database-validation/finland.md)
* [Обзор проверки по базам данных](https://docs.didit.me/ru/core-technology/database-validation/overview.md)
* [Коды результатов](https://docs.didit.me/ru/core-technology/database-validation/database-validation-outcome-codes.md)


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