Skip to main content
POST
/
entities
Criar
curl --request POST \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "externalId": "<string>",
  "name": "<string>",
  "countryCode": "<string>",
  "taxId": "<string>",
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": "<string>",
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {}
}
'
{
  "success": true,
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

​
Visão Geral

Cria uma nova entidade de empresa com os atributos especificados. As entidades de empresa representam organizações empresariais que você deseja analisar para risco e conformidade (KYB).

​
Endpoint

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

​
Autenticação

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

​
Corpo da Requisição

​
type
string
required
Deve ser company para criar uma entidade de empresa
​
externalId
string
required
Seu identificador único para esta empresa no seu sistema
​
name
string
required
Nome de exibição para a empresa
​
countryCode
string
required
Código de país ISO 3166-1 alpha-2 (ex: “US”, “BR”, “AR”)
​
taxId
string
Número de identificação fiscal (validado com base no país)
📋 Ver Formatos de Tax ID por País para formatos aceitos e regras de validação para cada país.
​
attributes
object
Atributos personalizados como pares chave-valor
​
entityData
object
required
Estrutura de dados específica da empresa (veja abaixo)
​
registrationDate
string
Data de registro da empresa em formato ISO 8601 datetime (ex: “2024-01-15T10:30:00Z”)
​
isClient
boolean
default:"false"
Marcar esta empresa como cliente/consumidor para fins de rastreamento
​
riskMatrixId
string
UUID da matriz de risco para executar regras automaticamente. Veja a seção Execução de Matriz de Risco abaixo para mais detalhes.
​
skipRulesExecution
boolean
default:"false"
Pular execução automática de regras após criação da empresa. Use isso para criar a entidade primeiro e acionar as regras manualmente depois.
​
status
string
default:"under_review"
Status inicial para a empresa. Opções:
  • active - Empresa está ativa
  • inactive - Empresa está inativa
  • blocked - Empresa está bloqueada
  • under_review - Empresa está em revisão (padrão)
  • suspended - Empresa está suspensa
  • expired - Registro da empresa expirou
  • deleted - Excluída de forma reversível
  • rejected - Empresa foi rejeitada
​
autoExecuteIntegrations
object
Configurar execução automática de integrações (enriquecimentos e verificações) ao criar a empresa.Estrutura:
{
  "executeAllActiveEnrichments": false,
  "executeAllActiveChecks": false,
  "enrichments": ["NOSIS", "REPET"],
  "checks": ["COMPLY_ADVANTAGE", "WORLDCHECK"]
}
Propriedades:
  • executeAllActiveEnrichments (boolean) - Executar todas as integrações de enriquecimento ativas configuradas na sua organização
  • executeAllActiveChecks (boolean) - Executar todas as integrações de verificação ativas configuradas na sua organização
  • enrichments (string[]) - Array de códigos específicos de provedores de enriquecimento para executar
  • checks (string[]) - Array de códigos específicos de provedores de verificação para executar
Códigos de Provedores Comuns:
  • NOSIS - NOSIS Argentina (enriquecimento de dados de empresas)
  • REPET - REPET Argentina (triagem de listas de vigilância)
  • COMPLY_ADVANTAGE - ComplyAdvantage (triagem de sanções e PEP)
  • WORLDCHECK - Refinitiv World-Check (triagem de conformidade)
Veja Referência de Códigos de Provedores para lista completa.

​
Estrutura de Dados da Entidade Empresa

O objeto entityData.company deve conter: 
{
  "company": {
    "legalName": "string",
    "tradeName": "string",
    "incorporationDate": "YYYY-MM-DD",
    "companySubtype": "merchant | investment_fund | holding | bank | payment_processor | other",
    "industry": "string",
    "websiteUrl": "string",
    "employeeCount": number,
    "revenue": number,
    "revenueCurrency": "string",
    "contactInfo": {
      "email": "string",
      "phone": "string",
      "alternativePhone": "string"
    },
    "address": "string | object (veja nota sobre Formato de Endereço)",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string"
  }
}
Formato de Endereço: O campo address suporta ambos os formatos:
  • Formato string (simples): "Av. Paulista, 1000, São Paulo, SP, Brazil"
  • Formato objeto (estruturado): 
    {
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Suite 200",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "Brazil",
  "postalCode": "01310-100"
}

​
Execução de Matriz de Risco

Você pode executar automaticamente uma matriz de risco (regras de conformidade KYB) ao criar uma empresa fornecendo o parâmetro riskMatrixId.

​
Como Funciona

  1. Obtenha seu ID de Matriz de Risco no painel do gu1 (formato: UUID)
  2. Inclua riskMatrixId na sua requisição de criação
  3. O sistema automaticamente:
    • Cria a entidade empresa
    • Executa todas as regras KYB na matriz
    • Calcula a pontuação de risco
    • Gera alertas de conformidade se necessário
    • Atualiza o status da empresa com base nos resultados

​
Exemplo com Matriz de Risco

{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech",
      "revenue": 5000000
    }
  }
}

