Início rápido

Coloque seu tenant em produção em menos de 10 minutos.

Pré-requisitos

• Bearer token fornecido pela equipe Velix
• Ambiente de desenvolvimento configurado na linguagem de sua escolha

---

1. Instalar o SDK (opcional)

SDKs oficiais disponíveis para TypeScript/JavaScript e Python. Para outras linguagens, use a API REST diretamente.

TypeScript

npm install @velix/sdk

JavaScript

npm install @velix/sdk

PHP

# Sem SDK oficial — use a API REST com cURL ou Guzzle
composer require guzzlehttp/guzzle

C#

# Sem SDK oficial — use HttpClient nativo
dotnet add package System.Net.Http.Json

Java

<!-- Sem SDK oficial — use OkHttp ou RestTemplate -->
<dependency>
  <groupId>com.squareup.okhttp3</groupId>
  <artifactId>okhttp</artifactId>
  <version>4.12.0</version>
</dependency>

Rust

# Cargo.toml — sem SDK oficial, use reqwest
[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde_json = "1"

Go

# Sem SDK oficial — use net/http nativo
go get github.com/google/go-querystring/query

Kotlin

implementation("com.velix:velix-sdk-kotlin:0.1.0-alpha.1")

Ruby

gem "velix-sdk", "~> 0.1.0.pre"

Swift

.package(url: "https://github.com/velix/velix-sdk-swift", from: "0.1.0-alpha.1")

Dart

dependencies:
  velix_sdk: ^1.0.0

Elixir

def deps do
  [{:velix, "~> 0.1.0-alpha.1"}]
end

Lua

luarocks install velix-sdk

PowerShell

Install-Module VelixSDK -Scope CurrentUser

Delphi

# Sem SDK via package manager — adicionar Source/ ao search path do projeto

cURL

Nenhuma instalação necessária.

---

2. Configurar o cliente

TypeScript

import { VelixClient } from '@velix/sdk';

const velix = new VelixClient({
  apiUrl: 'https://api.velixbiometrics.com',
  apiKey: process.env.VELIX_API_KEY!,
});

JavaScript

const { VelixClient } = require('@velix/sdk');

const velix = new VelixClient({
  apiUrl: 'https://api.velixbiometrics.com',
  apiKey: process.env.VELIX_API_KEY,
});

PHP

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://api.velixbiometrics.com',
    'headers'  => [
        'Authorization' => 'Bearer ' . getenv('VELIX_API_KEY'),
        'Content-Type'  => 'application/json',
    ],
]);

C#

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.BaseAddress = new Uri("https://api.velixbiometrics.com");
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("VELIX_API_KEY"));

Java

import okhttp3.OkHttpClient;
import okhttp3.Request;

OkHttpClient client = new OkHttpClient();
String apiKey = System.getenv("VELIX_API_KEY");

// Montar header em cada request:
Request.Builder builder = new Request.Builder()
    .header("Authorization", "Bearer " + apiKey)
    .header("Content-Type", "application/json");

Rust

use reqwest::Client;

let client = Client::new();
let api_key = std::env::var("VELIX_API_KEY").expect("VELIX_API_KEY not set");
let base_url = "https://api.velixbiometrics.com";

Go

package main

import (
    "net/http"
    "os"
)

var (
    apiKey  = os.Getenv("VELIX_API_KEY")
    baseURL = "https://api.velixbiometrics.com"
)

func newRequest(method, path string) *http.Request {
    req, _ := http.NewRequest(method, baseURL+path, nil)
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")
    return req
}

Kotlin

import com.velix.sdk.VelixClient

val velix = VelixClient {
    apiUrl = "https://api.velixbiometrics.com"
    apiKey = System.getenv("VELIX_API_KEY")
}

Ruby

require "velix"

velix = Velix::Client.new(
  api_url: "https://api.velixbiometrics.com",
  api_key: ENV["VELIX_API_KEY"]
)

Swift

import VelixSDK

let velix = VelixClient(config: VelixConfig(
    apiURL: URL(string: "https://api.velixbiometrics.com")!,
    apiKey: ProcessInfo.processInfo.environment["VELIX_API_KEY"]!
))

Dart

