API de plantilles biomètriques

Per defecte, eliminar una sessió de verificació també elimina l’embedding facial que alimentava la Cerca facial 1:N i la detecció de duplicats d’aquella sessió. Les aplicacions que necessiten que la detecció de duplicats continuï funcionant després de l’eliminació de la sessió poden optar per la retenció de plantilles biomètriques. Didit aleshores elimina la sessió i totes les seves dades com de costum, i conserva una plantilla biomètrica facial gestionada per separat i sense imatges, vinculada a l’usuari de la sessió. L’API de plantilles biomètriques et permet veure exactament quines plantilles té la teva aplicació, per què, fins quan, i purgar-les en qualsevol moment. Totes les plantilles també són visibles a la Business Console, a Lists → Biometric templates, i al perfil de l’usuari propietari.

Una plantilla biomètrica retinguda és una dada biomètrica. No és anònima, no és transitòria i no s’elimina juntament amb la sessió. Es manté fins a la seva data d’expiració programada, fins al termini anterior aplicable segons la llei, fins a l’eliminació de l’usuari, fins a una sol·licitud d’esborrat per motius de privacitat o fins a una purga explícita. Activa la retenció només quan la instrucció del responsable del tractament i l’avís de privacitat la cobreixin.

Com es crea una plantilla

Disparador	`source_type`	D’on prové la instrucció
Elimines una sessió en una aplicació que ha optat per la retenció, o envies `retain_face_embeddings: true` a Delete Session o a Batch Delete Sessions	`session_delete`	`instruction_source: api` o `console`
La finestra general de retenció de dades de la teva aplicació fa expirar una sessió en una aplicació que ha optat per la retenció	`automatic_retention`	`instruction_source: automatic_retention`
Un backfill operat per Didit que has sol·licitat per a sessions eliminades abans que optessis per la retenció	`backfill`	`instruction_source: backfill`

La retenció requereix un ancoratge d’usuari. Una sessió creada sense vendor_data no té usuari, per tant no pot retenir cap plantilla; la resposta de l’eliminació indica ineligible_no_vendor_user i l’embedding s’elimina juntament amb la sessió.

Què conté una plantilla

Es retè	Mai es retè
La plantilla facial numèrica usada per a la coincidència	La imatge facial, el vídeo de prova de vida, les imatges del document, els retalls del retrat i qualsevol altre contingut multimèdia
Un `uuid` de plantilla nou i aleatori i un `provenance_reference` opac	L’id, el número, la decisió, els camps d’identitat extrets o els payloads de funcionalitats de la sessió eliminada
L’usuari propietari (`vendor_user_uuid`); `vendor_data` es resol a partir de l’usuari quan llegeixes la plantilla, mai es copia	L’estat de la llista de bloqueig, coincidències prèvies, etiquetes de frau o afirmacions d’identitat entre organitzacions
`retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type`	Adreces de correu electrònic dels actors

Les plantilles estan circumscrites al teu tenant i només s’usen per instrucció teva dins de la teva aplicació: detecció de cares duplicades i de múltiples comptes, Autenticació biomètrica i les teves pròpies llistes facials. Mai no s’usen per a l’entrenament de models, analítica, coincidència entre organitzacions, senyals compartits de Xarxes ni el processament independent de frau de Didit.

Objecte de plantilla

{
  "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
}

Camp	Tipus	Descripció
`uuid`	UUID	Id de la plantilla. Generat aleatòriament; no es deriva de la sessió eliminada ni de la seva cara.
`vendor_user_uuid`	UUID	L’usuari propietari.
`vendor_data`	string o null	El `vendor_data` actual de l’usuari, resolt quan llegeixes la plantilla.
`source_type`	enum	`session_delete`, `automatic_retention` o `backfill`.
`provenance_reference`	UUID	Referència opaca que vincula la plantilla al seu registre d’auditoria. No és l’id de la sessió eliminada i no es pot resoldre fins a ella a través de l’API.
`retention_policy`	enum	La política de l’aplicació en el moment de la retenció: `delete_with_session` o `retain_until_user_deleted`.
`retention_override`	boolean o null	El valor de `retain_face_embeddings` enviat en l’eliminació, o `null` quan es va aplicar la política.
`retained_at`	datetime	Quan es va crear la plantilla.
`expires_at`	datetime	Quan la plantilla expira i es purga automàticament. Sempre està definit.
`retained_by`	string	L’entitat que va donar la instrucció: l’id de l’aplicació per a les claus d’API, l’id del membre de la Console per a les accions de la Console, o un identificador `service:` per a la retenció automàtica. Mai una adreça de correu electrònic.
`retained_by_type`	enum	`API_KEY`, `CONSOLE_USER` o `SYSTEM`.
`instruction_class`	enum	`operational_session_delete` o `privacy_erasure`.
`instruction_source`	enum	`api`, `console`, `automatic_retention`, `backfill`, `privacy_erasure`, `explicit_template_purge`, `vendor_user_delete`, `expiry`, `reconciliation`, `migration` o `system`.
`instruction_id`	string	El `instruction_id` que vas enviar en l’eliminació, o un id generat per Didit si l’havies omès.
`held_out_of_use`	boolean	`true` només mentre s’aplica un bloqueig legal. Una plantilla bloquejada queda exclosa de tota la coincidència. Consulta Bloquejos legals.
`status`	enum	Estat del cicle de vida, vegeu a continuació.
`purged_at`	datetime o null	Quan es va purgar la plantilla.

Estat

