Esta página foi traduzida pela API Cloud Translation.

Registrar seus clientes

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

Tudo pronto para registrar partes
Preparar as mesas de registro da festa
Use o método projects.locations.instances.importRegisteredParties para registrar ou cancelar o registro de partes.
Validar a resposta do método
(Opcional) Exportar uma tabela com as partes registradas

Antes de começar

Antes de começar, você precisa de uma instância de IA antilavagem de dinheiro.

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

Um ou mais conjuntos de dados
Um modelo ajustado, treinado e testado com base em testes

Quando registrar partes

Antes de criar previsões para uma parte em um de seus conjuntos de dados, você precisa registrá-la. O registro não é necessário para treinamento, ajuste ou backtesting.

Os resultados da Prediction são usados na investigação de clientes quanto à lavagem de dinheiro, seja na fase de produção ou de teste/paralelo.

As partes registradas geram custos mensais adicionais por parte registrada. Consulte a página de preços para mais informações.

Como preparar mesas de registro para festas

Consulte a página de preços para informações sobre o registro de partes.

Prepare uma tabela para a linha de negócios em que você quer registrar partes. Essa tabela de registro de partido pode ser um subconjunto da tabela Party.

Esquema de partes do varejo

Coluna	Tipo	Descrição
`party_id`	`STRING`	Identificador exclusivo da parte nos conjuntos de dados da instância
`party_size`	`STRING`	NULL: o conteúdo é ignorado para registros de varejistas

Esquema de partes comerciais

Coluna Tipo Descrição

party_id STRING Identificador exclusivo da parte nos conjuntos de dados da instância

party_size

STRING

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 pequenos grupos comerciais com uma média de menos de 500 transações mensais
LARGE para grandes partes comerciais com média de mais de ou igual a 500 transações mensais

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

Como registrar partes

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

As partes de varejo e comerciais precisam ser registradas separadamente. Use chamadas de API separadas e tabelas de registro de parte separadas. Se um partido estiver em ambas as listas, eles serão considerados registros separados.
As previsões exigem que todas as partes sejam registradas com a linha de negócios associada à versão do mecanismo usada. Não será possível criar resultados de previsão se um conjunto de dados for usado que contenha qualquer parte não registrada na mesma linha de negócios.
A tabela de registro da parte fornecida é usada para anexar à lista atual de partes registradas na instância ou substituir todas as partes registradas na linha de negócios fornecida na instância.
Depois de registrado, não é possível cancelar o registro de um grupo 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 da validação, é possível executar 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 com êxito, mesmo se uma solicitação validateOnly anterior foi bem-sucedida.
Para registros de partes comerciais, um valor diferente de SMALL ou LARGE no campo party_size na tabela de registro da parte aciona um erro (Invalid party_size present in table). As partes registradas não são atualizadas.
Para registros de partes varejistas, o campo party_size é ignorado, e todas as partes na tabela de registro de parte 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, 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:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
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 com a descrição das partes registradas
REGISTERED_PARTIES_TABLE: a tabela que lista as partes registradas
Observação: é possível fornecer várias tabelas que listam as partes registradas. Use o formato "bq://{project}.{bqDatasetID}.{bqTableID}" para cada tabela na matriz partyTables.
UPDATE_MODE: use REPLACE para substituir partes que são removíveis na tabela de partes registradas por novas ou use APPEND para adicionar novas partes à tabela de partes registradas
LINE_OF_BUSINESS: este campo precisa corresponder ao valor lineOfBusiness na versão do mecanismo usado pela configuração do mecanismo. Use COMMERCIAL para clientes bancários comerciais (entidades legais e naturais) ou RETAIL para clientes de bancos de varejo.

Solicitar corpo JSON:

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

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

curl

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login , ou usando o Cloud Shell, que automaticamente conecta você à CLI gcloud . É possível verificar a conta ativa atual executando gcloud auth list.

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.REGISTERED_PARTIES_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

Observação: O comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

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.REGISTERED_PARTIES_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": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "importRegisteredParties",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

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

Resposta ao 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 resposta	Tipo	Descrição
`partiesAdded`	`integer`	Número de partes adicionadas por esta operação
`partiesRemoved`	`integer`	Número de partes removidas por essa operação
`partiesTotal`	`integer`	Número total de partes registradas nessa instância, após a conclusão da atualização
`partiesUptiered`	`integer`	Número total de partes comerciais que subiram de nível de pequeno a grande
`partiesDowntiered`	`integer`	Número total de partes comerciais que são rebaixadas de grande para pequena
`partiesFailedToDowntier`	`integer`	Número total de partes comerciais que não conseguiram reduzir de grande para pequeno
`partiesFailedToRemove`	`integer`	Número de partes que não foram removidas por esta operação

Como cancelar o registro de partes

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

Respostas de cancelamento de registro

Após a conclusão da operação, verifique a resposta da API para conferir se a operação levou ao resultado pretendido 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 puderam ser removidas devido a restrições (por exemplo, devido ao número mínimo de dias antes que uma parte possa ser cancelada).

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, 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:
- us-central1
- us-east1
- asia-south1
- europe-west1
- europe-west2
- europe-west4
- northamerica-northeast1
- southamerica-east1
INSTANCE_ID: o identificador definido pelo usuário para a instância
BQ_OUTPUT_DATASET_NAME: um conjunto de dados do BigQuery para exportar uma tabela com a descrição das partes registradas
REGISTERED_PARTIES_TABLE: a tabela em que as partes registradas serão gravadas.
WRITE_DISPOSITION: a ação que ocorrerá se a tabela de destino já existir. Use um dos seguintes valores:
- WRITE_EMPTY: exportar dados apenas se a tabela do BigQuery estiver vazia.
- WRITE_TRUNCATE: apague todos os dados atuais na tabela do BigQuery antes de gravar na tabela.
LINE_OF_BUSINESS: use COMMERCIAL para clientes de bancos comerciais (pessoas jurídicas e naturais) ou use RETAIL para clientes de bancos de varejo

Solicitar corpo JSON:

{
  "dataset": {
    "tableUri": "bq://PROJECT_ID.BQ_OUTPUT_DATASET_NAME.REGISTERED_PARTIES_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.REGISTERED_PARTIES_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.REGISTERED_PARTIES_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": CREATE_TIME,
    "target": "projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID",
    "verb": "exportRegisteredParties",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Para informações sobre como conseguir 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:

Coluna	Tipo	Descrição
`party_id`	`STRING`	Identificador exclusivo da parte nos conjuntos de dados da instância
`party_size`	`STRING`	Especifica a camada para clientes comerciais (grande x pequeno). Este campo não se aplica a clientes de varejo. `NULL` para todos os clientes de varejo `SMALL` para pequenos grupos comerciais com uma média de menos de 500 transações mensais `LARGE` para grandes partes comerciais com média de mais de ou igual a 500 transações mensais Todos os valores diferenciam maiúsculas de minúsculas.
`earliest_remove_time`	`STRING`	O primeiro horário em que a parte pode ser removida
`party_with_prediction_intent`	`STRING`	O indicador que sugere se há previsão de um grupo desde o registro
`registration_or_uptier_time`	`STRING`	A hora em que o partido foi registrado ou superior