> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.api.corpx.com/_mcp/server.

# Captura facial (link e SDK FaceTec)

A captura facial aparece em dois produtos. Nos dois, a pessoa mostra o rosto ao vivo; a diferença é **quem abre a câmera**.

| Produto                                                                                            | Quando usar                             | Captura por **link**                             | Captura pelo **SDK** no seu app                              |
| -------------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
| [Abertura de conta](/baas/guias/abertura-de-contas/visao-geral) com biometria centralizada         | Onboarding PF/PJ, desligada por padrão  | `persons[].biometryLink` abre a página hospedada | `POST /v1/accreditations/{id}/capture` e o app relê os blobs |
| [Verificação de identidade](/baas/guias/autenticacao/verificacao-de-identidade) (API paga à parte) | Provar o CPF antes de uma ação sensível | `method: link` devolve `verificationLink`        | `method: facetec_sdk` e o app chama `/facetec/process`       |

Este guia cobre as duas formas na **abertura**. A verificação de identidade usa o mesmo SDK FaceTec v10, com rotas e cotas próprias — o pedido do pacote (bundle id, domínio) é o mesmo.

O app **não fala com a FaceTec nem com a Dracma**. Quem fala é a API CorpX. Embutir o SDK sem o pacote emitido para o seu aplicativo falha no `initialize` (`RejectedByServer`): o identificador do binário não está na allowlist.

> **Não baixe o SDK por conta**
>
> O FaceTec é licenciado pelo provedor de biometria do tenant. Um zip baixado na conta de desenvolvedor da FaceTec **não** autentica as sessões da CorpX. Peça o pacote ao suporte, com os identificadores abaixo; a CorpX devolve o zip e cadastra a chave.

## Pedir o SDK

Escreva para [suporte@corpx.com](mailto:suporte@corpx.com) **antes** de embutir a câmera. Um pacote vale para **um** aplicativo. Trocar o bundle id, o application id ou o domínio depois de emitido exige outro pedido.

Informe, para cada app (produção e, se houver, homologação):

| Campo             | Obrigatório em                                           | Exemplo                                                                                                     |
| ----------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Tenant            | todos                                                    | `tenant-suaempresa`                                                                                         |
| Produto           | todos                                                    | abertura (`accreditation_central_kyc`) e/ou verificação de identidade (`identity_verification_facetec_sdk`) |
| Application Name  | todos                                                    | nome que a FaceTec usa no pacote, ex. `Banco X iOS`                                                         |
| Plataforma        | todos                                                    | `browser`, `ios`, `android`, `react_native`, `flutter` ou `cordova`                                         |
| Bundle Identifier | iOS e quem empacota iOS (React Native, Flutter, Cordova) | `br.com.banco.app` (`CFBundleIdentifier`)                                                                   |
| Application ID    | Android e quem empacota Android                          | `br.com.banco.app` (`applicationId` do Gradle)                                                              |
| Domínios          | Browser SDK e WebView                                    | `app.banco.com`, `onboarding.banco.com` — hosts de produção, sem path                                       |
| Ambiente          | todos                                                    | produção e/ou desenvolvimento                                                                               |

Um app React Native, Flutter ou Cordova envia **os dois** identificadores nativos (iOS **e** Android), porque o binário que a loja instala é o nativo. Um PWA ou página própria envia só os domínios.

A CorpX:

1. pede o pacote FaceTec **v10** amarrado a esses identificadores;
2. entrega o zip (não redistribua; a licença é do aplicativo);
3. na verificação de identidade, cadastra o `deviceKeyIdentifier` no tenant;
4. na abertura, a chave da sessão vem de `POST .../capture/{token}/start` (`sdk.key`) — o zip ainda precisa ser o da mesma versão.

O `deviceKeyIdentifier` **não é segredo**: vai embutido no app e sai no `201` da verificação de identidade. O que não pode vazar é o zip, nem um bundle id diferente do pedido.

Sem esse cadastro, `method: facetec_sdk` responde `403 facetec_sdk_not_enabled`. A página hospedada da abertura **não** precisa do zip no seu repositório: ela carrega o Browser SDK nos assets da CorpX.

## Plataformas e idiomas

O que a FaceTec publica e o que este fluxo aceita:

| Pacote                         | Linguagem do app       | Onde a CorpX usa                                                 |
| ------------------------------ | ---------------------- | ---------------------------------------------------------------- |
| Browser SDK v10                | JavaScript             | Página hospedada da abertura; PWA / site próprio                 |
| iOS SDK v10                    | Swift ou Objective-C   | App nativo iOS 12+                                               |
| Android SDK v10                | Kotlin ou Java         | App nativo Android 5+                                            |
| React Native, Flutter, Cordova | a linguagem do wrapper | o wrapper chama o SDK iOS/Android; peça o zip desses sample apps |

Não há pacote C#, Python ou Go para a câmera. O backend só relê `requestBlob` / `responseBlob`.

