7. Fortlink – Captura facial via link

Fortlink é um produto Payface que permite realizar captura facial remota através de um link único gerado no back-end (server-side).
Esse link pode ser enviado ao usuário final por SMS, e-mail, WhatsApp, etc., para que ele conclua o fluxo de selfie no próprio dispositivo.

Com um único produto, você consegue:

Garantir vivacidade do rosto (liveness)
Validar identidade (selfie + CPF)
Cadastrar uma face na base (enroll)
Identificar uma face já cadastrada (1:1)

Ambientes e URLs

⚠️ Todos os exemplos abaixo utilizam o ambiente Sandbox.

Base Sandbox
https://api-sandbox.fortface.ai
Base Produção
https://api.fortface.ai

Os endpoints do Fortlink seguem o mesmo caminho em ambos os ambientes, mudando apenas o host base:

Criar/consultar Fortlink
POST/GET {BASE_URL}/backoffice/v1/fortlink
Healthcheck (exemplo ilustrativo)
GET {BASE_URL}/healthcheck

Exemplos:

Criar Fortlink em Sandbox:
POST https://api-sandbox.fortface.ai/backoffice/v1/fortlink
Criar Fortlink em Produção:
POST https://api.fortface.ai/backoffice/v1/fortlink

Ações disponíveis (`action`)

Ao criar um Fortlink, você define qual operação será feita através do campo action:

Action	Descrição
`liveness`	Verifica se a selfie capturada é de uma pessoa viva (anti-spoofing).
`capture`	Captura selfie e valida a identidade da pessoa junto com o CPF.
`enroll`	Cadastra uma foto na base biométrica (galeria) para uso futuro.
`identify`	Faz validação 1:1 com a foto previamente cadastrada para aquele usuário.

Visão geral do fluxo

Seu back-end gera o link chamando o endpoint de criação de Fortlink, definindo:
- externalUserId (identificador do usuário, ex: CPF – neste exemplo: 12345678900)
- action (uma das ações acima)
- externalTransactionId (ID da transação no seu sistema – opcional, mas recomendado para rastreabilidade)
- expirationMinutes (tempo de expiração do link em minutos – deve ser um número inteiro maior que zero)
- webhook (URL para receber o resultado)
- redirectURL (URL HTTPS para retorno do usuário ao seu app após o fluxo — opcional)
Você envia o linkUrl para o usuário final (SMS, e-mail, WhatsApp, etc.).
O usuário acessa o link e conclui o fluxo de captura facial no Fortlink.
Você obtém o resultado de duas formas:
- Via webhook (recomendado – evento assíncrono)
- Via consulta (polling) ao endpoint de Get-Link.
Quando redirectURL estiver configurada, após a tela final o App Web redireciona o usuário para essa URL (timer de 5 segundos ou botão Continuar). O redirect é apenas navegação/UX — o resultado continua sendo entregue via webhook.

Autenticação

Todos os endpoints do Fortlink exigem:

Header x-api-key: {SUA_API_KEY}
Header accept: application/json
Header Content-Type: application/json (quando houver body)

Importante: nunca exponha sua x-api-key no front-end ou em aplicativos públicos.

Segurança e mTLS

Todas as requisições para a API do Fortlink são protegidas com mTLS (Mutual TLS).

É necessário utilizar um certificado cliente válido para conseguir se comunicar com os endpoints.
O certificado deve ser gerado na página:
https://mtls-tool.fortface.com/

Ambientes protegidos por mTLS:

Ambiente	Base URL
Sandbox	`https://api-sandbox.fortface.ai`
Produção	`https://api.fortface.ai`

Após gerar o certificado no mtls-tool, configure-o no seu gateway / HTTP client (ex.: NGINX, API Gateway, biblioteca HTTP) para que todas as chamadas para essas bases (Sandbox e Produção) sejam feitas com mTLS.

Quando o cliente HTTPS suportar, prefira cert + key em vez de PFX. Para extrair o certificado do PFX: openssl pkcs12 -in arquivo.pfx -clcerts -nokeys -out certificado.crt -passin pass:SENHA. Use o .crt e o .key nas opções do cliente; em alguns ambientes o uso direto de PFX gera erro (ex.: "Unsupported PKCS12 PFX data").

Endpoints

Atualmente, o Fortlink expõe 3 endpoints principais:

Criar link (POST /backoffice/v1/fortlink)
Consultar link (GET /backoffice/v1/fortlink/{id})
Healthcheck (GET /healthcheck)

Além disso, você configura um Webhook para receber o resultado das operações.

1. Criar Fortlink (Sandbox)

Endpoint (Sandbox)

POST https://api-sandbox.fortface.ai/backoffice/v1/fortlink

Para Produção, use:
POST https://api.fortface.ai/backoffice/v1/fortlink

