Guia de Integração

Guia de Integração
MyPass v1.0

Autenticação biométrica 3D determinística. Integração documentada. Conformidade LGPD garantida.

Pular para seção:

Introdução

A MyPass API fornece verificação biométrica facial 3D para suas aplicações. Através dela, você pode confirmar a identidade de usuários com alta precisão e segurança.

Cadastro Facial

Registra o rosto de um usuário para futuras comparações.

Verificação

Compara o rosto capturado com um cadastro existente.

Prova de Vida

Confirma que a captura é de uma pessoa real, sem comparar com cadastro.

Obter sua API Key

O desenvolvedor acessa o formulário de cadastro em mypass.com.br

Preenche os dados da empresa, incluindo CNPJ

A solicitação passa por processo de aprovação

Após aprovação, um token mpx_ é gerado e enviado ao desenvolvedor

Este token é a API Key utilizada em todas as chamadas autenticadas

A API Key não pode ser recuperada depois. Se perder, será necessário solicitar uma nova via painel administrativo.

Baixar o SDK

O FaceTec SDK roda no dispositivo do usuário e captura os dados biométricos (face scan, imagens de auditoria).

Browser SDK (Web)Android SDKiOS SDK

dev.facetec.com/downloads

O Papel do SDK

O SDK é responsável por guiar o usuário na captura facial e gerar os dados (faceScan, auditTrailImage, etc) que serão enviados para a API.

Inicializar o SDK

GET/api/facetec/config

Resposta do Servidor

{
  "deviceKeyIdentifier": "abc123...",
  "publicFaceMapEncryptionKey": "-----BEGIN PUBLIC KEY-----\n..."
}

Exemplo Browser SDK

// Buscar configuração do servidor
const resp = await fetch('/api/facetec/config');
const config = await resp.json();

// Inicializar o SDK
FaceTecSDK.initializeInProductionMode(
  config.productionKeyText,
  config.deviceKeyIdentifier,
  config.publicFaceMapEncryptionKey,
  function(success) {
    if (success) { console.log('SDK inicializado com sucesso'); }
  }
);

Cadastro Facial (Enrollment)

POST/api/enrollment

Registra o rosto de um usuário para futuras verificações.

Headers

Header	Valor
Content-Type	application/json
X-API-Key	sua-chave-api

Body (JSON)

Campo	Tipo	Descrição
externalId	string	ID do usuário no seu sistema (CPF, UUID)
sessionId	string	ID da sessão do FaceTec SDK
faceScan	string	Dados do face scan (gerado pelo SDK)
auditTrailImage	string	Imagem de auditoria (base64)
lowQualityAuditTrailImage	string	Imagem de auditoria low-res

POST /api/enrollment
Content-Type: application/json
X-API-Key: sua-chave-api
{
  "externalId": "12345678900",
  "sessionId": "session-uuid-aqui",
  "faceScan": "dados-do-sdk...",
  "auditTrailImage": "base64...",
  "lowQualityAuditTrailImage": "base64..."
}

O externalId é o identificador único do usuário no seu ecossistema. Use-o para vincular o cadastro facial de forma definitiva à sua base de dados.

Verificação (Verify)

POST/api/verify

Compara o rosto capturado com o cadastro existente do usuário.

{
  "success": true,
  "match": true,
  "matchLevel": 8,
  "isLive": true
}

Campo	Descrição
match	true se o rosto corresponde ao cadastro
matchLevel	Nível de correspondência de 0 a 10 (mínimo recomendado: 6)
isLive	true se a prova de vida foi aprovada

Prova de Vida (Liveness)

POST/api/liveness

Apenas confirma que a captura é de uma pessoa física real.

{
  "success": true,
  "isLive": true,
  "confidence": 99.7
}

Não é necessário enviar externalId para liveness. Apenas os dados biométricos da sessão atual.

Consultar / Excluir Usuário

Consultar

GET/api/users/{externalId}

GET /api/users/12345678900
X-API-Key: sua-chave-api

Excluir (LGPD)

DELETE/api/users/{externalId}

Remove permanentemente os dados biométricos. Resposta de conformidade com o Direito ao Esquecimento.

DELETE /api/users/12345678900
X-API-Key: sua-chave-api

Autenticação

Nível 1 — Sandbox Token (Acesso ao Portal)

Para acessar o portal de desenvolvedores e a documentação interativa, utilize o sb_token fornecido durante o cadastro.
Este token é exclusivo para autenticação no portal, NÃO deve ser usado em chamadas à API de produção.

Nível 2 — Chamadas de API (X-API-Key)

Todas as chamadas operacionais à API precisam de autenticação via API Key (mpx_).

Via Header

X-API-Key: sua-mpx-key

Via Query

?key=sua-mpx-key

O query parameter é necessário para o Browser SDK, que não permite configurar headers customizados no XHR interno.

Os recursos habilitados dependem da configuração do seu contrato. O sistema retornará 403 Forbidden para módulos não ativos.

Códigos de Erro

Status	Erro	Descrição
400	Bad Request	Campos ausentes ou dados inválidos
401	Unauthorized	API Key ausente ou expirada
403	Forbidden	Recurso não permitido no contrato
404	Not Found	Usuário (externalId) não localizado
409	Conflict	Usuário já cadastrado no Enrollment
500	Internal Error	Falha crítica no processamento biométrico

{
  "success": false,
  "error": "Descrição detalhada do erro"
}

Fluxo via SDK

Encapsulamento total da comunicação biométrica via proxy processor.

O SDK captura os dados biométricos e gera o requestBlob criptografado.

Você envia o blob para /api/facetec/process.

O servidor processa a requisição com o motor central e devolve um responseBlob.

Você repassa o responseBlob ao SDK, que finaliza a operação de interface.

// Configurar o SDK com o endpoint MyPass
// Configure esta variável em seu .env.local para apontar ao servidor correto
FaceTecSDK.setServerBaseURL(process.env.NEXT_PUBLIC_MYPASS_API_URL || 'https://facetec.easypay.com.br/api/facetec');

// O SDK gerencia os POSTs e payloads criptografados

Neste fluxo, o SDK gerencia toda a complexidade criptográfica. O desenvolvedor apenas trata o callback final.

Base URL

Endereço operacional de produção para todas as chamadas:

https://facetec.easypay.com.br

Recomendação

Boas práticas: em ambientes de desenvolvimento, recomendamos configurar esta URL via variável de ambienteNEXT_PUBLIC_MYPASS_API_URLpara evitar exposição no código-fonte e facilitar a troca entre ambientes.

POST https://facetec.easypay.com.br/api/enrollment
Content-Type: application/json
X-API-Key: sua-chave-api
{
  "externalId": "12345678900",
  ...
}

Guia de Integração MyPass v1.0