A interface do SDK aceita **mais de 30 idiomas** (localização da FaceTec). A página hospedada da CorpX carrega `FaceTecStrings.pt-br.js` e fala português brasileiro com o titular. No app próprio, use o `FaceTecStrings.{locale}.js` que veio no zip e `FaceTecSDK.configureLocalization`. Pedido novo de pacote não troca o idioma: isso é arquivo de strings, não chave.

A versão tem de ser **v10**. O protocolo antigo (v9: `faceScan` / `scanResultBlob`, PEM, `productionKeyText`) não funciona nestas rotas. Na abertura, `sdk.version` do `/start` é a versão dos assets (hoje a linha 10.1.x); use exatamente esse zip.

> **HTTPS e câmera**
>
> No Browser SDK a câmera só abre em `https` (ou `localhost` no zip de desenvolvimento). HTTP remoto falha com `GetUserMediaRemoteHTTPNotSupported`. WebView precisa da permissão de câmera da plataforma nativa, não só da página.

## Abertura: captura pelo link

Use quando você **não** controla o dispositivo — WhatsApp, e-mail, webview simples, onboarding no desktop.

Não envie o objeto `biometry`. O `201` de `POST /v1/accreditations/pf` ou `/pj` traz o link na pessoa que captura (na PJ, só o administrador):

```json
{
  "accreditationId": "acr_01J8Y7C8D9E0F1G2H3J4",
  "status": "PENDING_BIOMETRY",
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "biometryLink": "https://tenant.api.corpx.com/v1/accreditations/capture/{token}"
    }
  ]
}
```

Entregue `biometryLink` só a essa pessoa. O token no path **é a credencial**: não manda JWT, vale 24 h, e um `POST /v1/accreditations/{id}/capture` (ou o retry da pessoa) invalida o anterior.

```mermaid
sequenceDiagram
  participant Voce as Seu sistema
  participant Titular
  participant Pagina as Página hospedada
  participant API as API CorpX

  Voce->>API: POST /v1/accreditations/pf ou /pj
  API-->>Voce: 201 com persons[].biometryLink
  Voce->>Titular: abre o link
  Titular->>Pagina: GET /v1/accreditations/capture/{token}
  Pagina->>API: POST .../start
  API-->>Pagina: sessionToken, sdk.version, sdk.key
  loop cada blob do SDK
    Pagina->>API: POST .../session (requestBlob)
    API-->>Pagina: responseBlob, status
  end
  Pagina->>API: GET .../done
  API-->>Titular: redirect ao callbackUri com outcome
```

O titular toca **Iniciar verificação facial**. A página carrega o Browser SDK em `/v1/accreditations/capture/assets/{versão}/core-sdk/…`, pede a câmera, relê os blobs e, no fim, chama `GET .../done`. Essa rota relê a verificação e manda o navegador de volta ao seu [`callbackUri`](/baas/guias/abertura-de-contas/callback-uri) com `outcome`:

| `outcome`           | Significado                                                                       |
| ------------------- | --------------------------------------------------------------------------------- |
| `biometry_approved` | Identidade aprovada no provedor                                                   |
| `biometry_pending`  | A captura saiu e o provedor ainda consolida — o caso mais comum; espere o webhook |
| `biometry_failed`   | Reprovada; cabe retry da pessoa                                                   |
| `biometry_expired`  | Link ou verificação vencidos; peça outro                                          |
| `error`             | Falha de leitura no `/done`; consulte o `GET` do credenciamento                   |

O `outcome` escolhe a tela. O estado autoritativo continua no [webhook de onboarding](/baas/guias/abertura-de-contas/webhooks) e no `GET /v1/accreditations/{id}`.

Quem reabre o mesmo link depois de concluir vê o desfecho, não a câmera. Sem `callbackUri` cadastrada, a página mostra o resultado e para.

## Abertura: captura pelo SDK no seu app

Use quando o titular já está no **seu** iOS, Android ou web app e você quer a câmera ali, sem sair para o browser da CorpX.

### 1. Token de captura

Enquanto o credenciamento está `PENDING_BIOMETRY`:

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accreditations/$ACR_ID/capture" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-Id: $TENANT_ID"
```

```json
{
  "accreditationId": "acr_01J8Y7C8D9E0F1G2H3J4",
  "captureToken": "…",
  "expiresAt": "2026-10-17T12:00:00Z",
  "captureUrl": "https://tenant.api.corpx.com/v1/accreditations/capture/…"
}
```

`captureUrl` é a página hospedada, se você quiser cair nela. No app, o que importa é `captureToken`: ele entra no path das rotas públicas abaixo. **Não** mande JWT nelas. Cada emissão apaga o token anterior. Fora de `PENDING_BIOMETRY`, a resposta é `409 capture_not_available`.

### 2. Inicializar o SDK

No momento de abrir a câmera — não no boot do app:

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accreditations/capture/$CAPTURE_TOKEN/start"
```

