API Reference

Referência completa de todos os endpoints públicos da Velix (api-velix-identity-core), que atua como BFF único da plataforma para integradores externos.

:::info OpenAPI interativo A spec OpenAPI completa está disponível em https://api.velixbiometrics.com/docs (Swagger UI) e https://api.velixbiometrics.com/docs-json (JSON bruto para ferramentas como Insomnia/Postman). :::

:::caution Escopo desta referência Esta página cobre apenas os endpoints voltados a integradores externos (tenant admin, portal do colaborador, dispositivos/edge). Endpoints usados exclusivamente pelo app-velix-admin interno (infra, faturamento de plataforma, catálogo de planos, logs, métricas) não são documentados aqui — são internos ao produto. :::

---

Base URL

https://api.velixbiometrics.com

Sandbox:

https://sandbox-api.velixbiometrics.com

---

Autenticação

Método	Path	Descrição
POST	/v1/auth/login	Login com email/senha, retorna access token + cookie de refresh
POST	/v1/auth/refresh	Renova o access token a partir do cookie de refresh
POST	/v1/auth/logout	Revoga o refresh token
GET	/v1/auth/me	Perfil do usuário autenticado
GET	/v1/auth/products	Lista produtos Velix disponíveis para o usuário (usado pelo SSO hub)
POST	/v1/auth/mfa/setup	Gera segredo TOTP + QR code
POST	/v1/auth/mfa/enable	Habilita MFA após confirmar código TOTP
POST	/v1/auth/mfa/verify	Verifica código TOTP
DELETE	/v1/auth/mfa/disable	Desabilita MFA

API Keys nativas

:::caution Endpoint corrigido Não existe POST /v1/auth/api-keys. A criação e gestão de API keys é feita através do recurso applications, autenticado com um JWT de sessão (tenant admin), não apenas com uma API key existente. :::

Método	Path	Descrição
GET	/v1/applications	Lista aplicações do tenant
POST	/v1/applications	Cria uma aplicação (retorna a primeira API key em texto puro, uma única vez)
DELETE	/v1/applications/:id	Remove uma aplicação
GET	/v1/applications/:id/api-keys	Lista API keys da aplicação
POST	/v1/applications/:id/api-keys	Cria uma nova API key para a aplicação
POST	/v1/applications/:id/api-keys/:keyId/rotate	Rotaciona (invalida a antiga, emite uma nova)
DELETE	/v1/applications/:id/api-keys/:keyId	Revoga uma API key

---

Tenant

Método	Path	Descrição
GET	/v1/tenants/:id	Dados do tenant
PATCH	/v1/tenants/:id	Atualiza dados básicos do tenant
GET	/v1/tenants/:id/settings	Configurações do tenant (webhookUrl, geofenceRadiusMetros, age_policy, etc.)
PATCH	/v1/tenants/:id/settings	Atualiza configurações do tenant

---

Pessoas

Método	Path	Descrição
GET	/v1/persons	Lista pessoas do tenant (paginado, filtrável)
POST	/v1/persons	Cria pessoa
GET	/v1/persons/:id	Busca pessoa por ID
PATCH	/v1/persons/:id	Atualiza pessoa
DELETE	/v1/persons/:id	Remove pessoa
POST	/v1/persons/upsert	Cria ou atualiza pessoa por externalId — recomendado para sync com ERPs
POST	/v1/persons/import	Importação em lote (máx. 500 linhas por chamada)
POST	/v1/persons/:id/send-enrollment-link	Envia link de auto-cadastro biométrico por email
DELETE	/v1/persons/:id/data	Anonimiza dados pessoais (LGPD)

:::caution Endpoints corrigidos POST /v1/persons/:id/enroll e POST /v1/persons/batch não existem. O enroll biométrico é feito pelo módulo de onboarding (ver abaixo), e a importação em lote é POST /v1/persons/import. :::

Cadastro biométrico (onboarding)

Método	Path	Descrição
POST	/v1/onboarding	Cria Person + Identity + enroll biométrico em uma chamada (uso admin)
GET	/v1/public/onboarding/health	Verifica disponibilidade do motor biométrico
POST	/v1/public/onboarding/register	Registro público — retorna enrollment_token
POST	/v1/public/onboarding/verify-token	Valida um enrollment_token pré-cadastrado
POST	/v1/public/onboarding/enroll	Enroll biométrico público (fluxo app-velix-onboarding)

---

Check-in

