Criar uma pessoa automaticamente com enriquecimento
Referência API
Criar uma pessoa automaticamente com enriquecimento
Criar pessoa automaticamente com dados enriquecidos de registros — para entidades de pessoa na plataforma KYC e análise de risco gu1.
POST
Criar uma pessoa automaticamente com enriquecimento
Visão Geral
O endpoint de criação automática de pessoa permite que você crie pessoas fornecendo informações mínimas (ID fiscal e país). O sistema automaticamente:- Busca dados da pessoa de registros oficiais
- Enriquece a pessoa com informações adicionais
- Executa enriquecimentos automaticamente
Endpoint
Autenticação
Requer uma chave de API válida no cabeçalho de autorização:Corpo da Requisição
string
required
Número de identificação fiscal da pessoa (por exemplo, CPF para Brasil, CURP para México, CUIT para Argentina)
string
required
Código de país ISO 3166-1 alpha-2 (por exemplo, “BR”, “MX”, “AR”, “CL”)
string
required
Deve ser definido como
personstring
Seu identificador único para esta pessoa (opcional, será gerado automaticamente se não fornecido)
boolean
default:"false"
Marcar esta pessoa como cliente para fins de rastreamento
string | string[]
Um ou mais UUIDs de matrizes de risco (legacy: um único UUID). Após a criação, regras ativas dessas matrizes são executadas (salvo
skipRulesExecution: true).string[]
Preferido para várias matrizes: lista ordenada de UUIDs. Tem precedência sobre
riskMatrixId quando informado e não vazio.boolean
default:"false"
Pular a execução automática de regras após a criação da pessoa
string
default:"under_review"
Status inicial da pessoa
object | null
Horário operacional opcional da entidade principal (
timezone + weekly). Persistido na criação automática como na criação manual de entidades. Não se aplica a acionistas/relacionamentos criados por depth.number
default:"0"
Profundidade da extração de relacionamentos (0-5). Controla quantos níveis de relacionamentos buscar e criar automaticamente.
0: Sem relacionamentos (apenas entidade principal)1: Apenas relacionamentos diretos2: Relacionamentos + seus relacionamentos3-5: Níveis adicionais (use com cautela - pode criar muitas entidades)
object
Configurar a execução automática de integrações para a entidade pessoa principal. Veja Referência de Códigos de Provedores para códigos disponíveis.Tipo: Exemplo:
object (opcional)Propriedades:executeAllActiveEnrichments(boolean, opcional, padrão:false) - Executar todas as integrações de enriquecimento ativasenrichments(array, opcional, padrão:[]) - Array de códigos de provedores de enriquecimento específicos para executarenrichmentGroupRefs(array de strings, opcional) — Slugs de grupos de enriquecimento do Marketplace (somente enriquecimentos). ComexecuteAllActiveEnrichments: false, os grupos são resolvidos e mesclados comenrichmentsexplícitos. ComexecuteAllActiveEnrichments: true, os refs de grupo são ignorados;enrichmentsexplícitos ainda podem acrescentar códigos após o conjunto ativo.
Configurar a execução automática de integrações para relacionamentos descobertos. Útil ao usar Exemplo:
depth > 0. Veja Referência de Códigos de Provedores para códigos disponíveis.Tipo: object (opcional)Propriedades:executeAllActiveEnrichments(boolean, opcional, padrão:false) - Executar todos os enriquecimentos ativos em entidades relacionadasenrichments(object, opcional) - Enriquecimentos específicos por tipo de entidadecompany(array, padrão:[]) - Enriquecimentos para relacionamentos de empresaperson(array, padrão:[]) - Enriquecimentos para relacionamentos de pessoa
enrichmentGroupRefs(array de strings, opcional) — Mesmos slugs do objeto principal; comexecuteAllActiveEnrichments: falseaplicam-se acompanye aperson. ComexecuteAllActiveEnrichments: trueneste objeto, os refs de grupo são ignorados;enrichmentsexplícitos por tipo ainda podem acrescentar códigos após o ativo de cada lado.
Códigos de Enrichment Obrigatórios por País
Brasil (BR)
Os enrichments de relacionamentos devem ser incluídos no array
autoExecuteIntegrations.enrichments da entidade principal (não em autoExecuteIntegrationsShareholders), pois o sistema precisa executá-los na pessoa principal para descobrir os relacionamentos. O campo autoExecuteIntegrationsShareholders controla quais enrichments executar em cada entidade relacionada após serem criados.Argentina (AR)
object
Opcional — Dados do cliente para a pessoa principal que não devem ser substituídos pelos enrichments. Referência completa: Criação automática de entidades.Campos:
name, email, phone, birthDate → entityData.person.dateOfBirth, address → entityData.person.address, gender (enum: M | F | male | female | other | unknown — use other para não binário; ver Criar entidade).Exemplo:object
Opcional - Atributos personalizados como pares chave-valor para a entidade criada.Aplicam-se apenas à entidade principal (a pessoa criada), não a relacionamentos/acionistas. Útil para segmentos de negócio, etiquetas, IDs internos ou qualquer metadado que queira associar no momento da criação.Estrutura: objeto com chaves string e valores de qualquer tipo (string, number, boolean, array, etc.).Exemplo:
Resposta
boolean
Indica se a pessoa foi criada com sucesso
object
Informações completas sobre a criação:
entity(object) - A pessoa criada com todos os dadossummary(object) - Resumo da criaçãoerrors(object, opcional) - Detalhes de quaisquer erros
object
Resultado da execução de regras (apenas presente quando as regras foram executadas, ex. quando skipRulesExecution é
false e há matriz configurada via riskMatrixId ou riskMatrixIds), ou null. Quando presente, inclui:- success (boolean) - Se as regras foram executadas com sucesso
- rulesTriggered (number) - Número de regras disparadas
- alerts (array) - Alertas gerados pelas regras
- riskScore (number) - Pontuação de risco final
- decision (string) - Decisão final (APPROVE, REJECT, HOLD, REVIEW_REQUIRED)
- rulesExecutionSummary (object) - Presente quando as regras foram executadas. Ver abaixo a estrutura.
object
Na raiz da resposta (igual à API de transações). Mesmo valor que
rulesResult.rulesExecutionSummary. Apenas presente quando as regras foram executadas (ex. skipRulesExecution é false e a matriz de risco foi executada). Resumo de quais regras deram match (hit) vs não (no hit), ações executadas e pontuação total. Omitido quando as regras não foram executadas. Estrutura completa e exemplo: Resumo de Execução de Regras.- rulesHit (array) - Regras cujas condições foram atendidas. Cada item: name, description, score, priority, category, status (ex.
active,shadow), conditions (array de{ field, value, operator? }), actions (alerts, suggestion, status, assignedUser). - rulesNoHit (array) - Regras avaliadas mas cujas condições não foram atendidas. Mesma estrutura que rulesHit (inclui ações configuradas, não executadas).
- actionsExecuted (object) - Ações executadas agregadas de todas as regras que deram hit: alerts, suggestion (
BLOCK|SUSPEND|FLAG, maior peso), status (status aplicado à entidade, se houver), assignedUser ({ userId }, se houver), customKeys (array de strings, opcional) — chaves de ações personalizadas das regras que deram match; para integrações/workflows. - totalScore (number) - Soma do score de todas as regras que deram hit e não estão em status
shadow.
Exemplos
Criar Pessoa com Todas as Integrações Ativas
Criar Pessoa com Integrações Específicas
Exemplo de Resposta
Respostas de Erro
400 Bad Request - Tax ID Inválido
404 Not Found - Pessoa Não Encontrada no Registro
409 Conflict - Pessoa Já Existe
Melhores Práticas
- Tratamento de erros: Sempre verifique o campo
successna resposta - Limitação de taxa: Seja consciente dos limites de taxa ao criar múltiplas pessoas
- Seleção de integração: Escolha integrações específicas para melhor controle sobre custo e desempenho
Próximos Passos
- Obter Pessoa - Recuperar detalhes da pessoa
- Criar Pessoa Manualmente - Criar pessoas com seus próprios dados
- Criar Validação KYC - Iniciar verificação de identidade