QFace API – Documentação Oficial
API REST simples e local para integração com serviços Windows da aplicação QFace.
Versão atual: 1.0.0
Última atualização: 2025-12-02
📑 Sumário
Introdução
Autenticação
Endpoints
GET /
GET /v1/health
POST /v1/foto/converter
GET /v1/foto/capturar
Códigos de Erro
Estrutura Geral das Respostas
Considerações
Introdução
A QFace API é uma API REST minimalista executada localmente no Windows para:
Verificação de status do serviço
Conversão de imagens faciais para template biométrico
Captura da face via dispositivo DFace Box - Digicon
A API é projetada para uso local por outros serviços internos.
Autenticação
❗ Não há autenticação.
A API é destinada exclusivamente ao ambiente local (localhost).
Endpoints
GET /
Descrição
Retorna informações básicas sobre o status atual da API.
Exemplo de Requisição
GET /
Exemplo de Resposta
{
"status": "ok",
"message": "Servidor QFace API rodando",
"timestamp": "2025-12-02T16:39:58.332Z",
"version": "1.0.0",
"instanceId": "33731a12-c30a-41db-bcdf-9c4553f11567",
"pid": 22912
}
GET /v1/health
Descrição
Endpoint de health check para verificação de integridade do serviço.
Exemplo de Requisição
GET /v1/health
Exemplo de Resposta
{
"status": "ok",
"name": "insoft-qface-win-api",
"version": "1.0.0",
"timestamp": "2025-12-02T16:39:27.083Z",
"instanceId": "33731a12-c30a-41db-bcdf-9c4553f11567",
"pid": 22912
}
POST /v1/foto/converter
Descrição
Converte imagens base64 de rosto humano em templates biométricos.
Payload (JSON)
{
"pictures": [
{
"personId": 41359,
"image": "iVBORw0KGgoAAAANSUh..."
},
{
"personId": 41359,
"image": "iVBORw0KGgoAAAANSUh..."
},
{
"personId": 41359,
"image": "iVBORw0KGgoAAAANSUh..."
}
]
}
Resposta (Erros parciais)
{
"success": true,
"pictures": [
{
"personId": 41359,
"template": null,
"error": "invalidImage",
"message": "A imagem é inválida e/ou não é de um rosto humano"
},
{
"personId": 255688,
"template": "737E796D77749E8D8C80869B7273...",
"error": null,
"message": null
},
{
"personId": 254809,
"template": null,
"error": "invalidImage",
"message": "A imagem é inválida e/ou não é de um rosto humano"
}
]
}
GET /v1/foto/capturar
Descrição
Inicia um processo de captura de rosto através do dispositivo DFace Box - Digicon (USB).
Resposta – Sucesso
{
"success": true,
"template": "6489847F7A738A8F846F849070808A7479...",
"quality": 87
}
template → modelo biométrico extraído
quality → qualidade da imagem / detecção
Resposta – Erro / Cancelamento
{
"success": false,
"message": "O processo de captura da face foi cancelado pelo usuário"
}
Códigos de Erro
Código
Descrição
invalidImage
Imagem inválida ou sem rosto detectável
cancelled
Usuário cancelou a captura
internalError
Erro interno inesperado
Estrutura Geral das Respostas
Sucesso
{
"success": true,
"data": {}
}
Erro
{
"success": false,
"message": "Descrição do erro"
}
Considerações
A API é destinada ao ambiente Windows com execução via serviços locais.
O template facial retornado é um
hexadecimal biométrico próprio do DFace Box - Digicon.
Imagens devem ser enviadas em base64
sem prefixo MIME (data:image/...).