import 'package:velix_sdk/velix_sdk.dart';

final velix = VelixClient(VelixConfig(
  apiUrl: 'https://api.velixbiometrics.com',
  apiKey: Platform.environment['VELIX_API_KEY']!,
));

Elixir

# config/runtime.exs
config :velix,
  api_url: "https://api.velixbiometrics.com",
  api_key: System.fetch_env!("VELIX_API_KEY")

Lua

local velix = require("velix")

local client = velix.Client.new({
  api_url = "https://api.velixbiometrics.com",
  api_key = os.getenv("VELIX_API_KEY"),
})

PowerShell

Import-Module VelixSDK

Connect-Velix -ApiUrl "https://api.velixbiometrics.com" -ApiKey $env:VELIX_API_KEY

Delphi

uses Velix.Client;

var
  Client: TVelixClient;
begin
  Client := TVelixClient.Create(
    'https://api.velixbiometrics.com',
    GetEnvironmentVariable('VELIX_API_KEY')
  );

cURL

export VELIX_API_KEY="seu_token_aqui"

# Teste de autenticação
curl https://api.velixbiometrics.com/v1/auth/me \
  -H "Authorization: Bearer $VELIX_API_KEY"

---

3. Cadastrar uma pessoa

:::caution Endpoint REST corrigido Os exemplos abaixo usam persons.enroll(...) como chamada de SDK ilustrativa. O endpoint REST real por trás do enroll biométrico é POST /v1/public/onboarding/enroll (fluxo de onboarding), não POST /v1/persons/:id/enroll — esse endpoint não existe. Veja a referência de API. :::

TypeScript

import { PersonsModule } from '@velix/sdk';

const persons = new PersonsModule(velix);

const person = await persons.create({
  name: 'Ana Silva',
  document: '123.456.789-00',
});

// Enroll biométrico (foto em base64)
await persons.enroll(person.id, fotoBase64);
console.log(`Pessoa cadastrada: ${person.id}`);

JavaScript

const { PersonsModule } = require('@velix/sdk');

const persons = new PersonsModule(velix);

const person = await persons.create({
  name: 'Ana Silva',
  document: '123.456.789-00',
});

await persons.enroll(person.id, fotoBase64);
console.log(`Pessoa cadastrada: ${person.id}`);

PHP

$res = $client->post('/v1/persons', [
    'json' => ['name' => 'Ana Silva', 'document' => '123.456.789-00'],
]);
$person = json_decode($res->getBody(), true);

$client->post("/v1/persons/{$person['id']}/enroll", [
    'json' => ['frame' => $fotoBase64],
]);
echo "Pessoa cadastrada: {$person['id']}";

C#

using System.Net.Http.Json;

var res = await client.PostAsJsonAsync("/v1/persons", new {
    name = "Ana Silva", document = "123.456.789-00"
});
var person = await res.Content.ReadFromJsonAsync<Person>();

await client.PostAsJsonAsync($"/v1/persons/{person.Id}/enroll", new {
    frame = fotoBase64
});
Console.WriteLine($"Pessoa cadastrada: {person.Id}");

Java

import okhttp3.*;
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper();

String body = mapper.writeValueAsString(Map.of(
    "name", "Ana Silva", "document", "123.456.789-00"
));
Request req = builder.url(apiKey + "/v1/persons")
    .post(RequestBody.create(body, MediaType.get("application/json")))
    .build();

Response res = client.newCall(req).execute();
Map person = mapper.readValue(res.body().string(), Map.class);

String enrollBody = mapper.writeValueAsString(Map.of("frame", fotoBase64));
Request enrollReq = builder.url(baseUrl + "/v1/persons/" + person.get("id") + "/enroll")
    .post(RequestBody.create(enrollBody, MediaType.get("application/json")))
    .build();
client.newCall(enrollReq).execute();

Rust

use serde_json::json;

let person: serde_json::Value = client
    .post(format!("{}/v1/persons", base_url))
    .bearer_auth(&api_key)
    .json(&json!({"name": "Ana Silva", "document": "123.456.789-00"}))
    .send().await?
    .json().await?;

let person_id = person["id"].as_str().unwrap();