Headers

accept: application/json
x-api-key: {SUA_API_KEY}
Content-Type: application/json

Body (exemplo – action identify)

{
  "externalUserId": "12345678900",
  "action": "identify",
  "expirationMinutes": 1440,
  "webhook": "https://webhook-test.com/example",
  "redirectURL": "https://cliente.com/retorno",
  "externalTransactionId": "example-1234"
}

Parâmetros do Body

Campo	Tipo	Obrigatório	Descrição
`externalUserId`	string	✅ Sim	Identificador único do usuário no seu sistema (ex: CPF)
`action`	string	✅ Sim	Ação a ser executada: `liveness`, `capture`, `enroll` ou `identify`
`externalTransactionId`	string	⚠️ Opcional	ID da transação no seu sistema para rastreabilidade. Recomendado para garantir correlação com o sistema cliente
`expirationMinutes`	integer	⚠️ Opcional	Tempo de validade do link em minutos. Deve ser um número inteiro maior que zero. Se omitido, usa o padrão da galeria
`webhook`	string	⚠️ Opcional	URL para receber notificações assíncronas do resultado
`redirectURL`	string	⚠️ Opcional	URL HTTPS para redirecionar o usuário final ao seu app após a tela de resultado no Fortlink. Não envia dados do processamento na URL
`document`	string	⚠️ Condicional	CPF do usuário. OBRIGATÓRIO quando `action: "capture"`. Opcional para outras actions. Deve ser um CPF válido (formato e dígitos verificadores)

⚠️ Validações importantes:

Parâmetros gerais:

expirationMinutes deve ser um número inteiro (não aceita decimais como 10.5)

expirationMinutes deve ser maior que zero (valores como 0 ou negativos retornam erro 400)

Não são permitidas conversões implícitas de tipo (strings como "1440" retornam erro 400)

Campo document (CPF):

OBRIGATÓRIO quando action = "capture" (retorna erro 400 se ausente)

Opcional para outras actions (identify, enroll, liveness)

É validado localmente antes de qualquer integração externa

CPF inválido (formato incorreto ou dígitos verificadores errados) retorna erro 422

A validação de CPF inclui: formato (11 dígitos), dígitos não repetidos e verificação dos dígitos verificadores

Campo redirectURL:

Opcional — links sem este campo mantêm o comportamento atual

Deve ser uma URL válida com protocolo HTTPS (HTTP ou URLs malformadas retornam erro 400)

Usada apenas para navegação do usuário no browser; o resultado do processamento continua sendo entregue via webhook

A URL é chamada exatamente como cadastrada, sem query strings ou parâmetros adicionais com dados do Fortlink

Exemplo em cURL (Sandbox)

curl --location 'https://api-sandbox.fortface.ai/backoffice/v1/fortlink' \
  --cert /caminho/para/seu-certificado.pem \
  --key /caminho/para/sua-chave.key \
  --header 'accept: application/json' \
  --header 'x-api-key: {SUA_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '{
    "externalUserId": "12345678900",
    "action": "identify",
    "expirationMinutes": 1440,
    "webhook": "https://webhook-test.com/example",
    "redirectURL": "https://cliente.com/retorno",
    "externalTransactionId": "example-1234"
  }'

Resposta (exemplo)

{
  "id": "019ae9ba-7cd4-73dd-bf39-649c0350c06b",
  "linkUrl": "https://api-sandbox.fortface.ai/fortlink/019ae9ba-7cd4-73dd-bf39-649c0350c06b",
  "externalUserId": "12345678900",
  "action": "identify",
  "status": "pending",
  "expirationMinutes": 1440,
  "webhook": "https://webhook-test.com/example",
  "redirectURL": "https://cliente.com/retorno",
  "galleryId": "UUID",
  "accountName": "test_gallery",
  "createdAt": "2025-12-04T14:18:24.340Z",
  "expiresAt": "2025-12-05T14:18:24.340Z",
  "externalTransactionId": "example-1234"
}

2. Consultar Fortlink (Get-Link / Polling)

Use este endpoint para consultar o status de um Fortlink e acessar o output da operação.

Endpoint (Sandbox)

GET https://api-sandbox.fortface.ai/backoffice/v1/fortlink/\{id\}

Para Produção, use:
GET https://api.fortface.ai/backoffice/v1/fortlink/\{id\}

Substitua {id} pelo id retornado na criação do link.

Headers

accept: application/json
x-api-key: {SUA_API_KEY}
Content-Type: application/json

Exemplo em cURL (Sandbox)

curl --location 'https://api-sandbox.fortface.ai/backoffice/v1/fortlink/019ae9bd-9845-7126-85ee-d49cfcc1f769' \
  --cert /caminho/para/seu-certificado.pem \
  --key /caminho/para/sua-chave.key \
  --header 'accept: application/json' \
  --header 'x-api-key: {SUA_API_KEY}' \
  --header 'Content-Type: application/json'

