Cadastrar pessoas

Uma pessoa no Velix tem dados cadastrais (nome, documento) e, opcionalmente, um embedding biométrico. O check-in facial só funciona após o enroll.

---

Criar pessoa

TypeScript

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

const persons = new PersonsModule(velix);

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

Python

from velix.modules.persons import PersonsModule

persons = PersonsModule(velix)
person = persons.create({"name": "Ana Silva", "document": "123.456.789-00"})

cURL

curl -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"}'

---

Enroll biométrico

O enroll registra o embedding facial da pessoa. Envie uma foto nítida, frontal, com boa iluminação.

A imagem deve ser enviada como base64 do JPEG ou PNG.

TypeScript

import { readFileSync } from 'fs';

const foto = readFileSync('foto.jpg').toString('base64');
const result = await persons.enroll(person.id, foto);

console.log(`Qualidade: ${result.quality}`); // 0.0–1.0

Python

import base64

with open("foto.jpg", "rb") as f:
    foto = base64.b64encode(f.read()).decode()

result = persons.enroll(person["id"], foto)
print(f"Qualidade: {result['quality']}")

cURL

FOTO=$(base64 -i foto.jpg)

curl -X POST "https://api.velixbiometrics.com/v1/persons/$PERSON_ID/enroll" \
  -H "Authorization: Bearer $VELIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"frame\":\"$FOTO\"}"

:::tip Qualidade mínima A Velix rejeita fotos com qualidade abaixo do biometricQualityLevel configurado no tenant. Se receber 400 face_quality_too_low, tente uma foto com melhor iluminação e enquadramento frontal. :::

---

Importar em lote

Para importar muitas pessoas de uma vez, use POST /v1/persons/batch:

curl -X POST https://api.velixbiometrics.com/v1/persons/batch \
  -H "Authorization: Bearer $VELIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persons": [
      {"name": "Ana Silva", "document": "123.456.789-00"},
      {"name": "Carlos Souza", "document": "987.654.321-00"}
    ]
  }'

O enroll biométrico de cada pessoa deve ser feito individualmente após a importação.