Operações de utilizadores do fornecedor: CRUD

A gestão das entidades de utilizador principais é feita através de endpoints públicos em /v3/users/. Os anexos de perfil, como o carregamento de uma face importada, usam o caminho organização/aplicação com didit_internal_id. Esta página apresenta a visão conceptual: consulte a referência da API para os esquemas completos de pedido / resposta.

Listar utilizadores

GET /v3/users/ Devolve uma lista paginada de utilizadores da sua aplicação. Suporta filtros por estado, pesquisa, intervalo de datas e outros.

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 de utilização:

Sincronizar diariamente um subconjunto de utilizadores para o seu armazém de dados.
Encontrar utilizadores sinalizados para uma fila de analistas.
Pesquisar utilizadores pelo nome de apresentação.

Obter um utilizador

GET /v3/users/{vendor_data}/ Obtenha um único utilizador pelo vendor_data. Devolve o modelo de dados completo, incluindo os contadores agregados.

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

O vendor_data no URL é sensível a maiúsculas e minúsculas. Envie sempre o valor exato que usou na criação da sessão.

Criar um utilizador

POST /v3/users/create/ Crie uma entidade de utilizador antes de executar qualquer sessão. Útil para:

Pré-carregar metadados ou campos personalizados antes de o cliente proceder à verificação.
Definir um estado inicial (por exemplo, FLAGGED enquanto a sua equipa de onboarding analisa documentos manualmente).
Carregar previamente utilizadores de uma base de dados existente, para ter uma lista completa desde o primeiro 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" }
  }'

Se já existir um utilizador com esse vendor_data, a chamada devolve um erro de conflito. Nesse caso, use PATCH para atualizar. Também pode enviar os dados de contacto: first_name e last_name (combinados em full_name quando não enviar este último), email, phone_number e country. A Didit guarda email e phone_number em metadata.contact, e country em metadata.address. Para convidar a pessoa a verificar-se na mesma chamada, adicione send_verification_link: true com um email e um workflow_id. A Didit cria uma sessão de verificação para a pessoa nesse fluxo e envia-lhe a ligação por e-mail. O verification_link da resposta inclui o session_id, o session_number, o status, o url, o workflow_id e o email da sessão, e é null quando não pede uma ligação. Consulte Criar utilizador para as validações e os erros.

Carregar uma face importada

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/ Associe uma imagem facial fidedigna a um perfil de utilizador existente. Este é o passo seguinte adequado quando importa utilizadores de outro fornecedor e quer que a Didit guarde as respetivas provas faciais antes da primeira sessão na 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"
  }'

Consulte Carregar face do utilizador para os campos do pedido, os limites, os endpoints de listagem e eliminação e a distinção em relação à lista de bloqueio.

Atualizar um utilizador

PATCH /v3/users/{vendor_data}/ Atualize os campos de perfil editáveis. A maioria dos campos derivados de sessões verificadas é só de leitura. Tentar alterá-los através de PATCH será ignorado ou assinalado no registo de auditoria. Campos editáveis: display_name, metadata, tags. Só de leitura após a verificação: full_name, date_of_birth, portrait_image, todos os contadores agregados, 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" } }'

Emite um webhook user.data.updated com o array changed_fields.

Alterar o estado

PATCH /v3/users/{vendor_data}/update-status/ Mude um utilizador entre ACTIVE, FLAGGED e BLOCKED. As alterações de estado são aplicadas às sessões e transações futuras.

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 → para	Gatilho comum
`ACTIVE` → `FLAGGED`	Regra de transações, análise de um analista, alerta de monitorização AML contínua
`ACTIVE` → `BLOCKED`	Fraude confirmada, entrada manual na lista de bloqueio, correspondência na lista de bloqueio
`FLAGGED` → `ACTIVE`	Revisão concluída pelo analista
`BLOCKED` → `ACTIVE`	Desbloqueio manual por um analista

Emite um webhook user.status.updated.

Eliminar utilizadores (em lote)

