API de templates biométricos

Por padrão, excluir uma sessão de verificação também exclui o embedding facial que alimentava a Busca facial 1:N e a detecção de duplicidades dessa sessão. Aplicações que precisam manter a detecção de duplicidades funcionando depois da exclusão da sessão podem ativar a retenção de templates biométricos. Nesse caso, a Didit exclui a sessão e todos os seus dados normalmente e mantém um único template biométrico facial, sem imagens e gerenciado separadamente, vinculado ao Usuário da sessão. A API de templates biométricos permite ver exatamente quais templates sua aplicação mantém, por que motivo e até quando, além de expurgá-los a qualquer momento. Cada template também aparece no Business Console em Lists → Biometric templates e no perfil do Usuário ao qual pertence.

Um template biométrico retido é um dado biométrico. Ele não é anônimo, não é temporário e não é excluído junto com a sessão. Ele permanece até a data de validade programada, até um prazo anterior exigido pela legislação aplicável, até a exclusão do Usuário, até uma solicitação de eliminação por motivos de privacidade ou até um expurgo explícito. Ative a retenção somente quando sua instrução como controlador e seu aviso de privacidade a contemplarem.

Como um template é criado

Gatilho	`source_type`	Origem da instrução
Você exclui uma sessão em uma aplicação com a retenção ativada, ou envia `retain_face_embeddings: true` em Excluir sessão ou Excluir sessões em lote	`session_delete`	`instruction_source: api` ou `console`
A janela geral de retenção de dados da sua aplicação faz uma sessão expirar em uma aplicação com a retenção ativada	`automatic_retention`	`instruction_source: automatic_retention`
Um backfill operado pela Didit, solicitado por você, para sessões excluídas antes de você ativar a retenção	`backfill`	`instruction_source: backfill`

A retenção exige um vínculo com um Usuário. Uma sessão criada sem vendor_data não tem Usuário e, portanto, não pode reter um template; a exclusão informa ineligible_no_vendor_user e o embedding é excluído junto com a sessão.

O que um template contém

Retido	Nunca retido
O template facial numérico usado na correspondência	A imagem do rosto, o vídeo de prova de vida, as imagens de documentos, os recortes de retrato e qualquer outra mídia
Um novo `uuid` aleatório do template e um `provenance_reference` opaco	O id, o número, a decisão, os campos de identidade extraídos ou os payloads de recursos da sessão excluída
O Usuário proprietário (`vendor_user_uuid`); o `vendor_data` é obtido do Usuário quando você lê o template, nunca copiado	Status na lista de bloqueio, correspondências anteriores, rótulos de fraude ou declarações de identidade entre organizações
`retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type`	Endereços de e-mail de quem executou a ação

Os templates são específicos de cada tenant e usados somente sob sua instrução, dentro da sua aplicação: detecção de rostos duplicados e de múltiplas contas, Autenticação biométrica e suas próprias listas de rostos. Eles nunca são usados para treinamento de modelos, análises, correspondência entre organizações, sinais compartilhados de Redes ou o processamento independente de fraudes da Didit.

Objeto template

{
  "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
  "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
  "vendor_data": "user-42",
  "source_type": "session_delete",
  "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
  "retention_policy": "retain_until_user_deleted",
  "retention_override": null,
  "retained_at": "2026-08-28T10:15:42.318402Z",
  "expires_at": "2027-08-28T10:15:42.318402Z",
  "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
  "retained_by_type": "API_KEY",
  "instruction_class": "operational_session_delete",
  "instruction_source": "api",
  "instruction_id": "post-approval-cleanup-2026-08",
  "held_out_of_use": false,
  "status": "active",
  "purged_at": null
}

Campo	Tipo	Descrição
`uuid`	UUID	Id do template. Gerado aleatoriamente; não é derivado da sessão excluída nem do rosto dela.
`vendor_user_uuid`	UUID	O Usuário proprietário.
`vendor_data`	string ou null	O `vendor_data` atual do Usuário, obtido quando você lê o template.
`source_type`	enum	`session_delete`, `automatic_retention` ou `backfill`.
`provenance_reference`	UUID	Referência opaca que vincula o template ao seu registro de auditoria. Não é o id da sessão excluída e não pode ser vinculada a ela pela API.
`retention_policy`	enum	A política da aplicação no momento da retenção: `delete_with_session` ou `retain_until_user_deleted`.
`retention_override`	boolean ou null	O valor de `retain_face_embeddings` enviado na exclusão, ou `null` quando a política foi aplicada.
`retained_at`	datetime	Quando o template foi criado.
`expires_at`	datetime	Quando o template expira e é expurgado automaticamente. Sempre definido.
`retained_by`	string	Principal que deu a instrução: o id da aplicação para chaves de API, o id do membro do Console para ações no Console ou um identificador `service:` para a retenção automática. Nunca um endereço de e-mail.
`retained_by_type`	enum	`API_KEY`, `CONSOLE_USER` ou `SYSTEM`.
`instruction_class`	enum	`operational_session_delete` ou `privacy_erasure`.
`instruction_source`	enum	`api`, `console`, `automatic_retention`, `backfill`, `privacy_erasure`, `explicit_template_purge`, `vendor_user_delete`, `expiry`, `reconciliation`, `migration` ou `system`.
`instruction_id`	string	O `instruction_id` que você enviou na exclusão, ou um id gerado pela Didit quando você o omitiu.
`held_out_of_use`	boolean	`true` somente enquanto um bloqueio legal estiver em vigor. Um template bloqueado é excluído de toda correspondência. Consulte Bloqueios legais.
`status`	enum	Status do ciclo de vida, veja abaixo.
`purged_at`	datetime ou null	Quando o template foi expurgado.