```json
{
  "sessionToken": "…",
  "expiresAt": "2026-10-16T12:10:00Z",
  "sdk": {
    "version": "10.1.21",
    "key": "…"
  }
}
```

Carregue o zip **dessa** `sdk.version`. No Browser SDK v10:

1. `FaceTecSDK.setResourceDirectory` / `setImagesDirectory` para as pastas do zip (`core-sdk/FaceTecSDK.js/resources`, `core-sdk/FaceTec_images`);
2. `configureLocalization` com o `FaceTecStrings` do idioma;
3. `initializeWithSessionRequest(sdk.key, processor)`.

O `processor` implementa `onSessionRequest(requestBlob, cb)` e `onFaceTecExit`. O init **já** gera um `requestBlob` e conta no teto de 15 chamadas. Guarde `sessionToken` no seu backend e ecoe em cada `/session`; o SDK v10 não expõe o id da sessão ao app.

No iOS/Android o sample app do zip mostra o equivalente (`initialize` + session request). O fio com a CorpX é o mesmo: cada blob vai ao `/session`.

### 3. Relé de cada blob

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accreditations/capture/$CAPTURE_TOKEN/session" \
  -H "Content-Type: application/json" \
  -H "X-FaceTec-User-Agent: $UA" \
  -d '{
    "requestBlob": "<base64 do SDK>",
    "sessionToken": "<sessionToken do /start>"
  }'
```

`requestBlob` e `sessionToken` são obrigatórios. Corpo de até **5 MB** (`413 payload_too_large`).

Headers opcionais, só se o seu SDK gerar:

* `X-FaceTec-User-Agent` — `FaceTecSDK.createFaceTecAPIUserAgentString("")`;
* `X-Testing-API-Header` — `FaceTecSDK.getTestingAPIHeader()`, nos zips de desenvolvimento.

A API só repassa. Não invente valor.

Resposta `200`:

```json
{
  "responseBlob": "…",
  "status": "pending",
  "retryAllowed": true
}
```

Devolva `responseBlob` ao SDK (`processResponse` no Browser SDK). `status`:

* `pending` — handshake ou captura sem veredito; **não** conta tentativa reprovada; o SDK pede outro round;
* outro valor (`approved`, `rejected`, …) — houve veredito; `rejected` conta nas 3 falhas.

Não interprete o blob. Não chame o provedor.

Quando a sessão do SDK encerrar com veredito, mande o titular ao `GET /v1/accreditations/capture/{token}/done` (webview) **ou** consulte o credenciamento / webhook. O `/done` é o mesmo da página hospedada: relê a verificação e devolve o `outcome` no `callbackUri`.

### Limites do link

| Teto                                                 | Erro                                                    |
| ---------------------------------------------------- | ------------------------------------------------------- |
| Token com 24 h                                       | `410 capture_expired` — emita outro                     |
| 3 capturas **processadas e reprovadas**              | `422 capture_failed_limit`                              |
| 15 chamadas a `/start`+`/session` (inclui handshake) | `429 capture_call_limit`                                |
| Uma chamada por vez                                  | `409 capture_in_progress`                               |
| Verificação ainda não gravada                        | `409 capture_not_available` (tente de novo em segundos) |
| Credenciamento fora de `PENDING_BIOMETRY`            | `409 capture_not_available`                             |

Retry da pessoa (PF) ou do administrador (PJ) emite token novo. Sócio que não é administrador recebe `422 administrator_required`.

## Verificação de identidade

API paga, independente de conta bancária. `POST /v1/identity-verifications` com `method: link` devolve `verificationLink` (página do provedor). Com `method: facetec_sdk` (exige `provider: dracma_trust` e o pacote cadastrado) o `201` traz `facetec.deviceKeyIdentifier` e `facetec.sessionToken`; cada captura vai a `POST /v1/identity-verifications/{id}/facetec/process`.

O pedido do zip (bundle id, application id, domínios) é **este** da seção [Pedir o SDK](#pedir-o-sdk). O protocolo no app — `initializeWithSessionRequest`, `requestBlob` / `responseBlob`, 3 tentativas, 15 chamadas, token de 10 min — está no [guia de verificação de identidade](/baas/guias/autenticacao/verificacao-de-identidade#captura-pelo-sdk-facetec). Não misture as rotas: captura de abertura não chama `/facetec/process`; verificação de identidade não usa `/accreditations/capture`.

## O que não fazer

* Chamar a FaceTec ou a Dracma com o `sessionToken` / `sdk.key`. A sessão só vale nas rotas da CorpX.
* Reusar um zip de outro aplicativo, outro tenant ou da conta gratuita da FaceTec.
* Mudar o bundle id no store e continuar com o mesmo zip.
* Tratar `callbackUri` / `outcome` como prova: o webhook e o `GET` é que fecham o estado.
* Traduzir `errorCode` da API para um genérico. A tela precisa do código original (`capture_expired`, `facetec_sdk_not_enabled`, …).
* Logar `requestBlob`, `responseBlob`, `sessionToken` ou selfie.