Método	Path	Descrição
POST	/v1/checkin/manual	Check-in manual pelo admin (sem câmera/QR)
GET	/v1/checkin/identities/:identityId/qr-token	Gera/consulta token de QR code da identidade
DELETE	/v1/checkin/identities/:identityId/qr-token	Revoga o QR token
GET	/v1/public/checkin/:tenantSlug/liveness/challenge	Nonce anti-replay para prova de vida (HMAC)
POST	/v1/public/checkin/:tenantSlug/identify	Identifica a face, grava imagem, publica evento Kafka e AuditLog
GET	/v1/public/checkin/qr/:token	Resolve check-in via QR code
GET	/v1/public/checkin/link/:token	Resolve check-in via link
POST	/v1/sync/batch	Sincroniza lote de check-ins offline registrados por dispositivos edge — requer header x-internal-secret (uso de dispositivo/edge, não de integrador via Bearer token)

:::caution Endpoint corrigido POST /v1/events/:id/checkin e GET /v1/events/:id/checkins não existem. O fluxo de check-in público passa por /v1/public/checkin/:tenantSlug/identify (identity-core atua como BFF — nunca chame o api-velix-vision diretamente). Histórico de check-ins de uma pessoa está disponível via GET /v1/me/checkins (portal do colaborador). :::

---

Eventos

Método	Path	Descrição
GET	/v1/events	Lista eventos do tenant
POST	/v1/events	Cria evento
GET	/v1/events/:id	Busca evento
PATCH	/v1/events/:id	Atualiza evento
PATCH	/v1/events/:id/config	Configura evento (métodos de check-in, capacidade, geofence)
PATCH	/v1/events/:id/status	Atualiza status do evento
DELETE	/v1/events/:id	Remove evento
GET	/v1/events/:token/branding	Branding público do evento (por token)
GET	/v1/events/:token/confirmed-list	Lista pública de confirmados (modo offline)

Convidados

Método	Path	Descrição
POST	/v1/events/:id/guests	Cria convidado
GET	/v1/events/:id/guests	Lista convidados (busca/status/paginado)
PATCH	/v1/events/:id/guests/:guestId	Atualiza convidado
DELETE	/v1/events/:id/guests/:guestId	Remove convidado
POST	/v1/events/:id/guests/import	Importa convidados via upload Excel
POST	/v1/events/:id/guests/invite	Envia convites
POST	/v1/events/:id/guests/reinvite	Reenvia convites
GET	/v1/events/:eventToken/guests/:guestToken	Dados mínimos do convidado por token (nunca expõe cpf/telefone/data de nascimento/email)
PATCH	/v1/events/:eventToken/guests/:guestToken/confirm	Confirma presença por token

---

Portal do colaborador (/v1/me)

Autenticado com JWT de portal (type: 'person_portal'), obtido via magic link — não o Bearer token de integrador.

Método	Path	Descrição
POST	/v1/portal/auth/magic-link	Solicita magic link de acesso ao portal
GET	/v1/portal/auth/magic-link/verify	Verifica o token do magic link, retorna JWT de portal
GET	/v1/me	Dados pessoais do colaborador autenticado
PATCH	/v1/me	Atualiza dados pessoais (nome/telefone/foto)
GET	/v1/me/sessions	Lista sessões de login do portal
GET	/v1/me/biometrics	Status biométrico por tenant
DELETE	/v1/me/biometrics/:tenantId	Solicita revogação de biometria em um tenant
GET	/v1/me/checkins	Histórico de check-ins, paginado
GET	/v1/me/notification-preferences	Preferências de notificação
PATCH	/v1/me/notification-preferences	Atualiza preferências de notificação
GET	/v1/me/biometric-images	Lista metadados de imagens biométricas
GET	/v1/me/biometric-images/:id/file	Stream de uma imagem biométrica

LGPD

Método	Path	Descrição
POST	/v1/me/deletion-request	Solicita exclusão de conta (LGPD) — emite identity.deletion_requested no Kafka
GET	/v1/me/deletion-request	Consulta status da solicitação de exclusão
DELETE	/v1/me/deletion-request	Cancela a solicitação de exclusão
POST	/v1/portal/auth/deletion-confirm	Confirma a exclusão via token recebido por email
POST	/v1/me/data-export	Solicita exportação de dados pessoais (portabilidade LGPD) — envia email quando pronto

---

Webhooks

:::caution Não é um recurso REST dedicado Não há POST/GET/DELETE /v1/webhooks. A entrega de webhooks é configurada através do campo webhookUrl nas configurações do tenant (PATCH /v1/tenants/:id/settings). Veja o guia de Webhooks para a lista de eventos, formato do payload e validação de assinatura HMAC-SHA256. :::

Método	Path	Descrição
GET	/v1/tenants/:id/settings	Consulta webhookUrl atual
PATCH	/v1/tenants/:id/settings	Define/atualiza webhookUrl

---

Health check

Método	Path	Descrição
GET	/v1/health/live	Liveness probe
GET	/v1/health/ready	Readiness probe (checa conexão com o banco)