insoft-qface-win-api - Dev Doc

Gilberto Júnior

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
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/...).