client.post(format!("{}/v1/persons/{}/enroll", base_url, person_id))
    .bearer_auth(&api_key)
    .json(&json!({"frame": foto_base64}))
    .send().await?;

println!("Pessoa cadastrada: {}", person_id);

Go

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

body, _ := json.Marshal(map[string]string{
    "name": "Ana Silva", "document": "123.456.789-00",
})
req, _ := http.NewRequest("POST", baseURL+"/v1/persons", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
var person map[string]interface{}
json.NewDecoder(resp.Body).Decode(&person)

enrollBody, _ := json.Marshal(map[string]string{"frame": fotoBase64})
enrollReq, _ := http.NewRequest("POST",
    fmt.Sprintf("%s/v1/persons/%s/enroll", baseURL, person["id"]),
    bytes.NewReader(enrollBody))
enrollReq.Header.Set("Authorization", "Bearer "+apiKey)
enrollReq.Header.Set("Content-Type", "application/json")
http.DefaultClient.Do(enrollReq)

fmt.Printf("Pessoa cadastrada: %s\n", person["id"])

Kotlin

val person = velix.persons.create(name = "Ana Silva", document = "123.456.789-00")
velix.persons.enroll(person.id, fotoBase64)
println("Pessoa cadastrada: ${person.id}")

Ruby

person = velix.persons.create(name: "Ana Silva", document: "123.456.789-00")
velix.persons.enroll(person.id, foto_base64)
puts "Pessoa cadastrada: #{person.id}"

Swift

let person = try await velix.persons.create(name: "Ana Silva", document: "123.456.789-00")
try await velix.persons.enroll(personID: person.id, fotoBase64: fotoBase64)
print("Pessoa cadastrada: \(person.id)")

Dart

final person = await velix.persons.create(name: 'Ana Silva', document: '123.456.789-00');
await velix.persons.enroll(person.id, fotoBase64);
print('Pessoa cadastrada: ${person.id}');

Elixir

{:ok, person} = Velix.Persons.create(%{name: "Ana Silva", document: "123.456.789-00"})
Velix.Persons.enroll(person.id, foto_base64)
IO.puts("Pessoa cadastrada: #{person.id}")

Lua

local person = client.persons:create({name = "Ana Silva", document = "123.456.789-00"})
client.persons:enroll(person.id, foto_base64)
print("Pessoa cadastrada: " .. person.id)

PowerShell

$person = New-VelixPerson -Name "Ana Silva" -Document "123.456.789-00"
Invoke-VelixEnroll -PersonId $person.Id -FotoBase64 $fotoBase64
Write-Host "Pessoa cadastrada: $($person.Id)"

Delphi

Person := Client.Persons.Create('Ana Silva', '123.456.789-00');
Client.Persons.Enroll(Person.Id, FotoBase64);
WriteLn('Pessoa cadastrada: ' + Person.Id);

cURL

# 1. Criar pessoa
PERSON=$(curl -s -X POST https://api.velixbiometrics.com/v1/persons \
  -H "Authorization: Bearer $VELIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Ana Silva","document":"123.456.789-00"}')

PERSON_ID=$(echo $PERSON | jq -r '.id')

# 2. Enroll biométrico
curl -X POST "https://api.velixbiometrics.com/v1/public/onboarding/enroll" \
  -H "Authorization: Bearer $VELIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"personId\":\"$PERSON_ID\",\"frame\":\"$FOTO_BASE64\"}"

echo "Pessoa cadastrada: $PERSON_ID"

---

4. Processar um check-in

:::caution Endpoint REST corrigido Os exemplos abaixo usam checkin.facial(...) como chamada de SDK ilustrativa. O endpoint REST real é POST /v1/public/checkin/:tenantSlug/identify — não existe POST /v1/events/:id/checkin. O identity-core atua como BFF: nunca chame o api-velix-vision diretamente. Veja o guia de fluxo de check-in e a referência de API. :::

TypeScript

import { CheckinModule } from '@velix/sdk';

const checkin = new CheckinModule(velix);
const result = await checkin.facial('SEU_EVENTO_ID', frameBase64);

if (result.success) {
  console.log(`✅ Check-in aprovado: ${result.personId}`);
} else {
  console.log('❌ Biometria não reconhecida');
}

JavaScript

const { CheckinModule } = require('@velix/sdk');

const checkin = new CheckinModule(velix);
const result = await checkin.facial('SEU_EVENTO_ID', frameBase64);

if (result.success) {
  console.log(`✅ Check-in aprovado: ${result.personId}`);
}

PHP

$res = $client->post('/v1/events/SEU_EVENTO_ID/checkin', [
    'json' => ['method' => 'facial', 'frame' => $frameBase64],
]);
$result = json_decode($res->getBody(), true);

if ($result['success']) {
    echo "✅ Check-in aprovado: {$result['personId']}";
}

C#

var res = await client.PostAsJsonAsync("/v1/events/SEU_EVENTO_ID/checkin", new {
    method = "facial",
    frame = frameBase64,
});
var result = await res.Content.ReadFromJsonAsync<CheckinResult>();

if (result.Success)
    Console.WriteLine($"✅ Check-in aprovado: {result.PersonId}");

Java

String body = mapper.writeValueAsString(Map.of(
    "method", "facial", "frame", frameBase64
));
Request req = builder
    .url(baseUrl + "/v1/events/SEU_EVENTO_ID/checkin")
    .post(RequestBody.create(body, MediaType.get("application/json")))
    .build();

Response res = client.newCall(req).execute();
Map result = mapper.readValue(res.body().string(), Map.class);
if ((Boolean) result.get("success"))
    System.out.println("✅ Check-in aprovado: " + result.get("personId"));

Rust

let result: serde_json::Value = client
    .post(format!("{}/v1/events/SEU_EVENTO_ID/checkin", base_url))
    .bearer_auth(&api_key)
    .json(&json!({"method": "facial", "frame": frame_base64}))
    .send().await?
    .json().await?;

if result["success"].as_bool().unwrap_or(false) {
    println!("✅ Check-in aprovado: {}", result["personId"]);
}

Go

body, _ := json.Marshal(map[string]string{
    "method": "facial", "frame": frameBase64,
})
req, _ := http.NewRequest("POST",
    baseURL+"/v1/events/SEU_EVENTO_ID/checkin",
    bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)

if result["success"] == true {
    fmt.Printf("✅ Check-in aprovado: %s\n", result["personId"])
}

Kotlin

val result = velix.checkin.facial("SEU_EVENTO_ID", frameBase64)
if (result.success) println("✅ Check-in aprovado: ${result.personId}")

Ruby

result = velix.checkin.facial("SEU_EVENTO_ID", frame_base64)
puts "✅ Check-in aprovado: #{result.person_id}" if result.success

Swift

let result = try await velix.checkin.facial(eventId: "SEU_EVENTO_ID", frameBase64: frameBase64)
if result.success { print("✅ Check-in aprovado: \(result.personId)") }

Dart

final result = await velix.checkin.facial('SEU_EVENTO_ID', frameBase64);
if (result.success) print('✅ Check-in aprovado: ${result.personId}');

Elixir

{:ok, result} = Velix.Checkin.facial("SEU_EVENTO_ID", frame_base64)
if result.success, do: IO.puts("✅ Check-in aprovado: #{result.person_id}")

Lua

local result = client.checkin:facial("SEU_EVENTO_ID", frame_base64)
if result.success then print("✅ Check-in aprovado: " .. result.person_id) end

PowerShell

$result = Invoke-VelixCheckin -EventId "SEU_EVENTO_ID" -FrameBase64 $frameBase64
if ($result.Success) { Write-Host "✅ Check-in aprovado: $($result.PersonId)" }

Delphi

Result := Client.Checkin.Facial('SEU_EVENTO_ID', FrameBase64);
if Result.Success then
  WriteLn('Check-in aprovado: ' + Result.PersonId);

cURL

curl -X POST "https://api.velixbiometrics.com/v1/public/checkin/SEU_TENANT_SLUG/identify" \
  -H "Authorization: Bearer $VELIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"frame\":\"$FRAME_BASE64\"}"

---

Próximos passos

• Configurar webhooks para receber eventos em tempo real
• Configurar geofence para restringir check-ins por localização
• Importar pessoas em lote