Criar uma empresa automaticamente com enriquecimento

curl --request POST \
  --url http://api.gu1.ai/entities/automatic \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taxId": "<string>",
  "country": "<string>",
  "type": "<string>",
  "externalId": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'

{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

POST

entities

automatic

Criar uma empresa automaticamente com enriquecimento

curl --request POST \
  --url http://api.gu1.ai/entities/automatic \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taxId": "<string>",
  "country": "<string>",
  "type": "<string>",
  "externalId": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'

{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

Visão Geral

O endpoint de criação automática de empresa permite que você crie empresas fornecendo informações mínimas (tax ID e país). O sistema automaticamente:

Busca dados da empresa de registros oficiais
Enriquece a empresa com informações adicionais
Executa enriquecimentos automaticamente

Isso é ideal para processos KYB (Know Your Business) onde você deseja integrar empresas com informações completas automaticamente.

Endpoint

POST http://api.gu1.ai/entities/automatic

Autenticação

Requer uma chave de API válida no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Corpo da Requisição

taxId

string

required

Número de identificação fiscal da empresa (ex: CNPJ para Brasil, RFC para México, CUIT para Argentina)

📋 Ver Formatos de Tax ID por País para formatos aceitos e regras de validação para cada país.

country

string

required

Código de país ISO 3166-1 alpha-2 (ex: “BR”, “MX”, “AR”, “CL”)

type

string

required

Deve ser definido como company

externalId

string

Seu identificador único para esta empresa (opcional, será gerado automaticamente se não fornecido)

isClient

boolean

default:"false"

Marcar esta empresa como cliente/negócio para fins de rastreamento

riskMatrixId

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

riskMatrixIds

string[]

Preferido para várias matrizes: lista ordenada de UUIDs. Tem precedência sobre riskMatrixId quando informado e não vazio.

skipRulesExecution

boolean

default:"false"

Pular execução automática de regras após criação da empresa

status

string

default:"under_review"

Status inicial para a empresa

operationalHours

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.

depth

number

default:"0"

Profundidade da extração de relacionamento (0-5). Controla quantos níveis de acionistas/relacionamentos buscar e criar automaticamente.

0: Sem relacionamentos (apenas entidade principal)
1: Apenas acionistas diretos
2: Acionistas + seus acionistas
3-5: Níveis adicionais (use com cautela - pode criar muitas entidades)

autoExecuteIntegrations

object

Configurar execução automática de integrações para a entidade empresa principal. Veja Referência de Códigos de Provedor para códigos disponíveis.Tipo: object (opcional)Propriedades:

executeAllActiveEnrichments (boolean, opcional, padrão: false) - Executar todas as integrações de enriquecimento ativas
enrichments (array, opcional, padrão: []) - Array de códigos de provedores de enriquecimento específicos para executar
enrichmentGroupRefs (array de strings, opcional) — Slugs de grupos de enriquecimento do Marketplace (somente enriquecimentos). Com executeAllActiveEnrichments: false, os grupos são resolvidos e mesclados com enrichments explícitos. Com executeAllActiveEnrichments: true, os refs de grupo são ignorados; enrichments explícitos ainda podem acrescentar códigos após o conjunto ativo.

{
  executeAllActiveEnrichments?: boolean; // padrão: false
  enrichments?: ValidProviderCodesEnum[]; // padrão: []
  enrichmentGroupRefs?: string[];
}

Exemplo:

{
  "executeAllActiveEnrichments": false,
  "enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
  "enrichmentGroupRefs": ["my_marketplace_group_slug"],
}

autoExecuteIntegrationsShareholders

object

Configurar execução automática de integrações para acionistas/relacionamentos descobertos. Útil ao usar depth > 0. Veja Referência de Códigos de Provedor para códigos disponíveis.Tipo: object (opcional)Propriedades:

executeAllActiveEnrichments (boolean, opcional, padrão: false) - Executar todos os enriquecimentos ativos nos acionistas
enrichments (object, opcional) - Enriquecimentos específicos por tipo de entidade
- company (array, padrão: []) - Enriquecimentos para acionistas empresa
- person (array, padrão: []) - Enriquecimentos para acionistas pessoa
enrichmentGroupRefs (array de strings, opcional) — Mesmos slugs do objeto principal; com executeAllActiveEnrichments: false aplicam-se a company e a person. Com executeAllActiveEnrichments: true neste objeto, os refs de grupo são ignorados; enrichments explícitos por tipo ainda podem acrescentar códigos após o ativo de cada lado.

{
  executeAllActiveEnrichments?: boolean;
  enrichments?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
  enrichmentGroupRefs?: string[];
}

Exemplo:

{
  "enrichments": {
    "person": [
      "br_cpfcnpj_complete_person_enrichment",
      "global_complyadvantage_person_search_enrichment"
    ],
    "company": ["br_cpfcnpj_complete_company_enrichment"]
  },
  "enrichmentGroupRefs": ["shareholder_pipeline_group_slug"]
}

Códigos de Enrichment Obrigatórios por País

Ao usar códigos de enrichment específicos (não executeAllActiveEnrichments: true), certos enrichments são obrigatórios para que a criação automática funcione. Sem eles, o sistema não consegue buscar os dados básicos da empresa nos registros oficiais e a requisição falhará.

Brasil (BR)

Cenário	Código(s) de Enrichment Obrigatório(s)	Descrição
Entidade principal	`br_cpfcnpj_complete_company_enrichment`	Busca dados da empresa do CNPJ/Receita Federal (razão social, nome fantasia, endereço, setor, etc.)
Sócios (`depth > 0`)	`br_bdc_shareholders_enrichment`	Obrigatório em `autoExecuteIntegrations.enrichments`. Busca o QSA (Quadro Societário e de Administradores) para descobrir sócios e diretores

O enrichment de sócios deve ser incluído no array autoExecuteIntegrations.enrichments da entidade principal (não em autoExecuteIntegrationsShareholders), pois o sistema precisa executá-lo na empresa principal para descobrir o QSA. O campo autoExecuteIntegrationsShareholders controla quais enrichments executar em cada sócio após serem criados.

Argentina (AR)

Cenário	Código de Enrichment Obrigatório	Descrição
Entidade principal	`ar_nosis_extended_verification_enrichment`	Busca dados da empresa do Nosis (razão social, situação CUIT, endereço, atividades, etc.)

Argentina não suporta criação automática de sócios ainda. O parâmetro depth deve ser 0. Se depth > 0 for fornecido, a requisição falhará com um erro.

customData

object

Opcional — Dados do cliente para a empresa principal que não devem ser substituídos pelos enrichments. Referência completa: Criação automática de entidades.Campos: name, email, phone, address → entityData.company.address (birthDate não se aplica a empresas).Exemplo:

{
  "taxId": "12345678000199",
  "country": "BR",
  "type": "company",
  "customData": {
    "name": "Acme Brasil Ltda (nome fantasia)",
    "email": "contato@acme.com",
    "phone": "+5511400000000",
    "address": { "fullAddress": "Av. Paulista 1000, São Paulo", "city": "São Paulo" }
  }
}

attributes

object

Opcional - Atributos personalizados como pares chave-valor para a entidade criada.Aplicam-se apenas à entidade principal (a empresa criada), não a acionistas/relacionamentos. Ú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:

{
  "businessSegments": ["retail", "fintech"],
  "source": "onboarding_web",
  "tags": ["vip", "high_volume"]
}

Resposta

success

boolean

Indica se a empresa foi criada com sucesso

data

object

Informações completas sobre a criação:

entity (object) - A empresa criada com todos os dados
summary (object) - Resumo da criação
errors (object, opcional) - Detalhes de quaisquer erros

rulesResult

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.

rulesExecutionSummary

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 Empresa com Todas as Integrações Ativas

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "123.456.789-00",
    "country": "BR",
    "type": "company",
    "isClient": true,
    "autoExecuteIntegrations": {
      "executeAllActiveEnrichments": true,
    }
  }'

Criar Empresa com Integrações Específicas

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "123.456.789-00",
    "country": "BR",
    "type": "company",
    "externalId": "business_12345",
    "autoExecuteIntegrations": {
      "enrichments": ["br_cpfcnpj_complete_company_enrichment"],
    }
  }'

