Registrar seus clientes

Nesta página, você vai seguir as etapas abaixo para registrar e cancelar o registro de partes a fim de criar resultados de previsão:

  1. Verifique se você está pronto para registrar partes
  2. Preparar as tabelas de registro de partidos
  3. Use o método projects.locations.instances.importRegisteredParties para registrar ou cancelar o registro de partes
  4. Validar a resposta do método
  5. (Opcional) Exportar uma tabela de partes registradas

Antes de começar

Antes de começar, você precisa de uma instância de IA da AML.

Para permitir que um modelo crie previsões de pontuação de risco, primeiro é necessário registrar partes. Recomendamos que você registre as partes quando já tiver o seguinte:

Quando registrar partes

Antes de criar previsões para uma parte em um dos seus conjuntos de dados, é necessário registrar a parte. Não é necessário fazer o registro para treinamento, ajuste ou backtesting.

Os resultados da Prediction são usados para investigar clientes em caso de lavagem de dinheiro em uma fase de produção ou de teste (paralela). Também é possível criar seus próprios processos de governança e análise de modelos com base nos resultados das previsões.

O registro de partes gera custos mensais adicionais por parte registrada. Consulte a página de preços para mais informações.

Como preparar as tabelas de registro de partidos

Leia a página de preços para saber como registrar partes.

Prepare uma tabela para a atividade em que você quer registrar as partes. Se você já tiver algumas partes registradas, essa tabela de registro de partes poderá conter um subconjunto das partes da tabela Parte que você quer usar para os resultados da previsão.

Esquema de partes de varejo

ColunaTipoDescrição
party_idSTRINGIdentificador exclusivo da parte nos conjuntos de dados da instância
party_sizeSTRINGNULL: o conteúdo é ignorado para registros de terceiros de varejo

Esquema de partes comerciais

ColunaTipoDescrição
party_idSTRINGIdentificador exclusivo da parte nos conjuntos de dados da instância
party_sizeSTRING Tamanho do grupo solicitado. O nível é baseado no número médio de transações mensais da parte nos últimos 365 dias:
  • SMALL para pequenas partes comerciais com menos de 500 transações mensais em média
  • LARGE para grandes partes comerciais com uma média mensal de 500 transações ou mais

Todos os valores diferenciam maiúsculas de minúsculas.

Como registrar partes

As partes são registradas separadamente para cada instância de IA de AML. Observações:

  • As partes comerciais e de varejo precisam ser registradas separadamente. Use chamadas de API separadas e tabelas de registro de partes separadas. Se uma parte estiver nas duas listas, ela será considerada um registro separado.
  • As previsões exigem que todas as partes estejam registradas na linha de negócios associada à versão do mecanismo usada. Não é possível criar resultados de previsão se um conjunto de dados for usado que contenha qualquer parte não registrada com a mesma linha de negócios.
  • A tabela de registro de partes fornecida é usada para anexar à lista de partes registradas na instância ou substituir todas as partes registradas para a linha de negócios fornecida na instância.
  • Depois de registrado, o registro de uma parte não pode ser cancelado por algum tempo (consulte a página de preços). Por esse motivo, você pode definir o campo validateOnly como TRUE. Esse campo permite que você veja o efeito líquido e a resposta do método sem mudar as partes registradas. Depois de validar, você pode realizar a operação novamente e definir o parâmetro validateOnly como FALSE.
  • Sempre verifique a resposta de uma solicitação de registro para garantir que todas as partes foram registradas, mesmo que uma solicitação validateOnly anterior tenha sido bem-sucedida.
  • Para registros de partes comerciais, um valor diferente de SMALL ou LARGE no campo party_size na tabela de registro de partes gera um erro (Invalid party_size present in table). As partes registradas não são atualizadas.
  • Para registros de partes de varejo, o campo party_size é ignorado, e todas as partes na tabela de registro de partes fornecida são registradas.

Para importar partes registradas, use o método projects.locations.instances.importRegisteredParties.

As informações a seguir também estão disponíveis em Criar e gerenciar instâncias.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
  • LOCATION: o local da instância. Use uma das regiões compatíveis.
    Mostrar locais
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID: o identificador definido pelo usuário para a instância
  • BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME: um conjunto de dados do BigQuery que contém uma tabela que descreve as partes registradas
  • PARTY_REGISTRATION_TABLE: a tabela que listas as partes registradas
  • UPDATE_MODE: use REPLACE para substituir partes que são removíveis na tabela de partes registradas por novas partes ou use APPEND para adicionar novas partes à tabela de partes registradas.
  • LINE_OF_BUSINESS: esse campo precisa corresponder ao valor lineOfBusiness na versão do mecanismo usada pela configuração do mecanismo. Use COMMERCIAL para clientes de bancos comerciais (entidades legais e naturais) ou RETAIL para clientes de bancos de varejo.

Corpo JSON da solicitação:

{
  "partyTables": [
     "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.PARTY_REGISTRATION_TABLE"
  ],
  "mode": "UPDATE_MODE",
  "lineOfBusiness": "LINE_OF_BUSINESS"
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

cat > request.json << 'EOF'
{
  "partyTables": [
     "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.PARTY_REGISTRATION_TABLE"
  ],
  "mode": "UPDATE_MODE",
  "lineOfBusiness": "LINE_OF_BUSINESS"
}
EOF

Depois execute o comando a seguir para enviar a solicitação REST: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:importRegisteredParties"

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

@'
{
  "partyTables": [
     "bq://PROJECT_ID.BQ_INPUT_REGISTERED_PARTIES_DATASET_NAME.PARTY_REGISTRATION_TABLE"
  ],
  "mode": "UPDATE_MODE",
  "lineOfBusiness": "LINE_OF_BUSINESS"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação REST: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:importRegisteredParties" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": "2023-03-14T15:52:55.358979323Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "importRegisteredParties",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Para saber como receber o resultado da operação de longa duração (LRO, na sigla em inglês), consulte Gerenciar operações de longa duração.

Resposta de registro

Quando a LRO é concluída, a resposta indica o número de partes que foram adicionadas, removidas ou atualizadas pela operação.

Campo de respostaTipoDescrição
partiesAddedinteger Número de partes adicionadas por essa operação
partiesRemovedinteger Número de partes removidas por essa operação
partiesTotalinteger Número total de partes registradas nesta instância após a conclusão da operação de atualização
partiesUptieredinteger Número total de partes comerciais que foram promovidas de pequenas para grandes
partiesDowntieredinteger Número total de partes comerciais que são rebaixadas de grandes para pequenas
partiesFailedToDowntierinteger Número total de partes comerciais que não conseguiram fazer downgrade de grande para pequeno
partiesFailedToRemoveinteger Número de partes que não foram removidas por essa operação

Como cancelar o registro de partes

As partes são canceladas por instância de IA de AML usando o mesmo método projects.locations.instances.importRegisteredParties e substituindo a lista de partes existente. Defina o campo mode como REPLACE. Essa configuração desregistra todas as partes registradas atualmente (para a linha de negócios fornecida) que não fazem parte da tabela de registro de partes fornecida.

Respostas de cancelamento de registro

Depois que a operação for concluída, verifique a resposta da API para conferir se a operação levou ao resultado esperado em termos de números de partes adicionadas ou removidas e o número total de partes registradas.

A resposta da API também retorna o número de partes que não podem ser removidas devido a restrições. Por exemplo, um cliente não pode ser cancelado até que um número mínimo de dias tenha decorrido.

Exportar partes registradas

Para exportar partes registradas, use o método projects.locations.instances.exportRegisteredParties.

As informações a seguir também estão disponíveis em Criar e gerenciar instâncias.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto do Google Cloud listado nas Configurações do IAM
  • LOCATION: o local da instância. Use uma das regiões compatíveis.
    Mostrar locais
    • us-central1
    • us-east1
    • asia-south1
    • europe-west1
    • europe-west2
    • europe-west4
    • northamerica-northeast1
    • southamerica-east1
    • australia-southeast1
  • INSTANCE_ID: o identificador definido pelo usuário para a instância
  • BQ_OUTPUT_DATASET_NAME: um conjunto de dados do BigQuery em que exportar uma tabela que descreve as partes registradas
  • PARTY_REGISTRATION_TABLE: a tabela para gravar as partes registradas
  • WRITE_DISPOSITION: a ação que ocorre se a tabela de destino já existir. Use um dos seguintes valores:
    • WRITE_EMPTY: só exporta dados se a tabela do BigQuery estiver vazia.
    • WRITE_TRUNCATE: apague todos os dados da tabela do BigQuery antes de gravar nela.
  • LINE_OF_BUSINESS: use COMMERCIAL para clientes de bancos comerciais (entidades legais e naturais) ou RETAIL para clientes de bancos de varejo.

Corpo JSON da solicitação:

{
  "dataset": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  },
  "lineOfBusiness": "LINE_OF_BUSINESS"
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

cat > request.json << 'EOF'
{
  "dataset": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  },
  "lineOfBusiness": "LINE_OF_BUSINESS"
}
EOF

Depois execute o comando a seguir para enviar a solicitação REST: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:exportRegisteredParties"

PowerShell

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual: 

@'
{
  "dataset": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.PARTY_REGISTRATION_TABLE",
    "writeDisposition": "WRITE_DISPOSITION"
  },
  "lineOfBusiness": "LINE_OF_BUSINESS"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação REST: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://financialservices.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:exportRegisteredParties" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.financialservices.v1.OperationMetadata",
    "createTime": "2023-03-14T15:52:55.358979323Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "exportRegisteredParties",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Para saber como receber o resultado da operação de longa duração (LRO, na sigla em inglês), consulte Gerenciar operações de longa duração.

Esse método gera uma tabela do BigQuery com o seguinte esquema:

ColunaTipoDescrição
party_idSTRINGIdentificador exclusivo da parte nos conjuntos de dados da instância
party_sizeSTRING Especifica o nível para clientes comerciais (grandes e pequenos). Esse campo não se aplica a clientes de varejo.
  • NULL para todos os clientes de varejo
  • SMALL para pequenas partes comerciais com menos de 500 transações mensais em média
  • LARGE para grandes partes comerciais com uma média mensal de 500 transações ou mais

Todos os valores diferenciam maiúsculas de minúsculas.

earliest_remove_timeSTRINGA primeira data e hora em que a parte pode ser removida
party_with_prediction_intentSTRINGO indicador que sugere se uma festa foi prevista desde o registro
registration_or_uptier_timeSTRINGO horário em que a festa foi registrada ou promovida