Persons Backend API#

Описание#

Persons Backend API - это REST API для программного управления персонами ( профилями пользователей) в системе. API позволяет создавать, обновлять персоны, а также управлять их алиасами и фотографиями через внешние системы.

Для комфортной интеграции через Backend API воспользуйтесь Swagger (OpenAPI)

Термины#

Персона - это профиль физического лица в системе, содержащий его идентификационные данные, фотографии и историю проверок.
Алиас - это идентификатор персоны (телефон, ИИН, номер документа, пользовательский ID), используемый для поиска и предотвращения дубликатов.
Верификация - статус подтвержденности личности персоны (is_verified).
API KEY - ключ для аутентификации организации при обращении к API.
Base64 - способ кодирования бинарных данных (изображений) в текстовый формат для передачи через JSON.

Этапы:#

1. Получение API-KEY организации#

Первый этап для использования API - получение API-KEY организации. Чтобы получить API-KEY организации, необходимо зайти в Личный Кабинет по данной ссылке. API-KEY находится в поле Backend Api Key

backend_api_key

Пример API-KEY организации:

API-KEY: Efy202XKbVAWRu...

Примечание

Для наглядности используется укороченная длина API KEY. Его фактическая длина составляет 47 и более символов.

2. Создание персоны#

Важно

Чтобы использовать данный API, необходимо иметь активную подписку на технологию "Персоны". Подробнее о подписках можно прочитать здесь.

При создании персоны используются данные в формате JSON. Обязательными являются фотография и API-ключ организации.

URL запроса:

https://kyc.biometric.kz/api/v1/backend/persons/

Формат запроса	Метод запроса
JSON	POST

Наименование поля	Тип	Обязательно	Описание
api_key	String	Да	API KEY организации в личном кабинете
image_b64	String	Да	Изображение персоны в формате Base64
photo_type	String	Да	Тип фотографии: `digital`, `scan`, `live`, `other`
is_verified	Boolean	Да	Статус верификации персоны
aliases	Array	Нет	Массив алиасов персоны

Структура алиаса:

Наименование поля	Тип	Обязательно	Описание
value	String	Да	Значение алиаса (номер телефона, ИИН, номер документа и т.д.)
type	String	Да	Тип алиаса: `phone`, `personal_number`, `document_number`, `custom`

Примеры запроса:

cURLPythonJavaScript

curl -X 'POST' \
'https://kyc.biometric.kz/api/v1/backend/persons/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "api_key": "<organization_api_key>",
  "image_b64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "photo_type": "other",
  "is_verified": true,
  "aliases": [
    {
      "value": "+77071234567",
      "type": "phone"
    },
    {
      "value": "123456789012",
      "type": "personal_number"
    }
  ]
}'

import requests
import base64

# Кодирование изображения в base64
with open('photo.jpg', 'rb') as image_file:
    encoded_image = base64.b64encode(image_file.read()).decode('utf-8')
    image_b64 = f"data:image/jpeg;base64,{encoded_image}"

url = 'https://kyc.biometric.kz/api/v1/backend/persons/'

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}

data = {
    'api_key': '<organization_api_key>',
    'image_b64': image_b64,
    'photo_type': 'other',
    'is_verified': True,
    'aliases': [
        {
            'value': '+77071234567',
            'type': 'phone'
        },
        {
            'value': '123456789012',
            'type': 'personal_number'
        }
    ]
}

response = requests.post(url, headers=headers, json=data)

print(response.json())

const url = 'https://kyc.biometric.kz/api/v1/backend/persons/';

// Функция для кодирования файла в base64
function fileToBase64(file) {
    return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.readAsDataURL(file);
        reader.onload = () => resolve(reader.result);
        reader.onerror = error => reject(error);
    });
}

const headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
};

const data = {
    api_key: '<organization_api_key>',
    image_b64: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...',
    photo_type: 'other',
    is_verified: true,
    aliases: [
        {
            value: '+77071234567',
            type: 'phone'
        },
        {
            value: '123456789012',
            type: 'personal_number'
        }
    ]
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

Пример ответа:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "organization": "550e8400-e29b-41d4-a716-446655440001",
  "is_verified": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "aliases": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "value": "550e8400-e29b-41d4-a716-446655440000",
      "type": "system_id"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "value": "+77071234567",
      "type": "phone"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440004",
      "value": "123456789012",
      "type": "personal_number"
    }
  ],
  "photos": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440005",
      "type": "other",
      "is_default": true,
      "is_uploaded": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

3. Обновление персоны#

Позволяет изменить статус верификации существующей персоны.

URL запроса:

https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/update

Формат запроса	Метод запроса
JSON	POST

Наименование поля	Тип	Обязательно	Описание
api_key	String	Да	API KEY организации в личном кабинете
is_verified	Boolean	Да	Новый статус верификации персоны

Примеры запроса:

cURLPythonJavaScript

curl -X 'POST' \
'https://kyc.biometric.kz/api/v1/backend/persons/550e8400-e29b-41d4-a716-446655440000/update' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "api_key": "<organization_api_key>",
  "is_verified": false
}'

import requests

person_id = '550e8400-e29b-41d4-a716-446655440000'
url = f'https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/update'

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}

data = {
    'api_key': '<organization_api_key>',
    'is_verified': False
}

response = requests.post(url, headers=headers, json=data)

print(response.json())

const personId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://kyc.biometric.kz/api/v1/backend/persons/${personId}/update`;

const headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
};