POST /v3/users/delete/ Elimine um ou mais utilizadores. Os registos dos utilizadores são eliminados permanentemente, juntamente com todos os templates biométricos retidos para eles após a eliminação das sessões. As respetivas sessões de verificação não são abrangidas por este endpoint e mantêm-se, com a ligação ao utilizador removida. Elimine-as com Eliminar sessão ou Eliminar sessões em lote. As transações também não são abrangidas. Elimine-as na Consola.

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"]
  }'

Selecione os utilizadores por vendor_data_list, por didit_internal_id_list ou por ambos em simultâneo. Em alternativa, envie delete_all: true para remover todos os utilizadores da aplicação. Os parâmetros de lote filter_* da Consola são recusados aqui com um 400, em vez de serem ignorados, para que uma intenção restrita nunca se transforme numa eliminação total. Devolve uma contagem, {"deleted": <int>}, e não um resultado por item. Os identificadores sem correspondência são ignorados silenciosamente. Por isso, envie uma lista sem duplicados se quiser comparar deleted com o número de identificadores enviados.

Modelo de permissões

As chaves de API pertencem a uma única aplicação. O segredo principal e as chaves de acesso total podem chamar todos os endpoints /v3/users/* dessa aplicação, incluindo delete. Uma chave de API com âmbito limitado precisa de acesso a Pessoas (users): leitura para os endpoints GET e escrita para criar, atualizar, alterar o estado e eliminar. Criar um utilizador com send_verification_link: true requer também escrita em Sessões, porque cria uma sessão e envia a respetiva ligação por e-mail. Uma chave sem o acesso necessário responde com 403. Uma chave limitada a alguns fluxos ou a sessões aprovadas não consegue aceder de todo aos endpoints /v3/users/*. As funções são um conceito da Consola: o recurso de permissões users e as respetivas autorizações determinam o que um membro da equipa pode fazer na Consola, e não são avaliados nos pedidos com chave de API. Consulte Funções e permissões para ver essa matriz. Para impedir que um serviço elimine utilizadores, atribua-lhe uma chave apenas com leitura em Pessoas, ou sem qualquer acesso a Pessoas.

Limites de pedidos e idempotência

Todos os endpoints /v3/users/* estão sujeitos aos limites de pedidos padrão.
create não é idempotente: repetir a chamada com o mesmo vendor_data devolve um conflito. Evite duplicados do seu lado ou faça sempre um GET antes.
delete é idempotente: eliminar um utilizador já eliminado não tem efeito.

Webhooks disparados por estas operações

Operação	Webhook
`create`	nenhum para a própria chamada create: o primeiro `user.data.updated` chega quando uma sessão ou uma atualização preenche o perfil pela primeira vez
`update`	`user.data.updated` (com `changed_fields`)
`update-status`	`user.status.updated`
`delete`	nenhum: registe a eliminação do seu lado se precisar de reagir a ela

Próximos passos

Modelo de dados

Referência completa dos campos.

API de listagem

Esquema de GET /v3/users/.

API de criação

Esquema de POST /v3/users/create/.

Carregar rosto

Anexe imagens faciais importadas aos perfis de utilizador.

Visão geral

Preços

Fluxos e verificação

Revisão e operações

Entidades (utilizadores e empresas)

Definições e personalização

Segurança e conformidade

Didit Academy

Recursos

Operações de utilizadores do fornecedor: CRUD

Listar utilizadores

Obter um utilizador

Criar um utilizador

Carregar uma face importada

Atualizar um utilizador

Alterar o estado

Eliminar utilizadores (em lote)

Modelo de permissões

Limites de pedidos e idempotência

Webhooks disparados por estas operações

Próximos passos

Modelo de dados

API de listagem

API de criação

Carregar rosto

​Listar utilizadores

​Obter um utilizador

​Criar um utilizador

​Carregar uma face importada

​Atualizar um utilizador

​Alterar o estado

​Eliminar utilizadores (em lote)

​Modelo de permissões

​Limites de pedidos e idempotência

​Webhooks disparados por estas operações

​Próximos passos

Modelo de dados

API de listagem

API de criação

Carregar rosto

Listar utilizadores

Obter um utilizador

Criar um utilizador

Carregar uma face importada

Atualizar um utilizador

Alterar o estado

Eliminar utilizadores (em lote)

Modelo de permissões

Limites de pedidos e idempotência

Webhooks disparados por estas operações

Próximos passos