Resposta (exemplo – action enroll aprovada)

{
  "id": "019ae9bd-9845-7126-85ee-d49cfcc1f769",
  "externalUserId": "12345678900",
  "action": "enroll",
  "expirationAt": "2025-12-05T14:21:47.973Z",
  "webhook": "https://webhook-test.com/example",
  "redirectURL": "https://cliente.com/retorno",
  "externalTransactionId": "example-1234",
  "galleryId": "UUID",
  "accountName": "test_gallery",
  "status": "approved",
  "linkUrl": "https://api-sandbox.fortface.ai/fortlink/019ae9bd-9845-7126-85ee-d49cfcc1f769",
  "output": {
    "photo": {
      "liveness": {
        "value": true,
        "confidence": 100
      },
      "eyesOpen": {
        "left": {
          "value": true,
          "confidence": 64.7906925257821
        },
        "right": {
          "value": true,
          "confidence": 67.04287669451382
        }
      }
    },
    "sdk": {
      "platform": "web",
      "appId": "fortlink-sandbox",
      "model": "not identified",
      "sdkVersion": "2.4.0",
      "soVersion": "18.7",
      "so": "iOS",
      "browser": "Safari",
      "browserVersion": "26.1",
      "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.1 Mobile/15E148 Safari/604.1",
      "requestSdkConfig": "true"
    },
    "imageData": "",
    "hash": "75FR5OJA8IogI1z23Ia4hHgmEszTrWprRoFxwI78/KFTrszGJWvKkeLoFz4/gnzwAL14IpXkc7yzUKL+RS29eg==",
    "api": {
      "env": "sandbox",
      "timestamp": 1764858237498,
      "version": "v1 - 2.56.1"
    }
  },
  "sessionId": "f74b1c97-bf92-469c-a418-1f192f4da44b",
  "sessionIds": [
    "e5a8b3dd-365a-44c2-b11d-5a3cdc89a3da",
    "f74b1c97-bf92-469c-a418-1f192f4da44b"
  ],
  "createdAt": "2025-12-04T14:21:47.973Z"
}

3. Healthcheck

Endpoint para verificar rapidamente o status do ambiente Fortlink.

Endpoint (Sandbox – exemplo)

GET https://api-sandbox.fortface.ai/healthcheck

Endpoint (Produção – exemplo)

GET https://api.fortface.ai/healthcheck

Exemplo em cURL (Sandbox)

curl --location 'https://api-sandbox.fortface.ai/healthcheck' \
  --cert /caminho/para/seu-certificado.pem \
  --key /caminho/para/sua-chave.key \
  --header 'accept: application/json' \
  --header 'x-api-key: {SUA_API_KEY}' \
  --header 'Content-Type: application/json'

Webhook

O Webhook é o mecanismo preferencial para receber o resultado da captura facial.
Quando o usuário conclui o fluxo, o Fortlink envia um POST para a URL configurada no campo webhook da criação do link.

Quando redirectURL foi informada na criação do link, o objeto fortlink no payload do webhook também inclui esse campo. Isso permite correlacionar o evento com a URL de retorno do usuário; não substitui o webhook como canal de entrega do resultado.

Exemplo de payload (Sandbox)

{
  "sentAt": "2025-12-04T14:23:58.131Z",
  "event": {
    "id": "019ae9bf-941d-70e3-9533-9fc95c907226",
    "type": "link_approved",
    "createdAt": "2025-12-04T14:23:57.981Z"
  },
  "fortlink": {
    "id": "019ae9bd-9845-7126-85ee-d49cfcc1f769",
    "linkUrl": "https://api-sandbox.fortface.ai/fortlink/019ae9bd-9845-7126-85ee-d49cfcc1f769",
    "externalUserId": "12345678900",
    "action": "enroll",
    "status": "approved",
    "expirationAt": "2025-12-05T14:21:47.973Z",
    "webhook": "https://webhook-test.com/example",
    "redirectURL": "https://cliente.com/retorno",
    "galleryId": "UUID",
    "accountName": "test_gallery",
    "createdAt": "2025-12-04T14:21:47.973Z",
    "externalTransactionId": "example-1234",
    "sessionId": "f74b1c97-bf92-469c-a418-1f192f4da44b",
    "output": {
      "photo": {
        "liveness": {
          "value": true,
          "confidence": 100
        },
        "eyesOpen": {
          "left": {
            "value": true,
            "confidence": 64.7906925257821
          },
          "right": {
            "value": true,
            "confidence": 67.04287669451382
          }
        }
      },
      "sdk": {
        "platform": "web",
        "appId": "fortlink-sandbox",
        "model": "not identified",
        "sdkVersion": "2.4.0",
        "soVersion": "18.7",
        "so": "iOS",
        "browser": "Safari",
        "browserVersion": "26.1",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.1 Mobile/15E148 Safari/604.1",
        "requestSdkConfig": "true"
      },
      "imageData": "",
      "hash": "75FR5OJA8IogI1z23Ia4hHgmEszTrWprRoFxwI78/KFTrszGJWvKkeLoFz4/gnzwAL14IpXkc7yzUKL+RS29eg==",
      "api": {
        "env": "sandbox",
        "timestamp": 1764858237498,
        "version": "v1 - 2.56.1"
      }
    }
  }
}

