Gestió d'usuaris: operacions CRUD d'usuaris del proveïdor

Les operacions sobre l’entitat bàsica d’usuari es fan amb endpoints públics sota /v3/users/. Els adjunts del perfil, com la pujada d’una imatge facial importada, usen la ruta d’organització i aplicació amb didit_internal_id. Aquesta pàgina és una guia conceptual: consulta la referència de l’API per als esquemes complets de sol·licitud i resposta.

Llistar usuaris

GET /v3/users/ Retorna una llista paginada dels usuaris de la teva aplicació. Admet filtres per estat, cerca, interval de dates i més.

curl -G https://verification.didit.me/v3/users/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "search=jane" \
  --data-urlencode "page_size=50"

Casos d’ús:

Sincronitzar cada dia un subconjunt d’usuaris amb el teu magatzem de dades.
Trobar usuaris marcats per a una cua d’analistes.
Cercar usuaris pel nom visible.

Obtenir un usuari

GET /v3/users/{vendor_data}/ Recupera un sol usuari pel seu vendor_data. Retorna el model de dades complet, inclosos els comptadors agregats.

curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"

vendor_data a la URL distingeix entre majúscules i minúscules. Passa sempre el valor exacte que vas fer servir en crear la sessió.

Crear un usuari

POST /v3/users/create/ Crea una entitat d’usuari abans que s’executi cap sessió. És útil per a:

Carregar metadades o camps personalitzats abans que el client es verifiqui.
Establir un estat inicial (per exemple, FLAGGED mentre el teu equip d’alta revisa documents manualment).
Precarregar usuaris d’una base de dades existent perquè tinguis un llistat complet des del primer dia.

curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_source": "web" }
  }'

Si ja existeix un usuari amb aquest vendor_data, la crida retorna un error de conflicte: usa PATCH per actualitzar-lo. També pots enviar dades de contacte: first_name i last_name (que es combinen per formar full_name quan no l’envies), email, phone_number i country. Didit guarda email i phone_number a metadata.contact, i country a metadata.address. Per convidar la persona a verificar-se en la mateixa crida, afegeix send_verification_link: true amb un email i un workflow_id. Didit crea per a la persona una sessió de verificació en aquell flux de treball i li envia l’enllaç per correu electrònic. El verification_link de la resposta conté session_id, session_number, status, url, workflow_id i email de la sessió, i és null quan no en demanes cap. Consulta Crear usuari per a les comprovacions i els errors.

Pujar una imatge facial importada

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ Adjunta una imatge facial de confiança a un perfil d’usuari existent. És el pas adequat quan importes usuaris d’un altre proveïdor i vols que Didit incorpori la seva evidència facial abans de la primera sessió de Didit.

# First create or retrieve the User and read didit_internal_id from the response.
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'

Consulta Pujar la imatge facial d’un usuari per als camps de la sol·licitud, els límits, els endpoints de llistat i eliminació, i la diferència respecte a la llista de bloqueig.

Actualitzar un usuari

PATCH /v3/users/{vendor_data}/ Actualitza els camps de perfil modificables. La majoria de camps derivats de sessions verificades són de només lectura: si intentes canviar-los amb PATCH, s’ignoraran o es marcaran al registre d’auditoria. Camps modificables: display_name, metadata, tags. De només lectura després de la verificació: full_name, date_of_birth, portrait_image, tots els comptadors agregats i el mapa features.

curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'

Emet un webhook user.data.updated amb la matriu changed_fields.

Canviar l’estat

PATCH /v3/users/{vendor_data}/update-status/ Mou un usuari entre ACTIVE, FLAGGED i BLOCKED. Els canvis d’estat es propaguen a les sessions i transaccions futures.

curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Chargeback fraud pattern detected"
  }'

De → a	Desencadenant habitual
`ACTIVE` → `FLAGGED`	Regla de transacció, revisió d’un analista, coincidència en el monitoratge AML continu
`ACTIVE` → `BLOCKED`	Frau confirmat, entrada manual a la llista de bloqueig, coincidència amb la llista de bloqueig
`FLAGGED` → `ACTIVE`	Revisió resolta per un analista
`BLOCKED` → `ACTIVE`	Desbloqueig manual per un analista

Emet un webhook user.status.updated.

Eliminar usuaris (en lot)

