> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar uma entidade empresa
> Criar uma nova empresa com dados personalizados — para entidades de empresa na plataforma de risco e compliance gu1, com exemplos para create.
## 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:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Corpo da Requisição
Deve ser `company` para criar uma entidade de empresa
Seu identificador único para esta empresa no seu sistema
Nome de exibição para a empresa
Código de país ISO 3166-1 alpha-2 (ex: "US", "BR", "AR")
Número de identificação fiscal (validado com base no país)
📋 Ver [Formatos de Tax ID por País](/pt/api-reference/entities/tax-id-formats) para formatos aceitos e regras de validação para cada país.
Horário operacional opcional na **raiz** para regras KYT. Mesma forma que em [Criar entidade](/pt/api-reference/entities/create).
Atributos personalizados como pares chave-valor
Estrutura de dados específica da empresa (veja abaixo)
Data de registro da empresa em formato ISO 8601 datetime (ex: "2024-01-15T10:30:00Z")
Marcar esta empresa como cliente/consumidor para fins de rastreamento
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](#execução-de-matriz-de-risco) abaixo.
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`.
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 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
Configurar execução automática de enriquecimentos ao criar a empresa.
**Estrutura:**
```json theme={null}
{
"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](/pt/api-reference/integrations/company-provider-codes) e a referência completa em [provider-codes](/pt/api-reference/integrations/provider-codes).
Opcional. Igual a [Criar entidade](/pt/api-reference/entities/create): 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)
```json theme={null}
{
"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:
```json theme={null}
{
"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):
```json theme={null}
{
"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
1. **Obtenha seu(s) ID(s) de Matriz de Risco** no painel do gu1 (formato: UUID)
2. **Inclua `riskMatrixId` ou `riskMatrixIds` 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
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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](/pt/api-reference/entities/create#exemplo-monitoramento-de-sancoes-gu1-ao-criar).
***
## Resposta
Indica se a empresa foi criada com sucesso
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
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.
**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
```bash cURL theme={null}
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"
}
}'
```
```javascript JavaScript theme={null}
const response = await fetch('http://api.gu1.ai/entities', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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'
}
})
});
const data = await response.json();
console.log(data.entity);
```
```python Python theme={null}
import requests
response = requests.post(
'http://api.gu1.ai/entities',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'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'
}
}
)
entity = response.json()['entity']
print(entity)
```
## Exemplo de Resposta
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"error": "Invalid or missing API key",
"code": "INVALID_KEY"
}
```
## Próximos Passos
Após criar uma empresa, você pode:
1. [Obter Detalhes da Empresa](/pt/api-reference/company/get) - Recuperar informações completas da empresa
2. [Listar Empresas](/pt/api-reference/company/list) - Consultar suas empresas
3. [Atualizar Empresa](/pt/api-reference/company/update) - Modificar dados da empresa
4. [Criar Validação KYB](/pt/use-cases/kyb/overview) - Iniciar processo de verificação KYB