sdk-velix-cpp

SDK oficial C++ (pré-release) para a plataforma VELIX Biometrics — controle de acesso por biometria facial.

Pré-release: ainda não bate contra uma API pública versionada estável (task #593/#616). Cobre a superfície /v1/api/* (Velix.ID: onboarding, checkin, LGPD, dados próprios; Velix Events: criar/consultar convidado). Velix Time não tem endpoint na superfície de API key ainda.

Requisitos

• CMake >= 3.16
• Compilador C++17 (GCC, Clang ou MSVC)
• libcurl (dev headers) — apt install libcurl4-openssl-dev / brew install curl
• nlohmann/json — baixado automaticamente via FetchContent no build

Build

cmake -S . -B build
cmake --build build

Uso

#include "velix/client.hpp"

velix::ClientConfig cfg;
cfg.api_url = "https://api.velixbiometrics.com";
cfg.api_key = "vlx_<hex>";  // enviado como header x-api-key

velix::VelixClient client(cfg);

velix::OnboardingRequest req;
req.name = "Fulano de Tal";
req.frames = {frame1_base64, frame2_base64, frame3_base64};

try {
  velix::OnboardingResponse r = client.Enroll(req);
  std::cout << "person_id: " << r.person_id << std::endl;
} catch (const velix::AuthError& e) {
  // credenciais inválidas ou API key sem escopo onboarding:write
} catch (const velix::VelixError& e) {
  std::cerr << e.code() << ": " << e.message() << std::endl;
}

Autenticação

Header x-api-key: vlx_<hex>. Cada API key tem scopes: string[] — escopos granulares usados: onboarding:write, checkin:write, lgpd:write, me:read, events:read, events:write.

Métodos

Método	Endpoint	Escopo
Enroll(OnboardingRequest)	POST /v1/api/onboarding	onboarding:write
Identify(CheckinIdentifyRequest)	POST /v1/api/checkin/identify	checkin:write
RequestDeletion(person_id)	POST /v1/api/deletion-request	lgpd:write
GetMe(person_id)	GET /v1/api/me/{personId}	me:read
CreateGuest(event_id, CreateGuestRequest)	POST /v1/api/events/{id}/guests	events:write
GetGuest(event_id, guest_id)	GET /v1/api/events/{id}/guests/{guestId}	events:read

Toda resposta 4xx/5xx lança um subtipo de velix::VelixError (AuthError, NotFoundError, BiometricError, RateLimitError, ServerError) com code()/message() extraídos do envelope real de erro ({"error":{"code":"...","message":"..."}}). Erros de rede/conexão lançam velix::NetworkError.

Timeout

Default de 30s (ClientConfig::timeout), conforme contrato oficial — payloads de checkin/onboarding com liveness samples podem chegar a 6-12MB.

Licença

Ver LICENSE na raiz do monorepo VELIX.