Exemplo de Resposta

{
  "success": true,
  "data": {
    "entity": {
      "id": "company_uuid",
      "organizationId": "org_uuid",
      "type": "company",
      "name": "Tech Solutions LTDA",
      "taxId": "12345678900",
      "countryCode": "BR",
      "status": "under_review",
      "entityData": {
        "company": {
          "legalName": "Tech Solutions LTDA",
          "tradeName": "Tech Solutions",
          "incorporationDate": "2020-01-15",
          "industry": "Technology"
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:00.000Z"
    },
    "summary": {
      "entitiesCreated": 1,
      "relationshipsCreated": 0,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

Respostas de Erro

400 Bad Request - Tax ID Inválido

{
  "success": false,
  "error": "Invalid CPF format for Brazil"
}

404 Not Found - Empresa Não Encontrada no Registro

{
  "success": false,
  "error": "Entity not found in official registry",
  "details": {
    "taxId": "123.456.789-00",
    "country": "BR",
    "registry": "Receita Federal"
  }
}

409 Conflict - Empresa Já Existe

{
  "success": false,
  "error": "Entity with this tax ID already exists",
  "details": {
    "existingEntityId": "uuid",
    "taxId": "123.456.789-00"
  }
}

Melhores Práticas

Tratamento de erros: Sempre verifique o campo success na resposta
Limitação de taxa: Esteja atento aos limites de taxa ao criar múltiplas empresas
Seleção de integração: Escolha integrações específicas para melhor controle sobre custo e desempenho

Próximos Passos

Obter Empresa - Recuperar detalhes da empresa
Criar Empresa Manualmente - Criar empresas com seus próprios dados
Criar Validação KYB - Iniciar verificação de identidade

Criar uma entidade empresa Obter uma empresa por ID

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Corpo da Requisição

​Códigos de Enrichment Obrigatórios por País

​Brasil (BR)

​Argentina (AR)

​Resposta

​Exemplos

​Criar Empresa com Todas as Integrações Ativas

​Criar Empresa com Integrações Específicas

​Exemplo de Resposta

​Respostas de Erro

​400 Bad Request - Tax ID Inválido

​404 Not Found - Empresa Não Encontrada no Registro

​409 Conflict - Empresa Já Existe

​Melhores Práticas

​Próximos Passos

Visão Geral

Endpoint

Autenticação

Corpo da Requisição

Códigos de Enrichment Obrigatórios por País

Brasil (BR)

Argentina (AR)

Resposta

Exemplos

Criar Empresa com Todas as Integrações Ativas

Criar Empresa com Integrações Específicas

Exemplo de Resposta

Respostas de Erro

400 Bad Request - Tax ID Inválido

404 Not Found - Empresa Não Encontrada no Registro

409 Conflict - Empresa Já Existe

Melhores Práticas

Próximos Passos