​
Combinado com Enriquecimentos

Para melhores resultados, combine a execução de matriz com enriquecimentos automáticos: 
{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "enrichments": ["NOSIS", "REPET"],
    "checks": ["COMPLY_ADVANTAGE"]
  },
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech"
    }
  }
}
Fluxo de Execução:
  1. Entidade empresa criada
  2. Enriquecimento NOSIS busca dados oficiais da empresa
  3. REPET verifica listas de vigilância
  4. ComplyAdvantage verifica sanções
  5. Regras da matriz de risco avaliam todos os dados coletados
  6. Pontuação de risco final calculada
  7. Alertas de conformidade gerados se as regras forem acionadas

​
Resposta

​
success
boolean
Indica se a empresa foi criada com sucesso
​
entity
object
O objeto de empresa criado incluindo:
  • id - ID interno do gu1
  • externalId - Seu ID externo
  • organizationId - ID da sua organização
  • type - Sempre “company”
  • name - Nome da empresa
  • riskScore - Pontuação de risco inicial (0-100)
  • status - Status da empresa
  • entityData - Dados específicos da empresa
  • attributes - Atributos personalizados
  • createdAt - Timestamp de criação
  • updatedAt - Timestamp da última atualização
​
rulesResult
object
Resultado da execução de regras (apenas presente quando as regras foram executadas, ex. quando skipRulesExecution é false e há matriz de risco configurada), incluindo:
  • 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). 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.
  • 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.

​
Exemplo de Requisição

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "externalId": "company_789",
    "name": "Tech Solutions S.A.",
    "countryCode": "BR",
    "taxId": "12.345.678/0001-90",
    "entityData": {
      "company": {
        "legalName": "Tech Solutions Sociedade Anônima",
        "tradeName": "Tech Solutions",
        "incorporationDate": "2020-06-15",
        "industry": "Software Development",
        "employeeCount": 50,
        "revenue": 5000000,
        "revenueCurrency": "BRL",
        "contactInfo": {
          "email": "contact@techsolutions.com.br",
          "phone": "+55 11 3456-7890"
        },
        "address": "Av. Paulista, 1000",
        "city": "São Paulo",
        "state": "SP",
        "country": "Brazil",
        "postalCode": "01310-100"
      }
    },
    "attributes": {
      "website": "https://techsolutions.com.br",
      "partnershipTier": "gold"
    }
  }'

​
Exemplo de Resposta

{
  "success": true,
  "entity": {
    "id": "660e9511-f39c-52e5-b827-557766551111",
    "externalId": "company_789",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "company",
    "name": "Tech Solutions S.A.",
    "taxId": "12.345.678/0001-90",
    "countryCode": "BR",
    "riskScore": 35,
    "status": "active",
    "entityData": {
      "company": {
        "legalName": "Tech Solutions Sociedade Anônima",
        "tradeName": "Tech Solutions",
        "incorporationDate": "2020-06-15",
        "industry": "Software Development",
        "employeeCount": 50,
        "revenue": 5000000,
        "revenueCurrency": "BRL"
      }
    },
    "attributes": {
      "website": "https://techsolutions.com.br",
      "partnershipTier": "gold"
    },
    "createdAt": "2024-10-03T15:00:00.000Z",
    "updatedAt": "2024-10-03T15:00:00.000Z"
  }
}

​
Respostas de Erro

​
400 Bad Request - Tax ID Inválido

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid CNPJ format. Please check the format and try again.",
    "details": {
      "field": "taxId",
      "taxIdName": "CNPJ",
      "providedValue": "12.345.678/0001-90"
    }
  },
  "entity": null
}

​
400 Bad Request - Campos Obrigatórios Ausentes

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields for company creation",
    "details": {
      "missingFields": ["legalName", "industry"],
      "requiredFields": ["legalName", "tradeName", "industry", "incorporationDate"],
      "countryCode": "BR"
    }
  },
  "entity": null
}

​
409 Conflict - Entidade Duplicada

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Entity with this external_id already exists",
    "details": {
      "field": "external_id",
      "value": "company_789",
      "constraint": "entities_organization_external_id_unique"
    }
  },
  "entity": null
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "INVALID_KEY"
}

​
Próximos Passos

Após criar uma empresa, você pode:
  1. Obter Detalhes da Empresa - Recuperar informações completas da empresa
  2. Listar Empresas - Consultar suas empresas
  3. Atualizar Empresa - Modificar dados da empresa
  4. Criar Validação KYB - Iniciar processo de verificação KYB