Skip to main content
POST
http://api.gu1.ai
/
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": {}
}

​
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
  • pending_verification - Verificação pendente
  • 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

​
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