Identidade digital que vai além
da senha.
Integre biometria palmar, reconhecimento facial e liveness detection de classe mundial na sua aplicação com uma única API REST. Infraestrutura neutra, base centralizada, máxima segurança.
Biometria Palmar
Identificação por veia palmar com FAR < 0.0001% e FRR < 0.1%
Reconhecimento Facial
1:N e 1:1 com acurácia de 99.8% em bases de milhões
Liveness Detection
Anti-spoofing contra deepfake, foto e vídeo com IA generativa
Palm Payment
Pagamento transparente pela palma da mão. Sem cartão, sem celular.
Hub Neutro
Base centralizada de biometria — sem canibalismo entre instituições
Produtos disponíveis
Soluções biométricas enterprise para bancos, fintechs, órgãos públicos e varejo.
Treeal Palmar ID
Identificação de pessoas pela geometria e padrão venoso da palma da mão. Tecnologia Tencent Cloud adaptada para o mercado brasileiro. Captura contactless, leitura em < 1s.
Treeal Face ID
Reconhecimento facial 1:1 e 1:N de alta performance. Integra liveness passivo e ativo, detecção de deepfake em tempo real e busca em grandes bases biométricas.
Treeal Liveness
Prova de vivacidade passiva e ativa. Detecta ataques de apresentação usando fotos impressas, máscaras 3D, replay de vídeo e deepfakes gerados por IA generativa.
Palm Payment
Pagamento biométrico pela palma da mão. Integração com bandeiras e adquirentes via Positivo Informática (hardware). Zero fricção: o usuário apenas aproxima a mão.
Ecossistema de parceiros
Treeal ID como hub neutro entre a tecnologia e as instituições.
Em 5 minutos rodando.
Do cadastro à primeira verificação biométrica com um mínimo de código.
Autenticação e primeiro chamado
Siga os passos abaixo para integrar a Treeal ID API na sua aplicação.
-
Obtenha seu token de acesso
Gere um access_token JWT usando suas credenciais de cliente. O token expira em 3600 segundos.
HTTP RequestPOST https://api.treeal.id/v2/auth/token Content-Type: application/json { "client_id": "seu_client_id", "client_secret": "seu_client_secret", "grant_type": "client_credentials" }cURLcurl -X POST https://api.treeal.id/v2/auth/token \ -H "Content-Type: application/json" \ -d '{"client_id":"seu_id","client_secret":"seu_secret","grant_type":"client_credentials"}'Resposta · 200 OK{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "token_type": "Bearer", "expires_in": 3600, "scope": "biometric:read biometric:write" } -
Enrolle um usuário (biometria palmar)
Envie a imagem da palma capturada pelo hardware para cadastro na base central. O campo palm_image deve ser Base64 de uma imagem PNG/JPG.
JavaScript · fetchconst enrollPalm = async (userId, palmImageBase64) => { const res = await fetch('https://api.treeal.id/v2/palmar/enroll', { method: 'POST', headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Institution-ID': 'seu_institution_id' }, body: JSON.stringify({ user_id: userId, palm_image: palmImageBase64, hand: 'right', // 'right' | 'left' | 'both' liveness_check: true }) }); return res.json(); }; -
Verifique / autentique o usuário
Compare uma nova captura da palma com o template cadastrado. Retorna um match_score e decisão binária.
JavaScript · fetchconst verifyPalm = async (userId, palmImageBase64) => { const res = await fetch(`https://api.treeal.id/v2/palmar/verify/${userId}`, { method: 'POST', headers: { 'Authorization': `Bearer ${accessToken}`, 'Content-Type': 'application/json', 'X-Institution-ID': 'seu_institution_id' }, body: JSON.stringify({ palm_image: palmImageBase64, hand: 'right' }) }); const data = await res.json(); // data.matched === true / false // data.match_score: 0.0 – 1.0 return data; }; -
Trate a resposta
Implemente o fluxo de sucesso e erro baseado em matched e match_score.
Exemplo · Resposta de verificação{ "request_id": "req_01JXYZ...", "user_id": "usr_abc123", "matched": true, "match_score": 0.9987, "liveness": { "is_live": true, "confidence": 0.9982 }, "latency_ms": 210, "timestamp": "2026-04-10T14:32:00Z" }Pronto! Com apenas 3 chamadas você tem um fluxo completo de enroll e verificação biométrica. Consulte a referência completa da API para todos os parâmetros.
Hub neutro e base centralizada.
Treeal ID como camada de orquestração entre tecnologia e instituições, garantindo privacidade, segurança e interoperabilidade.
Fluxo de dados
Visão completa da arquitetura de integração entre parceiros.
Segurança e compliance
Criptografia E2E
Dados biométricos trafegam cifrados com TLS 1.3 + mTLS. Templates armazenados com AES-256. Chaves gerenciadas em HSM.
LGPD & GDPR
Arquitetura em conformidade com a LGPD e GDPR. Consentimento explícito, direito ao esquecimento, auditoria de acesso completa.
PCI-DSS (Palm Pay)
Módulo de pagamento palmar em conformidade com PCI-DSS nível 1. Tokenização de dados de pagamento, sem armazenamento de PAN.
Alta Disponibilidade
Infraestrutura multi-region com SLA de 99.9%. Failover automático, balanceamento de carga e disaster recovery em < 15 min (RTO).
Autenticação
A API Treeal ID usa OAuth 2.0 com fluxo Client Credentials. Todos os endpoints exigem um token Bearer válido.
Gera um JWT de acesso com validade de 1 hora. Use-o no header Authorization: Bearer <token>.
Request Body| Campo | Tipo | Obrigat. | Descrição |
|---|---|---|---|
| client_id | string | ✓ Sim | ID do cliente fornecido pela Treeal ID |
| client_secret | string | ✓ Sim | Secret do cliente (manter seguro) |
| grant_type | string | ✓ Sim | Sempre client_credentials |
| scope | string | Opcional | Escopos separados por espaço. Ex: biometric:read biometric:write payment |
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "biometric:read biometric:write",
"institution_id": "inst_abc123"
}{
"error": "invalid_client",
"error_description": "Client authentication failed",
"request_id": "req_01JXYZ..."
}Invalida imediatamente um access token. Use em logout ou rotação de credenciais.
| Campo | Tipo | Obrigat. | Descrição |
|---|---|---|---|
| token | string | ✓ Sim | O access token a ser revogado |
Biometria Palmar API
Endpoints para enroll, verificação 1:1, identificação 1:N e gestão de templates palmares.
Extrai e armazena o template biométrico palmar de um usuário. Suporta mão direita, esquerda ou ambas. Requer liveness check configurável.
Headers obrigatórios| Header | Valor |
|---|---|
| Authorization | Bearer <access_token> |
| X-Institution-ID | ID da instituição |
| Content-Type | application/json |
| Campo | Tipo | Obrigat. | Descrição |
|---|---|---|---|
| user_id | string | ✓ Sim | ID único do usuário na sua instituição |
| palm_image | string | ✓ Sim | Imagem em Base64 (PNG/JPG). Mín. 300×300px |
| hand | enum | ✓ Sim | right | left | both |
| liveness_check | boolean | Opcional | Ativar prova de vivacidade. Default: true |
| metadata | object | Opcional | Dados adicionais (ex: device_id, branch_id) |
import requests, base64
with open('palm_right.jpg', 'rb') as f:
palm_b64 = base64.b64encode(f.read()).decode()
resp = requests.post(
'https://api.treeal.id/v2/palmar/enroll',
headers={
'Authorization': f'Bearer {access_token}',
'X-Institution-ID': 'inst_abc123'
},
json={
'user_id': 'usr_001',
'palm_image': palm_b64,
'hand': 'right',
'liveness_check': True
}
)
print(resp.json())
{
"request_id": "req_01JXYZ...",
"user_id": "usr_001",
"template_id": "tpl_palm_abc123",
"hand": "right",
"quality_score": 0.96,
"liveness": {
"is_live": true,
"confidence": 0.9991
},
"enrolled_at": "2026-04-10T14:00:00Z",
"status": "active"
}{
"error": "IMAGE_QUALITY_LOW",
"message": "Imagem com qualidade insuficiente. Score mínimo: 0.6",
"quality_score": 0.42,
"request_id": "req_01JXYZ..."
}{
"error": "USER_ALREADY_ENROLLED",
"message": "Usuário já possui template palmar. Use PATCH para atualizar.",
"template_id": "tpl_palm_abc123"
}Compara uma nova captura palmar com o template cadastrado do usuário. Retorna score de similaridade e decisão de match.
| Parâmetro | Tipo | Obrigat. | Descrição |
|---|---|---|---|
| user_id | path | ✓ Sim | ID do usuário a verificar |
| palm_image | string | ✓ Sim | Imagem Base64 da nova captura |
| hand | enum | ✓ Sim | right | left |
| threshold | number | Opcional | Limiar de match. Default: 0.92 (range: 0.5–0.99) |
Busca quem é o usuário em toda a base biométrica da instituição. Retorna até 10 candidatos ranqueados por score.
| Campo | Tipo | Obrigat. | Descrição |
|---|---|---|---|
| palm_image | string | ✓ Sim | Imagem Base64 da palma |
| hand | enum | ✓ Sim | right | left |
| max_results | integer | Opcional | Máx candidatos. Default: 5, máx: 10 |
| min_score | number | Opcional | Score mínimo para incluir no resultado. Default: 0.80 |
Remove permanentemente o template biométrico palmar do usuário. Ação irreversível — solicita confirmação via campo confirm: true.
Biometria Facial API
Reconhecimento facial 1:1 e 1:N com suporte a detecção de deepfake e liveness integrado.
| Campo | Tipo | Obrigat. | Descrição |
|---|---|---|---|
| user_id | string | ✓ Sim | ID único do usuário |
| face_image | string | ✓ Sim | Imagem facial em Base64. Rosto visível, frontal. |
| liveness_type | enum | Opcional | passive | active | none. Default: passive |
| deepfake_check | boolean | Opcional | Verificar se imagem é deepfake. Default: true |
Compara o rosto capturado com o template do usuário informado. Retorna match score e status de liveness/deepfake.
Busca facial em toda a base da instituição. Suporta bases de milhões de usuários com latência média de 400ms.
Compara dois rostos diretamente, sem necessidade de enroll prévio. Útil para onboarding com documento de identidade.
{
"image_a": "<base64 foto selfie>",
"image_b": "<base64 foto documento>",
"liveness_on_a": true
}
// Resposta
{
"same_person": true,
"match_score": 0.9872,
"liveness": { "is_live": true, "confidence": 0.997 }
}
Liveness Detection API
Prova de vivacidade passiva e ativa. Anti-spoofing de nível enterprise contra deepfakes gerados por IA.
Passive Liveness
Uma única foto/frame. Sem interação do usuário. Detecta apresentação de foto, máscara e replay. Latência < 200ms.
Active Liveness
Usuário realiza ações (piscar, sorrir, virar cabeça). Maior segurança contra ataques sofisticados e deepfakes em tempo real.
| Campo | Tipo | Obrigat. | Descrição |
|---|---|---|---|
| image | string | ✓ Sim | Imagem facial Base64 |
| deepfake_check | boolean | Opcional | Verificar deepfake por IA generativa. Default: true |
{
"is_live": true,
"confidence": 0.9984,
"attack_type": null,
"deepfake": {
"detected": false,
"confidence": 0.9991
},
"latency_ms": 148
}
Inicia uma sessão de liveness ativo. Retorna um session_id e a lista de ações que o usuário deve realizar, em ordem aleatória.
Envia os frames capturados durante a sessão ativa. Requer o session_id retornado por /active/init.
Palm Payment API
Pagamento biométrico pela palma da mão. Zero fricção, máxima segurança. Compatível com POS Positivo Palmar.
| Campo | Tipo | Obrigat. | Descrição |
|---|---|---|---|
| user_id | string | ✓ Sim | ID do usuário (já enrollado) |
| payment_token | string | ✓ Sim | Token do método de pagamento (gerado pelo banco/adquirente) |
| payment_type | enum | ✓ Sim | debit | credit | pix |
| bank_code | string | ✓ Sim | Código da instituição financeira (ISPB) |
Ponto principal do fluxo. Recebe a imagem da palma capturada no terminal, identifica o usuário, verifica liveness e autoriza o pagamento.
| Campo | Tipo | Obrigat. | Descrição |
|---|---|---|---|
| palm_image | string | ✓ Sim | Imagem Base64 capturada no terminal |
| amount | number | ✓ Sim | Valor em centavos. Ex: 5000 = R$ 50,00 |
| terminal_id | string | ✓ Sim | ID do terminal Positivo registrado |
| merchant_id | string | ✓ Sim | ID do estabelecimento comercial |
| payment_type | enum | Opcional | debit | credit | pix. Default: preferência do usuário |
{
"authorization_code": "AUTH_0xA3F2B...",
"user_id": "usr_001",
"status": "approved",
"amount": 5000,
"payment_type": "debit",
"match_score": 0.9971,
"liveness_passed": true,
"nsu": "202604101432001",
"latency_ms": 280
}
Retorna histórico paginado de transações biométricas do usuário. Suporta filtros de data e status.
SDKs & Bibliotecas
Bibliotecas oficiais para acelerar sua integração com a Treeal ID API.
Python SDK
pip install treeal-id
Node.js SDK
npm install @treeal/id-sdk
Java SDK
Maven · treeal:id-sdk
iOS SDK
Swift Package Manager
Android SDK
Gradle · treeal-id-android
REST (cURL)
Sem dependência, qualquer linguagem
Exemplo rápido — Node.js SDK
import { TreealID } from '@treeal/id-sdk';
const client = new TreealID({
clientId: process.env.TREEAL_CLIENT_ID,
clientSecret: process.env.TREEAL_CLIENT_SECRET,
institutionId: process.env.TREEAL_INSTITUTION_ID,
environment: 'sandbox' // 'production'
});
// Enroll palmar
const enrollment = await client.palmar.enroll({
userId: 'usr_001',
palmImage: palmBuffer, // Buffer ou Base64
hand: 'right'
});
// Verificar
const result = await client.palmar.verify('usr_001', {
palmImage: newCapture,
hand: 'right'
});
if (result.matched) {
console.log(`✅ Usuário autenticado! Score: ${result.matchScore}`);
}
Códigos de Erro
Referência completa de erros da API Treeal ID com descrições e sugestões de resolução.
| HTTP | Código de Erro | Descrição | Resolução |
|---|---|---|---|
| 400 | IMAGE_QUALITY_LOW | Imagem abaixo do score mínimo de qualidade | Solicitar nova captura. Score mínimo: 0.60 |
| 400 | INVALID_IMAGE_FORMAT | Formato de imagem não suportado | Usar PNG, JPG ou BMP. Verificar Base64 |
| 400 | LIVENESS_FAILED | Prova de vivacidade reprovada | Ataque detectado. Registrar tentativa. |
| 400 | DEEPFAKE_DETECTED | Imagem identificada como deepfake | Bloquear sessão e acionar equipe de segurança |
| 401 | TOKEN_EXPIRED | Access token expirado | Renovar token via /v2/auth/token |
| 401 | INVALID_TOKEN | Token inválido ou malformado | Verificar geração do token |
| 403 | SCOPE_INSUFFICIENT | Token sem escopo necessário | Solicitar escopo adicional no token |
| 403 | INSTITUTION_MISMATCH | Usuário pertence a outra instituição | Verificar X-Institution-ID |
| 404 | USER_NOT_ENROLLED | Usuário não possui template cadastrado | Realizar enroll antes de verificar |
| 409 | USER_ALREADY_ENROLLED | Usuário já possui template ativo | Usar PATCH /enroll/{id} para atualizar |
| 422 | NO_PALM_DETECTED | Palma não detectada na imagem | Verificar enquadramento e iluminação |
| 422 | NO_FACE_DETECTED | Rosto não detectado na imagem | Garantir rosto frontal e iluminado |
| 429 | RATE_LIMIT_EXCEEDED | Limite de requisições excedido | Implementar backoff exponencial |
| 500 | INTERNAL_ERROR | Erro interno no servidor | Contato: suporte@treeal.id |
Changelog
Histórico de versões e alterações da API Treeal ID.
-
v2.1.0Abr 2026
Palm Payment Beta + Liveness Ativo
- 🆕 Novo módulo Palm Payment com endpoints /v2/payment/*
- 🆕 Liveness ativo com sessões e ações aleatórias
- 🛡️ Detecção de deepfake por IA generativa aprimorada
- ⚡ Redução de latência do Palmar Verify em ~30%
- 📦 Lançamento do SDK Node.js e Python v2.1.0
-
v2.0.3Mar 2026
Melhorias de performance e segurança
- 🔒 Atualização TLS 1.3 obrigatório em todos os endpoints
- ⚡ Otimização do pipeline de extração de template palmar
- 🐛 Correção: FAR em condições de baixa iluminação
- 📖 Documentação de erros expandida
-
v2.0.0Jan 2026
Lançamento da API v2 — Integração Tencent Cloud LATAM
- 🚀 Novo motor biométrico palmar com FAR < 0.0001%
- 🆕 Endpoint /v2/facial/compare para onboarding com documento
- 🏗️ Arquitetura de hub neutro — base centralizada multi-instituição
- 🔑 OAuth 2.0 Client Credentials substituindo API Keys
- ⚠️ Breaking: v1 descontinuada — migrar até Jun/2026
-
v1.5Out 2025
Última versão da API v1 (legado)
- Biometria facial e liveness passivo
- API Keys para autenticação
- Descontinuação prevista: Jun/2026
Guia: Enroll de Usuário
Fluxo completo para cadastro biométrico com palmar + facial + liveness.
Capturar imagem no terminal
O terminal Positivo Palmar captura automaticamente a imagem com qualidade mínima garantida pelo hardware. Retorna Base64.
Verificar qualidade da imagem
Antes de enviar, verifique o quality_score retornado pelo SDK do terminal. Mínimo recomendado: 0.75.
Chamar POST /v2/palmar/enroll
Envie user_id, palm_image, hand e liveness_check: true. Guarde o template_id retornado.
(Opcional) Enroll facial
Para duplo fator, chame também POST /v2/facial/enroll com face_image do mesmo usuário.
Confirmar enroll e notificar usuário
Ao receber status: "active" na resposta, o usuário está pronto para usar serviços biométricos.
Guia: Verificação & Match
Fluxo de autenticação e identificação biométrica em produção.
Verify 1:1
O usuário se identifica (informa user_id) e a biometria confirma. Mais rápido e barato. Ideal para autenticação em apps e ATMs.
Search 1:N
Apenas a palma — o sistema encontra quem é. Sem necessidade de informar user_id. Ideal para pagamentos e controle de acesso.
// 1. Capturar palma no terminal
const capture = await terminal.capture();
// 2. Checar qualidade
if (capture.qualityScore < 0.6) throw Error('Imagem insuficiente');
// 3. Verificar (1:1) ou Buscar (1:N)
const result = userId
? await client.palmar.verify(userId, { palmImage: capture.base64 })
: await client.palmar.search({ palmImage: capture.base64 });
// 4. Decisão
if (result.matched && result.matchScore >= 0.92) {
grantAccess(result.userId);
} else {
denyAccess('Biometria não reconhecida');
}
Guia: Fluxo de Pagamento Palmar
Passo a passo da jornada completa do Palm Payment, do terminal ao banco.
Suporte & SLA
Canais de suporte técnico e acordos de nível de serviço da plataforma Treeal ID.
Suporte Técnico
Abertura de chamados para dúvidas e incidentes de integração. Disponível para todos os planos.
Portal de ChamadosSlack Privado
Canal dedicado no Slack para clientes enterprise. Acesso direto à equipe de engenharia da Treeal ID.
Solicitar AcessoStatus da Plataforma
Acompanhe a disponibilidade e incidentes em tempo real da API Treeal ID.
status.treeal.idSLA por plano
| Plano | Disponibilidade | Latência P95 | Suporte | RPM |
|---|---|---|---|---|
| Sandbox | 99% | — | Email (5 dias úteis) | 60 |
| Starter | 99.5% | < 500ms | Portal (2 dias úteis) | 600 |
| Business | 99.9% | < 350ms | Slack + Portal (8h) | 3.000 |
| Enterprise | 99.95% | < 300ms | Slack dedicado (2h) + TAM | Ilimitado |
Pronto para integrar a biometria do futuro?
Fale com nosso time comercial e de engenharia. Acesse o sandbox em menos de 24h após aprovação.
Time Comercial
Planos, precificação, contratos e parcerias estratégicas. Atendemos bancos, fintechs, governo e varejo.
comercial@treeal.idTime de Engenharia
Dúvidas técnicas, arquitetura de integração, POC e avaliação de casos de uso específicos.
engineering@treeal.idSandbox Gratuito
Ambiente de testes com dados simulados. Sem cartão de crédito. Solicite acesso em até 24h.
Solicitar SandboxTREEAL ID
Do lado de quem faz acontecer.
Parceiro América Latina · Tecnologia Tencent Cloud · Hardware Positivo Informática