Skip to main content
POST
Criar uma empresa automaticamente com enriquecimento

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

Autenticação

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

Corpo da Requisição

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.
string
required
Código de país ISO 3166-1 alpha-2 (ex: “BR”, “MX”, “AR”, “CL”)
string
required
Deve ser definido como company
string
Seu identificador único para esta empresa (opcional, será gerado automaticamente se não fornecido)
boolean
default:"false"
Marcar esta empresa como cliente/negócio 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 execução automática de regras após criação da empresa
string
default:"under_review"
Status inicial para a empresa
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 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)
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.
Exemplo:
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.
Exemplo:

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)

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)

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.
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, addressentityData.company.address (birthDate não se aplica a empresas).Exemplo:
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:

Resposta

boolean
Indica se a empresa foi criada com sucesso
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
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 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

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

Próximos Passos