`status`	Significat	Participa en la coincidència?
`pending`	La plantilla s’està creant. Si l’eliminació que la va crear ha retornat `503`, repeteix l’eliminació per completar-la.	No
`active`	La plantilla participa en la coincidència fins a `expires_at`.	Sí, tret que `held_out_of_use` sigui `true` o que `expires_at` ja hagi passat
`expired`	`expires_at` ja ha passat i la purga automàtica és en curs.	No
`held_out_of_use`	S’aplica un bloqueig legal.	No
`purge_pending`	Hi ha una purga en curs.	No
`purge_failed`	Una purga no s’ha pogut completar perquè un magatzem biomètric no estava disponible. Repeteix la purga; mentrestant, la plantilla continua exclosa de la coincidència.	No
`purged`	La plantilla està eliminada. Només és visible a la resposta de la purga com a `already_purged`; les plantilles purgades no es llisten i retornen `404` en consultar-les individualment.	No

Com s’utilitzen les plantilles en la coincidència

Una plantilla active participa exactament en la mateixa coincidència que un rostre d’una sessió en curs: la detecció automàtica de duplicats en noves sessions, l’API de cerca facial independent, la Autenticació biomètrica i les teves llistes de rostres. Una coincidència amb una plantilla retinguda s’informa amb source: "retained_template", el vendor_user_id i vendor_data de l’usuari propietari i el biometric_template_id. Mai inclou un id de sessió, una imatge de coincidència, dades d’identitat ni un estat, perquè la sessió que va generar el rostre ja no existeix. Consulta informe de cerca facial. Una plantilla retinguda mai no es posa en una llista de bloqueig. Si el rostre de la sessió eliminada estava en una llista de bloqueig de rostres, aquesta entrada de la llista conserva la seva pròpia entrada biomètrica independent i el seu propi cicle de vida: eliminar l’entrada de la llista suprimeix l’entrada de bloqueig, i purgar la plantilla no afecta la llista.

Punts de purga

Tots els casos següents eliminen la plantilla de la coincidència i esborren la plantilla emmagatzemada:

Punt de purga	Com
Purga explícita	`DELETE /v3/biometric-templates/{uuid}/` o `POST /v3/biometric-templates/delete/`, o Llistes → Plantilles biomètriques a la Console
Eliminació d’usuari	`POST /v3/users/delete/` purga totes les plantilles vinculades a l’usuari abans d’eliminar-lo
Esborrat per privacitat	Qualsevol eliminació d’una sessió d’aquest usuari enviada amb `deletion_instruction: "privacy_erasure"` purga totes les plantilles vinculades a l’usuari, independentment de la política de l’aplicació
Caducitat	Didit purga la plantilla automàticament quan passa `expires_at`

Tornar a establir la política de l’aplicació en delete_with_session deixa de crear noves plantilles, però no purga les existents. Purga-les explícitament. Les purgues esborren primer la plantilla emmagatzemada i només després marquen la plantilla com a purgada, de manera que una purga que retorna 503 deixa la plantilla en purge_failed, ja exclosa de la coincidència, i és segur repetir-la. Una purga repetida d’una plantilla ja purgada retorna already_purged.

Registre d’auditoria

Cada intent de retenció i de purga, inclosos els errors i els resultats no elegibles, es registra amb el principal que actua (retained_by / el principal que realitza la purga i el tipus de principal), instruction_class, instruction_source, instruction_id, provenance_reference i el resultat. Envia el teu propi instruction_id en les eliminacions per poder correlacionar el registre d’auditoria de Didit amb el teu registre d’esborraments. Les entrades d’auditoria mai no contenen imatges, vectors, camps d’identitat ni adreces de correu electrònic.

Retencions legals

Una retenció legal és una excepció, mai un mode de retenció. Didit no aplica retencions per iniciativa pròpia; una retenció només pot derivar d’una instrucció documentada d’acord amb el teu Acord de Tractament de Dades o d’una ordre vinculant d’una autoritat competent. Mentre una retenció estigui vigent, la plantilla es marca com a held_out_of_use: queda exclosa de tot tipus de coincidència i de la recuperació rutinària, i mai no és cercable. No hi ha cap API per crear ni aixecar retencions. Contacta amb el teu representant de Didit si reps una ordre que afecti plantilles retingudes.

Permisos i autenticació

Els endpoints de Plantilles biomètriques accepten només claus d’API de l’aplicació (x-api-key). Els tokens d’usuari de la Business Console es rebutgen amb 403. Els usuaris de la Console gestionen les plantilles a Llistes → Plantilles biomètriques amb els seus permisos de lists.

Endpoints

Endpoint	Mètode	Finalitat
`/v3/biometric-templates/`	GET	Llista paginada amb filtres
`/v3/biometric-templates/count/`	GET	Recompte amb els mateixos filtres
`/v3/biometric-templates/{template_uuid}/`	GET	Una plantilla
`/v3/biometric-templates/{template_uuid}/`	DELETE	Purgar una plantilla
`/v3/biometric-templates/delete/`	POST	Purgar per llista d’ids o per filtre

Relacionat

Darrera modificació el 7 de novembre del 2026

​Com es crea una plantilla

​Què conté una plantilla

​Objecte de plantilla

​Estat

​Com s’utilitzen les plantilles en la coincidència

​Punts de purga

​Registre d’auditoria

​Retencions legals

​Permisos i autenticació

​Endpoints

​Relacionat

Com es crea una plantilla

Què conté una plantilla

Objecte de plantilla

Estat

Com s’utilitzen les plantilles en la coincidència

Punts de purga

Registre d’auditoria

Retencions legals

Permisos i autenticació

Endpoints

Relacionat