const data = {
    api_key: '<organization_api_key>',
    is_verified: false
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

4. Добавление фотографии к персоне#

Позволяет добавить дополнительную фотографию к существующей персоне.

URL запроса:

https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/photo/

Формат запроса	Метод запроса
JSON	POST

Наименование поля	Тип	Обязательно	Описание
api_key	String	Да	API KEY организации в личном кабинете
image_b64	String	Да	Изображение в формате Base64
photo_type	String	Да	Тип фотографии: `digital`, `scan`, `live`, `other`
is_default	Boolean	Да	Сделать эту фотографию основной для персоны

Примеры запроса:

cURLPythonJavaScript

curl -X 'POST' \
'https://kyc.biometric.kz/api/v1/backend/persons/550e8400-e29b-41d4-a716-446655440000/photo/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "api_key": "<organization_api_key>",
  "image_b64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...",
  "photo_type": "digital",
  "is_default": true
}'

import requests
import base64

# Кодирование изображения в base64
with open('new_photo.jpg', 'rb') as image_file:
    encoded_image = base64.b64encode(image_file.read()).decode('utf-8')
    image_b64 = f"data:image/jpeg;base64,{encoded_image}"

person_id = '550e8400-e29b-41d4-a716-446655440000'
url = f'https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/photo/'

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}

data = {
    'api_key': '<organization_api_key>',
    'image_b64': image_b64,
    'photo_type': 'digital',
    'is_default': True
}

response = requests.post(url, headers=headers, json=data)

print(response.json())

const personId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://kyc.biometric.kz/api/v1/backend/persons/${personId}/photo/`;

const headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
};

const data = {
    api_key: '<organization_api_key>',
    image_b64: 'data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD...',
    photo_type: 'digital',
    is_default: true
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

5. Добавление алиаса к персоне#

Позволяет добавить новый идентификатор (алиас) к существующей персоне.

URL запроса:

https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/alias/

Формат запроса	Метод запроса
JSON	POST

Наименование поля	Тип	Обязательно	Описание
api_key	String	Да	API KEY организации в личном кабинете
value	String	Да	Значение алиаса (номер телефона, ИИН, номер документа и т.д.)
type	String	Да	Тип алиаса: `phone`, `personal_number`, `document_number`, `custom`

Необходимо учесть

Нельзя создавать алиасы типа system_id - они создаются автоматически
Значения алиасов должны быть уникальными в рамках организации
При попытке добавить существующий алиас вернется ошибка с детализацией конфликта

Примеры запроса:

cURLPythonJavaScript

curl -X 'POST' \
'https://kyc.biometric.kz/api/v1/backend/persons/550e8400-e29b-41d4-a716-446655440000/alias/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "api_key": "<organization_api_key>",
  "value": "AB1234567",
  "type": "document_number"
}'

import requests

person_id = '550e8400-e29b-41d4-a716-446655440000'
url = f'https://kyc.biometric.kz/api/v1/backend/persons/{person_id}/alias/'

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
}

data = {
    'api_key': '<organization_api_key>',
    'value': 'AB1234567',
    'type': 'document_number'
}

response = requests.post(url, headers=headers, json=data)

print(response.json())

const personId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://kyc.biometric.kz/api/v1/backend/persons/${personId}/alias/`;

const headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json'
};

const data = {
    api_key: '<organization_api_key>',
    value: 'AB1234567',
    type: 'document_number'
};

fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error(error));

Типы фотографий#

Значение	Приоритет	Описание
digital	1	Цифровое фото из чипа документа
scan	2	Портрет со сканированного документа
live	3	Лучший кадр с liveness-проверки
other	4	Загруженные вручную или прочие фотографии

Автоматическое управление основным фото

При добавлении фотографии с более высоким приоритетом и флагом is_default: true, она автоматически становится основной, а предыдущая основная фотография теряет этот статус.

Типы алиасов#

Значение	Описание	Особенности
system_id	Внутренний UUID персоны	Создается автоматически, неизменяемый
phone	Номер телефона	Формат: +77071234567
personal_number	ИИН (персональный номер)	12 цифр
document_number	Номер документа (паспорт, удостоверение)	Любой формат
custom	Пользовательский идентификатор	Любой формат

Ошибки#

Код состояния	Ответ	Описание
400	Invalid API key	Неверный или отсутствующий API ключ организации
400	Person not found	Персона с указанным ID не найдена или не принадлежит вашей организации
400	Invalid image format	Неверный формат изображения или поврежденные данные Base64
400	Invalid photo type	Неверный тип фотографии. Допустимые значения: digital, scan, live, other
400	Invalid alias type	Неверный тип алиаса. Допустимые значения: phone, personal_number, document_number, custom
400	Cannot create system_id alias	Алиасы типа system_id создаются автоматически и не могут быть добавлены вручную
400	Alias already exists	Алиас с таким значением уже существует в организации
400	Person limit exceeded	Превышен лимит количества персон для вашей подписки
400	Cannot delete default photo	Нельзя удалить единственное основное фото персоны
400	Client does not have access to Persons technology	У клиента нет доступа к технологии "Персоны". Причины: подписка отсутствует, истекла, или технология не активна
400	Subscription has not started	Подписка еще не активировалась
400	No active or future subscription for technology	Нет активной или будущей подписки на технологию "Персоны"
400	Client does not have subscription	У клиента отсутствует подписка, подробнее о подписках можно прочитать здесь
400	File extension is not allowed	Неподдерживаемое расширение файла. Разрешены только: JPEG, JPG, PNG
404	Organization not found	Организация с указанным API ключом не найдена
422	Validation error	Ошибка валидации входных данных. Проверьте обязательные поля и их форматы
500	Internal server error	Внутренняя ошибка сервера. Обратитесь в техническую поддержку

Детализация ошибок

Для ошибок валидации (код 400, 422) в ответе будет содержаться детальная информация о том, какое именно поле содержит ошибку и что нужно исправить.

Обработка ошибок алиасов

При попытке добавить уже существующий алиас, в ответе будет указан список всех конфликтующих значений и ID персон, которым они принадлежат.