API REST · v1

Documentação da API

Integre verificação facial em qualquer produto — evento, ponto, acesso, varejo. O ModFACE identifica pelo rosto e devolve o resultado; a regra de negócio é sua. Tudo via REST, autenticado por API key.

Base URL https://modface.gmscorporation.com.br/api

Introdução

O fluxo tem dois momentos: cadastro (enrollment) do rosto na inscrição, e reconhecimento na hora da verificação. Cada tenant tem uma galeria isolada, identificada pela API key — não há comparação cruzada entre tenants.

1. Cadastro

POST /faces com a captura + external_id + consentimento.

2. Reconhecimento

POST /recognize confirma liveness e compara 1:N.

3. Resultado

Retorna confirmado + external_id + score. Você decide o resto.

Autenticação

Toda requisição envia a API key da galeria no header. Aceitamos Authorization: Bearer ou X-Api-Key. A key é exibida uma única vez no painel — guarde-a com segurança; no servidor guardamos só o hash.

Header de autenticação

Authorization: Bearer mf_sua_api_key_aqui
Content-Type: application/json

Endpoints

Método	Caminho	Descrição
POST	/faces	Cadastra (enrollment) o rosto de um participante na galeria do tenant.
POST	/recognize	Reconhece 1:N contra a galeria e confirma liveness.
DELETE	/faces/{external_id}	Exclui o participante e sua biometria (LGPD).
GET	/events/{event}/usage	Consumo faturável do evento (metering).
GET	/events/{event}/attendance	Lista as verificações/presenças do evento.

POST

/faces

Cadastra o rosto de um participante. Envie a imagem (multipart/base64) ou o embedding já extraído no navegador. O external_id é seu identificador — o ModFACE nunca guarda nome/CPF.

Requisição

curl -X POST https://modface.gmscorporation.com.br/api/faces \
  -H "Authorization: Bearer mf_sua_api_key_aqui" \
  -F "external_id=cliente-8f3a" \
  -F "consentimento=1" \
  -F "imagem=@rosto.jpg"

Resposta 201

{
  "participante": {
    "id": 42,
    "external_id": "cliente-8f3a",
    "nome": null,
    "consentimento_em": "2026-09-05T12:00:00-03:00"
  },
  "embedding": [0.021, -0.114, 0.087, "..."],
  "modelo_versao": "stub-v1",
  "quality_score": 0.94
}

POST

/recognize

Reconhece 1:N. Confirma o liveness da captura e compara contra a galeria enviada. Retorna match, score e o external_id. Só há match com score ≥ limiar e liveness aprovado.

Resposta 200

{
  "match": true,
  "liveness_ok": true,
  "score": 0.9812,
  "limiar": 0.96,
  "faturavel": true,
  "participante": { "external_id": "cliente-8f3a", "nome": null }
}

Erros

Respostas seguem o padrão HTTP. O corpo traz sempre um campo message.

Código	Significado
401	API key ausente ou inválida.
403	A API key não pertence a este evento/tenant.
404	Recurso não encontrado (ex.: external_id inexistente).
422	Dados inválidos (sem rosto na imagem, imagem vazia, campo faltando).
429	Rate limit excedido (120 req/min por key).

Limites & billing

Rate limit de 120 requisições por minuto por API key.
R$ 0,35 por reconhecimento com match. No-match e falha de liveness não faturam.
Dedup: a mesma pessoa reconhecida 2x em 10 min não cobra em dobro.
Enrollment (cadastro) não tem custo por face.

Comece a integrar

Crie sua conta, gere a API key e faça a primeira chamada em minutos.

Gerar API key