Criar uma entidade empresa

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>",
  "operationalHours": {},
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "monitoring": {}
}
'

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

POST

entities

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>",
  "operationalHours": {},
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "monitoring": {}
}
'

{
  "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.

operationalHours

object | null

Horário operacional opcional na raiz para regras KYT. Mesma forma que em Criar entidade.

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 | string[]

Um ou mais UUIDs de matrizes de risco (legacy: um único UUID). Se informados, após a criação o sistema avalia a empresa somente contra regras ativas dessas matrizes (salvo skipRulesExecution: true). Mesma semântica que riskMatrixIds quando você envia um único id como string. Veja Execução de Matriz de Risco abaixo.

riskMatrixIds

string[]

Forma preferida para várias matrizes: lista ordenada de UUIDs da sua organização. Quando presente e não vazia, tem precedência sobre riskMatrixId.

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 enriquecimentos ao criar a empresa.Estrutura:

{
  "executeAllActiveEnrichments": false,
  "enrichments": [
    "ar_nosis_extended_verification_enrichment",
    "ar_bcra_deudas_enrichment",
    "global_gueno_sanctions_enrichment"
  ],
  "excludeEnrichments": []
}

Propriedades:

executeAllActiveEnrichments (boolean) - Executar todas as integrações de enriquecimento ativas configuradas na sua organização
enrichments (string[]) - Array de códigos específicos de provedores de enriquecimento para executar

Exemplos de códigos válidos (empresa AR — devem coincidir com as strings de ValidProviderCodesEnum):

ar_nosis_extended_verification_enrichment — enriquecimento NOSIS estendido
ar_bcra_deudas_enrichment — dívidas BCRA
ar_repet_entity_enrichment — REPET / listas (empresa)
global_complyadvantage_sanctions_enrichment — ComplyAdvantage sanções
global_gueno_sanctions_enrichment — sanções Gu1 (quando configurado)

Veja Códigos de provedores e a referência completa em provider-codes.

monitoring

object

Opcional. Igual a Criar entidade: use monitoring.main com global_gueno_sanctions_enrichment: true para watchlist quando esse enriquecimento rodar via autoExecuteIntegrations. Somente esse código é suportado hoje. Exige monitoramento habilitado no Marketplace.

Monitoramento de sanções Gu1 (empresa)

{
  "type": "company",
  "externalId": "co_screening_001",
  "name": "Tech Solutions S.A.",
  "countryCode": "AR",
  "taxId": "30-71000001-2",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "tradeName": "Tech Solutions",
      "industry": "Software"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": true
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": ["global_gueno_sanctions_enrichment"],
  }
}

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 ou mais matrizes de risco (regras de conformidade KYB) ao criar uma empresa fornecendo riskMatrixId ou riskMatrixIds.

Como Funciona

Obtenha seu(s) ID(s) de Matriz de Risco no painel do gu1 (formato: UUID)
Inclua riskMatrixId ou riskMatrixIds na sua requisição de criação
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
    }
  }
}

Exemplo com várias matrizes de risco

{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech"
    }
  }
}

Combinado com Enriquecimentos

{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": [
      "ar_nosis_extended_verification_enrichment",
      "ar_bcra_deudas_enrichment",
      "global_gueno_sanctions_enrichment"
    ]
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    }
  },
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech"
    }
  }
}

Ver Criar entidade — monitoramento.

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:

Obter Detalhes da Empresa - Recuperar informações completas da empresa
Listar Empresas - Consultar suas empresas
Atualizar Empresa - Modificar dados da empresa
Criar Validação KYB - Iniciar processo de verificação KYB

Formatos de Tax ID por País Criar uma empresa automaticamente com enriquecimento

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Corpo da Requisição

​Monitoramento de sanções Gu1 (empresa)

​Estrutura de Dados da Entidade Empresa

​Execução de Matriz de Risco

​Como Funciona

​Exemplo com Matriz de Risco

​Exemplo com várias matrizes de risco

​Combinado com Enriquecimentos

​Resposta

​Exemplo de Requisição

​Exemplo de Resposta

​Respostas de Erro

​400 Bad Request - Tax ID Inválido

​400 Bad Request - Campos Obrigatórios Ausentes

​409 Conflict - Entidade Duplicada

​401 Unauthorized

​Próximos Passos

Visão Geral

Endpoint

Autenticação

Corpo da Requisição

Monitoramento de sanções Gu1 (empresa)

Estrutura de Dados da Entidade Empresa

Execução de Matriz de Risco

Como Funciona

Exemplo com Matriz de Risco

Exemplo com várias matrizes de risco

Combinado com Enriquecimentos

Resposta

Exemplo de Requisição

Exemplo de Resposta

Respostas de Erro

400 Bad Request - Tax ID Inválido

400 Bad Request - Campos Obrigatórios Ausentes

409 Conflict - Entidade Duplicada

401 Unauthorized

Próximos Passos