POST /v3/users/delete/ Elimina un o diversos usuaris. Els registres d’usuari s’eliminen de manera permanent, juntament amb totes les plantilles biomètriques conservades per a ells després de l’eliminació de la sessió. Les seves sessions de verificació no les cobreix aquest endpoint i es conserven amb l’enllaç a l’usuari esborrat; elimina-les amb Eliminar sessió o Eliminar sessions en lot. Tampoc es cobreixen les transaccions: elimina-les des de la Console.

curl -X POST https://verification.didit.me/v3/users/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data_list": ["user-42", "user-43", "user-44"]
  }'

Selecciona usuaris per vendor_data_list, per didit_internal_id_list, o per tots dos alhora; o bé passa delete_all: true per eliminar tots els usuaris de l’aplicació. Els paràmetres de lot filter_* de la Console es rebutgen aquí amb un 400 en lloc d’ignorar-se, perquè una intenció restringida mai no es pugui convertir en un esborrat total. Retorna un recompte, {"deleted": <int>}, i no un resultat per element. Els identificadors que no coincideixen amb res s’ometen sense avisar, així que envia una llista sense duplicats si vols comparar deleted amb el nombre d’identificadors que has enviat.

Model de permisos

Les claus d’API pertanyen a una sola aplicació. La clau secreta principal i les claus d’accés complet poden cridar tots els endpoints /v3/users/* d’aquesta aplicació, inclosa delete. Una clau d’API amb permisos limitats necessita accés a Persones (users): lectura per als endpoints GET, i escriptura per crear, actualitzar, canviar l’estat i eliminar. Crear un usuari amb send_verification_link: true també necessita escriptura a Sessions, perquè crea una sessió i n’envia l’enllaç per correu electrònic. Una clau sense l’accés que necessita respon amb 403. Una clau limitada a alguns fluxos de treball o a sessions aprovades no pot accedir als endpoints /v3/users/*. Els rols són un concepte de la Console: el recurs de permís users i les seves declaracions decideixen què pot fer un membre de l’equip a la Console, i no s’avaluen per a les sol·licituds amb clau d’API. Consulta Rols i permisos per a aquesta matriu. Per evitar que un servei elimini usuaris, dona-li una clau amb només lectura de Persones, o sense cap accés a Persones.

Límits de freqüència i idempotència

Tots els endpoints /v3/users/* estan subjectes als límits de freqüència estàndard.
create no és idempotent: si tornes a enviar la mateixa petició amb el mateix vendor_data, retorna un conflicte. Evita duplicats pel teu compte, o fes sempre un GET primer.
delete és idempotent: eliminar un usuari ja eliminat no té cap efecte.

Webhooks activats per aquestes operacions

Operació	Webhook
`create`	cap per a la pròpia crida create: el primer `user.data.updated` arriba quan una sessió o una actualització omple el perfil per primera vegada
`update`	`user.data.updated` (amb `changed_fields`)
`update-status`	`user.status.updated`
`delete`	cap: registra l’eliminació pel teu costat si necessites reaccionar-hi

Passos següents

Model de dades

Referència completa dels camps.

API de llistat

Esquema de GET /v3/users/.

API de creació

Esquema de POST /v3/users/create/.

Pujar una cara

Adjunta imatges facials importades als perfils d’usuari.

Visió general

Preus

Fluxos de treball i verificació

Revisió i operacions

Entitats (usuaris i empreses)

Configuració i personalització

Seguretat i compliment

Didit Academy

Recursos

Gestió d'usuaris: operacions CRUD d'usuaris del proveïdor

Llistar usuaris

Obtenir un usuari

Crear un usuari

Pujar una imatge facial importada

Actualitzar un usuari

Canviar l’estat

Eliminar usuaris (en lot)

Model de permisos

Límits de freqüència i idempotència

Webhooks activats per aquestes operacions

Passos següents

Model de dades

API de llistat

API de creació

Pujar una cara

​Llistar usuaris

​Obtenir un usuari

​Crear un usuari

​Pujar una imatge facial importada

​Actualitzar un usuari

​Canviar l’estat

​Eliminar usuaris (en lot)

​Model de permisos

​Límits de freqüència i idempotència

​Webhooks activats per aquestes operacions

​Passos següents

Model de dades

API de llistat

API de creació

Pujar una cara

Llistar usuaris

Obtenir un usuari

Crear un usuari

Pujar una imatge facial importada

Actualitzar un usuari

Canviar l’estat

Eliminar usuaris (en lot)

Model de permisos

Límits de freqüència i idempotència

Webhooks activats per aquestes operacions

Passos següents