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

1. Introdução

2. Autenticação

3. Endpoints

   • GET /
   • GET /v1/health
   • POST /v1/foto/converter
   • GET /v1/foto/capturar

4. Códigos de Erro

5. Estrutura Geral das Respostas

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

---