Status

`status`	Significado	Participa da correspondência?
`pending`	O template está sendo criado. Se a exclusão que o criou retornou `503`, repita a exclusão para concluí-la.	Não
`active`	O template participa da correspondência até `expires_at`.	Sim, a menos que `held_out_of_use` seja `true` ou que `expires_at` já tenha passado
`expired`	`expires_at` já passou e o expurgo automático está em andamento.	Não
`held_out_of_use`	Um bloqueio legal está em vigor.	Não
`purge_pending`	Um expurgo está em andamento.	Não
`purge_failed`	Um expurgo não pôde ser concluído porque um armazenamento biométrico estava indisponível. Repita o expurgo; enquanto isso, o template continua excluído da correspondência.	Não
`purged`	O template foi excluído. Visível apenas na resposta do expurgo como `already_purged`; templates expurgados não são listados e retornam `404` na consulta de detalhes.	Não

Como os templates são usados na correspondência

Um template active participa exatamente da mesma correspondência que o rosto de uma sessão em andamento: detecção automática de duplicatas durante novas sessões, a API de Busca facial independente, a Autenticação biométrica e as suas listas de rostos. Uma correspondência com um template retido é informada com source: "retained_template", o vendor_user_id e os vendor_data do Usuário ao qual ele pertence e o biometric_template_id. Ela nunca traz um ID de sessão, uma imagem de correspondência, dados de identidade ou um status, porque a sessão que gerou o rosto não existe mais. Consulte o relatório de Busca facial. Um template retido nunca entra em uma lista de bloqueio. Se o rosto da sessão excluída estava em uma lista de bloqueio de rostos, essa entrada da lista de bloqueio mantém a sua própria entrada biométrica independente e o seu próprio ciclo de vida: remover a entrada da lista exclui a entrada da lista de bloqueio, e expurgar o template não afeta a lista.

Pontos de expurgo

Todos os casos a seguir removem o template da correspondência e excluem o template armazenado:

Ponto de expurgo	Como
Expurgo explícito	`DELETE /v3/biometric-templates/{uuid}/` ou `POST /v3/biometric-templates/delete/`, ou Lists → Biometric templates no Console
Exclusão do usuário	`POST /v3/users/delete/` expurga todos os templates vinculados ao Usuário antes de o Usuário ser excluído
Apagamento por privacidade	Qualquer exclusão de uma sessão desse Usuário enviada com `deletion_instruction: "privacy_erasure"` expurga todos os templates vinculados ao Usuário, independentemente da política da aplicação
Expiração	A Didit expurga o template automaticamente assim que a data em `expires_at` passa

Alterar novamente a política da aplicação para delete_with_session impede a criação de novos templates, mas não expurga os existentes. Expurgue-os explicitamente. Os expurgos excluem primeiro o template armazenado e só depois marcam o template como expurgado. Por isso, um expurgo que retorna 503 deixa o template em purge_failed, já excluído da correspondência, e pode ser repetido com segurança. Um novo expurgo de um template já expurgado retorna already_purged.

Trilha de auditoria

Toda tentativa de retenção e de expurgo, incluindo falhas e resultados de inelegibilidade, é registrada com a entidade responsável pela ação (retained_by / responsável pelo expurgo e seu tipo), instruction_class, instruction_source, instruction_id, provenance_reference e o resultado. Envie o seu próprio instruction_id nas exclusões para poder correlacionar a trilha de auditoria da Didit com o seu registro de apagamentos. As entradas de auditoria nunca contêm imagens, vetores, campos de identidade ou endereços de e-mail.

Preservações legais

Uma preservação legal (legal hold) é uma exceção, nunca um modo de retenção. A Didit não aplica preservações por iniciativa própria; uma preservação só pode decorrer de uma instrução documentada nos termos do seu Acordo de Processamento de Dados ou de uma ordem vinculante de uma autoridade competente. Enquanto uma preservação estiver em vigor, o template fica marcado como held_out_of_use: ele é excluído de todo tipo de correspondência e da recuperação rotineira, e nunca pode ser pesquisado. Não existe API para criar ou remover preservações. Entre em contato com o seu representante da Didit se receber uma ordem que afete templates retidos.

Permissões e autenticação

Os endpoints de templates biométricos aceitam apenas chaves de API da aplicação (x-api-key). Tokens de usuário do Business Console são rejeitados com 403. Os usuários do Console gerenciam os templates em Lists → Biometric templates de acordo com suas permissões de lists.

Endpoints

Endpoint	Método	Finalidade
`/v3/biometric-templates/`	GET	Lista paginada com filtros
`/v3/biometric-templates/count/`	GET	Contagem com os mesmos filtros
`/v3/biometric-templates/{template_uuid}/`	GET	Um template
`/v3/biometric-templates/{template_uuid}/`	DELETE	Excluir permanentemente um template
`/v3/biometric-templates/delete/`	POST	Excluir permanentemente por lista de IDs ou por filtro

Conteúdo relacionado

Última modificação em 1 de novembro de 2026

​Como um template é criado

​O que um template contém

​Objeto template

​Status

​Como os templates são usados na correspondência

​Pontos de expurgo

​Trilha de auditoria

​Preservações legais

​Permissões e autenticação

​Endpoints

​Conteúdo relacionado

Como um template é criado

O que um template contém

Objeto template

Status

Como os templates são usados na correspondência

Pontos de expurgo

Trilha de auditoria

Preservações legais

Permissões e autenticação

Endpoints

Conteúdo relacionado