Redirect do usuário final (`redirectURL`)

Quando redirectURL é informada na criação do link:

O usuário conclui o fluxo e visualiza a tela final do Fortlink (sucesso, falha, rejeição, etc.).
Após exibir a tela final, o App Web inicia um timer de 5 segundos e redireciona automaticamente para redirectURL.
O usuário pode clicar em Continuar para retornar imediatamente, sem aguardar o timer.
A URL é aberta exatamente como cadastrada — sem status, scores, tokens ou outros dados do processamento na URL.
Se o usuário fechar o navegador antes do redirect, o webhook ainda é enviado normalmente.

Links criados sem redirectURL mantêm o comportamento atual (sem redirect automático).

Status possíveis do Fortlink / Webhook

Os status do Fortlink seguem a seguinte lógica de negócio:

PENDING      = "pending"
EXPIRED      = "expired"
APPROVED     = "approved"
REJECTED     = "rejected"
INCONCLUSIVE = "inconclusive"

Definição de cada status

PENDING

"pending"

Nenhum dos outros status foi atingido ainda. O usuário ainda não completou a tarefa ou o resultado ainda está em processamento.

EXPIRED

"expired"

Passou o tempo determinado para validade do link (expirationMinutes / expirationAt). O usuário não pode mais utilizar aquele Fortlink.

APPROVED

"approved"

Captura aprovada (Hubface capture 4 ou 5) e/ou liveness aprovado nas actions enroll, identify e liveness.

REJECTED

"rejected"

Liveness reprovado mais de 5 vezes (value = false) nas actions enroll, identify e liveness ou capture com status 1 ou 2 (Hubface).

INCONCLUSIVE

"inconclusive"

Resultado inconclusivo de captura: capture com status 0 ou 3 (Hubface).

Em resumo:

APPROVED → sucesso claro conforme regras de captura / liveness.

REJECTED → falha clara (múltiplas reprovações de liveness ou capture 1/2).

INCONCLUSIVE → captura não permite afirmar nem aprovar nem rejeitar com segurança (Hubface 0/3).

PENDING / EXPIRED → estados de fluxo (ainda em andamento ou vencido).

Resumo

O Fortlink simplifica a integração de captura facial remota:

Você gera um link no server-side (usando o endpoint /backoffice/v1/fortlink).
O usuário faz a selfie no fluxo web.
Você recebe o resultado completo via Webhook ou consulta por ID.
Toda a comunicação com a API é protegida por mTLS, com certificados gerados em: https://mtls-tool.fortface.com/.

Exemplos de valores usados neste documento:

externalUserId: "12345678900"
galleryId: "UUID"
webhook: "https://webhook-test.com/example"
redirectURL: "https://cliente.com/retorno" (opcional)
externalTransactionId: "example-1234"

Ambientes:

Sandbox (BASE): https://api-sandbox.fortface.ai
Produção (BASE): https://api.fortface.ai

Caminho principal (em ambos):

POST/GET {BASE_URL}/backoffice/v1/fortlink

Integre os 3 pontos principais:

POST /backoffice/v1/fortlink – criação do link
GET /backoffice/v1/fortlink/{id} – consulta (polling)
Webhook – recebimento assíncrono dos resultados

E use as actions (liveness, capture, enroll, identify) de acordo com o objetivo do seu fluxo de negócio.

Ambientes e URLs​

Ações disponíveis (action)​

Visão geral do fluxo​

Autenticação​

Segurança e mTLS​

Endpoints​

1. Criar Fortlink (Sandbox)​

2. Consultar Fortlink (Get-Link / Polling)​

3. Healthcheck​

Webhook​

Redirect do usuário final (redirectURL)​

Status possíveis do Fortlink / Webhook​

Definição de cada status​

Resumo​

Ambientes e URLs

Ações disponíveis (`action`)

Visão geral do fluxo

Autenticação

Segurança e mTLS

Endpoints

1. Criar Fortlink (Sandbox)

2. Consultar Fortlink (Get-Link / Polling)

3. Healthcheck

Webhook

Redirect do usuário final (`redirectURL`)

Status possíveis do Fortlink / Webhook

Definição de cada status

Resumo