> ## 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 (pessoa ou empresa)
> Crie uma nova pessoa ou empresa com dados personalizados — no modelo universal de entidades gu1 para KYC, KYB e análise de risco, com exemplos para create.
## Visão Geral
Cria uma nova entidade com o tipo e atributos especificados. Entidades representam os objetos de dados principais que você deseja analisar para risco e conformidade.
## 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
O tipo de entidade a ser criada. Tipos disponíveis:
* `person` - Pessoa física/cliente
* `company` - Entidade empresarial
Seu identificador único para esta entidade em seu sistema. **Opcional** — a gu1 atribui um automaticamente se omitido (ver tabela abaixo).
Nome de exibição para a entidade
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). Em uma organização, um `taxId` ativo normalizado pode pertencer a **apenas uma** entidade (`person` ou `company`). Conflitos retornam **`409`** com código **`DUPLICATE_TAX_ID`**.
**Quando `externalId` é omitido**
| Você envia | `externalId` armazenado |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `taxId` (com ou sem formatação) | Tax ID normalizado: **apenas letras e dígitos, maiúsculas** — sem pontos, traços ou espaços. Exemplo: `30-12345678-9` → `30123456789` |
| Sem `taxId` | `{slug-nome}-{timestamp-ms}` derivado de `name` (minúsculas, não alfanumérico → `-`, máx. 20 caracteres). Exemplo: `acme-corp-1719345678901` |
A coluna **`taxId`** continua salva no [formato de exibição do país](/pt/api-reference/entities/tax-id-formats) quando informada. Envie um `externalId` explícito se precisar do seu próprio ID de CRM ou usuário, independente do documento fiscal.
E-mail de contato principal na linha da entidade (opcional, nullable). Entidades existentes permanecem `null` até ser definido. Em PATCH, `null` limpa o campo.
Telefone de contato principal na linha da entidade (opcional, nullable). Entidades existentes permanecem `null` até ser definido. Em PATCH, `null` limpa o campo.
Horário operativo opcional para regras KYT (`outside_entity_operational_hours`). Campo na **raiz** (não em `attributes`).
* `timezone` (obrigatório se `operationalHours` for enviado): valor do enum **transaction\_time\_zone** (mesmo de `transaction.timeZone`). **Lista completa:** [Enum fuso horário](/pt/api-reference/transactions/time-zone-enum).
* `weekly`: chaves `monday` … `sunday`. Cada dia: `{ "start": "09:00", "end": "18:00" }` ou `{ "closed": true }`. Dias omitidos = fechado.
Nacionalidade opcional na raiz: ISO 3166-1 alpha-2 ou um rótulo reconhecido que a API mapeia para ISO2. Se omitido, o campo na raiz pode ser derivado de `entityData.person.nationality` ou `entityData.company.nationality` quando mapeável.
Opcional. Pede que um **enriquecimento com suporte a monitoramento** rode em **modo watchlist** (op 1: screening + inscrição para corridas periódicas), não só consulta pontual (op 0).
**Escopo hoje:** apenas **`global_gueno_sanctions_enrichment`**. A chave do mapa é o **mesmo código** em `autoExecuteIntegrations.enrichments`. Códigos legacy `*_check` **foram removidos (2026-06-04)** e não fazem mais parte do contrato.
* **`main`**: flags da **entidade principal** neste `POST /entities`.
* **`relationships`**: **ignorado** aqui; use [Criar automaticamente](/pt/api-reference/entities/create-automatic) com `depth` > 0.
**Valor por código** (objeto recomendado; `boolean` legacy ainda aceito):
* `{ "watchlist": true }` — inscrição; matriz de monitoramento = herdar `riskMatrixId` da entidade.
* `{ "watchlist": true, "riskMatrixId": "" }` — inscrição; **somente** essa matriz em regras/screening de monitoramento.
* `{ "watchlist": false }` ou `false` — sem watchlist.
* `true` — equivalente a `{ "watchlist": true }`.
**Requisitos** (se faltar algum, o enrichment roda como op 0): (1) código em `enrichments` ou ativo via execute-all; (2) monitoramento ON no **Marketplace** para Gu1 sanções.
Guia: [Monitoramento de sanções Gu1](/es/guias/monitoreo-sanciones-gueno-cliente). Exemplos: [Monitoramento na criação](#exemplo-monitoramento-de-sancoes-gu1-na-criacao).
**Opcional** — Executar integrações (enriquecimentos e checks) logo após criar a entidade.
Propriedades:
* `executeAllActiveEnrichments` (boolean)
* `enrichments` (array de códigos de provedor; ver [códigos de provedor](/pt/api-reference/integrations/provider-codes))
* `enrichmentGroupRefs` (array de strings, opcional) — Slugs de **grupos de enriquecimento** do Marketplace (somente enriquecimentos). Com `executeAllActiveEnrichments: false`, 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.
**Opcional** — Atributos personalizados. Aceita formato **plano** (`{ "phone": "..." }`) ou **aninhado por categoria** (`{ "contact": { "phone": "..." } }`). Armazenados **exatamente como enviados** (objetos aninhados atuam como categorias e são retornados como enviados); ver [Atualizar entidade](/pt/api-reference/entities/update) para detalhes.
**Opcional** - Estrutura de dados específica do tipo. Veja exemplos abaixo para cada tipo de entidade.
**Quando usar entityData?**
* **Opcional para criação básica de entidade** - Você pode criar uma entidade apenas com `type`, `name`, `taxId` e `countryCode`
* **Necessário para enriquecimento e análise de risco** - Se você quiser executar verificações de conformidade, precisará fornecer campos relevantes
* **Pode ser preenchido depois** - Você pode criar uma entidade mínima primeiro, depois atualizá-la com dados completos antes de executar a análise de risco
**Exemplo Mínimo (Person):**
```json theme={null}
{
"type": "person",
"name": "João Silva",
"taxId": "12345678900",
"countryCode": "BR"
// entityData não é necessário para criação básica
}
```
**Exemplo Completo (Person com dados KYC):**
```json theme={null}
{
"type": "person",
"name": "João Silva",
"taxId": "12345678900",
"countryCode": "BR",
"entityData": {
"person": {
"firstName": "João",
"lastName": "Silva",
"dateOfBirth": "1980-01-15",
"email": "joao@example.com",
"phone": "+5511912345678"
}
}
}
```
### Matriz de risco e execução de regras
Um ou mais UUIDs de matrizes de risco (legacy: um único UUID). Se informados, após a criação o sistema avalia a entidade **somente** contra regras ativas dessas matrizes (salvo `skipRulesExecution: true`). Mesma semântica que `riskMatrixIds` quando você envia um único id como 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`.
Pular a execução automática de regras após criar a entidade. Use para criar primeiro e disparar regras manualmente depois.
Apenas entidades **company**: níveis de acionistas a criar automaticamente (0–5). `0` = nenhum (padrão).
Vínculos **declarativos** a entidades **já existentes** na mesma organização (máx. 10). Independente de `shareholderDepth` / enrichment.
Cada item deve incluir **exatamente um** de: `relatedEntityId` (UUID), `relatedTaxId`, `relatedExternalId`.
| Campo | Descrição |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `relationshipType` | Enum do grafo (`shareholder`, `manages`, `owns`, `employed_by`, …) |
| `role` / `roles` | Papel(éis) em `metadata.roles` (ex. `SOCIO`, `REPRESENTANTE`) |
| `relatedCountryCode` | ISO2 opcional para normalizar `relatedTaxId` (padrão: `countryCode` da nova entidade) |
| `asSource` | Padrão `true`: a entidade criada é **source** e a relacionada é **target**. Com `shareholder`, a criada é acionista/sócia da contraparte (ex. pessoa → empresa). `false` inverte a direção. |
Se a contraparte não existir → **404** `RELATED_ENTITY_NOT_FOUND` e a entidade **não** é criada.
## Estruturas de Dados de Entidade
### Entidade Person
```json theme={null}
{
"person": {
"firstName": "string",
"lastName": "string",
"dateOfBirth": "YYYY-MM-DD",
"nationality": "string",
"occupation": "string",
"income": number,
"incomeCurrency": "string",
"address": "string | object (ver nota Formato de endereço)",
"city": "string",
"state": "string",
"country": "string",
"postalCode": "string",
"email": "string",
"gender": "M | F | male | female | unknown | other",
"phone": "string",
"alternativePhone": "string",
"idType": "national_id | passport | drivers_license | tax_id | other",
"idNumber": "string",
"isPep": boolean,
"pepPosition": "string",
"pepCountry": "string"
}
}
```
**Gênero (`entityData.person.gender`)** — enum fechado. Apenas os valores da tabela são aceitos; qualquer outra string (ex.: `X`, `non_binary`) retorna **erro de validação**.
| Valor | Significado |
| --------------- | ----------------------------------------------------------------- |
| `M` ou `male` | Masculino |
| `F` ou `female` | Feminino |
| `other` | Outro / não binário — use este código para identidade não binária |
| `unknown` | Não informado ou desconhecido |
**Argentina (AR):** a derivação automática de CUIL a partir de DNI + gênero e as checagens RENAPER reconhecem somente `M`/`F` (ou `male`/`female`). Com `other` ou `unknown`, o CUIL não é derivado automaticamente e o RENAPER não usa o gênero da entidade.
### Entidade Company
```json theme={null}
{
"company": {
"legalName": "string",
"tradeName": "string",
"incorporationDate": "YYYY-MM-DD",
"industry": "string",
"employeeCount": number,
"revenue": number
}
}
```
### Entidade Alert
```json theme={null}
{
"alert": {
"alertNumber": "string",
"alertType": "RISK | COMPLIANCE | FRAUD | REGULATORY | SYSTEM",
"severity": "INFO | WARNING | HIGH | CRITICAL",
"status": "NEW | ACKNOWLEDGED | INVESTIGATING | RESOLVED | FALSE_POSITIVE",
"sourceSystem": "string",
"triggerRuleId": "string",
"triggerCondition": "string",
"affectedEntityId": "string",
"relatedEntityIds": ["string"],
"alertedAt": "ISO8601 timestamp",
"acknowledgedAt": "ISO8601 timestamp",
"acknowledgedBy": "string",
"resolvedAt": "ISO8601 timestamp",
"resolvedBy": "string",
"resolutionNotes": "string",
"falsePositiveReason": "string"
}
}
```
## Parâmetros de Query
Força o re-enriquecimento da entidade mesmo que já exista no sistema.
**Tipo**: `boolean` (query string: `"true"` ou `"false"`)
**Comportamento**:
* Quando `true`: Força o sistema a buscar dados atualizados de provedores de enriquecimento (ex: verificação de antecedentes, dados KYC, registros de empresas)
* Quando `false` ou omitido: Utiliza dados de enriquecimento em cache se disponíveis
* Sobrescreve a configuração da organização `enrichmentsConfig.reEnrichExistingEntities`
**Casos de Uso**:
* Re-validar dados da entidade após um período de tempo significativo
* Atualizar informações quando se sabe que os dados externos mudaram
* Atualização manual acionada pela equipe de compliance
* Auditorias periódicas de qualidade de dados
**Exemplo**:
```bash theme={null}
POST http://api.gu1.ai/entities?refresh=true
```
**Nota**: O re-enriquecimento pode incorrer em custos adicionais de provedores de dados externos.
## Resposta
Indica se a entidade foi criada com sucesso
O objeto de entidade criado incluindo:
* `id` - ID interno do gu1
* `externalId` - Seu ID externo
* `organizationId` - ID da sua organização
* `type` - Tipo de entidade
* `name` - Nome da entidade
* `riskScore` - Pontuação de risco inicial (0-100)
* `status` - Status da entidade
* `entityData` - Dados específicos do tipo
* `attributes` - Atributos personalizados
* `createdAt` - Data/hora de criação
* `updatedAt` - Data/hora 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.
**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** (array de `{ name?, type?, severity?, description? }`), **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: monitoramento de sanções Gu1 na criação
O parâmetro **`monitoring`** não executa integrações sozinho: só altera **como** roda um enrichment já listado em **`autoExecuteIntegrations`**. Hoje o caso documentado é **`global_gueno_sanctions_enrichment`** (monitoramento da org no Marketplace).
| Condição | Efeito |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Código em `enrichments` + `monitoring.main[código]` com watchlist ativo + monitoramento org ON | **Op 1** — screening + watchlist / screening diário. |
| Sem `monitoring` ou `watchlist: false` | **Op 0** — só consulta pontual. |
| `monitoring` com monitoramento org OFF | **Op 0** — sem erro obrigatório; screening roda. |
| Só `monitoring` sem o código em `enrichments` | Sem efeito. |
Códigos `*_check` (ex.: `global_gueno_sanctions_check`) **foram removidos (2026-06-04)**. Para watchlist na criação, use **`global_gueno_sanctions_enrichment`** em `enrichments` e em `monitoring.main`.
### Só watchlist Gu1 (pessoa)
```json theme={null}
{
"type": "person",
"externalId": "cust_screening_001",
"name": "María González",
"countryCode": "AR",
"taxId": "27-12345678-1",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"nationality": "AR"
}
},
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true
}
}
},
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": ["global_gueno_sanctions_enrichment"]
}
}
```
### Enriquecimentos locais + monitoramento Gu1 (pessoa AR)
```json theme={null}
{
"type": "person",
"name": "María González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15"
}
},
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_renaper_data_enrichment",
"ar_repet_person_enrichment",
"global_gueno_sanctions_enrichment"
]
},
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true
}
}
}
}
```
### Matriz de risco só para monitoramento (opcional)
Além do `riskMatrixId` na entidade (regras na criação), você pode fixar uma matriz **diferente** só para corridas disparadas pelo screening diário de monitoramento:
```json theme={null}
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true,
"riskMatrixId": "660e8400-e29b-41d4-a716-446655440001"
}
}
}
```
`riskMatrixId: null` no objeto equivale a **herdar** a matriz global da entidade nessas corridas de monitoramento.
### Empresa (`type: "company"`)
```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": { "watchlist": true }
}
},
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": ["global_gueno_sanctions_enrichment"]
}
}
```
**`monitoring.relationships`** não é usado em `POST /entities`. Para acionistas/relacionadas no mesmo job, use [Criar automaticamente](/pt/api-reference/entities/create-automatic) com `depth` > 0, `monitoring.relationships` e códigos em `autoExecuteIntegrationsShareholders`.
## Exemplos
### Criar Entidade Person (KYC)
```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": "person",
"externalId": "customer_12345",
"name": "María González",
"countryCode": "AR",
"taxId": "20-12345678-9",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"nationality": "AR",
"occupation": "Software Engineer",
"income": 85000
}
},
"attributes": {
"email": "maria.gonzalez@example.com",
"phone": "+54 11 1234-5678",
"customerSince": "2024-01-15"
}
}'
```
```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: 'person',
externalId: 'customer_12345',
name: 'María González',
countryCode: 'AR',
taxId: '20-12345678-9',
entityData: {
person: {
firstName: 'María',
lastName: 'González',
dateOfBirth: '1985-03-15',
nationality: 'AR',
occupation: 'Software Engineer',
income: 85000
}
},
attributes: {
email: 'maria.gonzalez@example.com',
phone: '+54 11 1234-5678',
customerSince: '2024-01-15'
}
})
});
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': 'person',
'externalId': 'customer_12345',
'name': 'María González',
'countryCode': 'AR',
'taxId': '20-12345678-9',
'entityData': {
'person': {
'firstName': 'María',
'lastName': 'González',
'dateOfBirth': '1985-03-15',
'nationality': 'AR',
'occupation': 'Software Engineer',
'income': 85000
}
},
'attributes': {
'email': 'maria.gonzalez@example.com',
'phone': '+54 11 1234-5678',
'customerSince': '2024-01-15'
}
}
)
entity = response.json()['entity']
print(entity)
```
### Criar Entidade Company (KYB)
```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
}
},
"attributes": {
"website": "https://techsolutions.com.br",
"registeredAddress": "Av. Paulista, 1000, São Paulo",
"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
}
},
attributes: {
website: 'https://techsolutions.com.br',
registeredAddress: 'Av. Paulista, 1000, São Paulo',
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
}
},
'attributes': {
'website': 'https://techsolutions.com.br',
'registeredAddress': 'Av. Paulista, 1000, São Paulo',
'partnershipTier': 'gold'
}
}
)
entity = response.json()['entity']
print(entity)
```
## Exemplo de Resposta
```json theme={null}
{
"success": true,
"entity": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "customer_12345",
"organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
"type": "person",
"name": "María González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskScore": 25,
"status": "active",
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15",
"nationality": "AR",
"occupation": "Software Engineer",
"income": 85000
}
},
"attributes": {
"email": "maria.gonzalez@example.com",
"phone": "+54 11 1234-5678",
"customerSince": "2024-01-15"
},
"createdAt": "2024-10-03T14:30:00.000Z",
"updatedAt": "2024-10-03T14:30:00.000Z"
}
}
```
## Respostas de Erro
### 400 Bad Request - ID Fiscal Inválido
```json theme={null}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Formato de CUIT inválido. Por favor verifique o formato e tente novamente.",
"details": {
"field": "taxId",
"taxIdName": "CUIT",
"providedValue": "20-12345678-9"
}
},
"entity": null
}
```
### 400 Bad Request - Campos Obrigatórios Ausentes
```json theme={null}
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Faltam campos obrigatórios para criação da empresa",
"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": "Entidade com este external_id já existe",
"details": {
"field": "external_id",
"value": "customer_12345",
"constraint": "entities_organization_external_id_unique"
}
},
"entity": null
}
```
Um **tax ID** duplicado (mesma organização, qualquer tipo de entidade) retorna **`DUPLICATE_TAX_ID`** com `existingEntityId` / `existingEntityType` em `details` quando disponíveis.
### 401 Unauthorized
```json theme={null}
{
"error": "Invalid or missing API key",
"code": "INVALID_KEY"
}
```
### 429 Too Many Requests
```json theme={null}
{
"error": "Rate limit exceeded",
"code": "RATE_LIMIT_EXCEEDED",
"message": "Você excedeu o limite de taxa da API. Por favor aguarde antes de fazer mais solicitações.",
"retryAfter": 3600,
"limit": 100,
"remaining": 0,
"resetAt": "2025-01-15T10:00:00Z"
}
```
### 500 Internal Server Error
```json theme={null}
{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Ocorreu um erro inesperado ao criar a entidade",
"details": {
"message": "Database connection timeout"
}
},
"entity": null
}
```
## Próximos Passos
Após criar uma entidade, você pode:
1. [Solicitar Análise de IA](/en/api-reference/entities/analyze) - Obter avaliação automatizada de risco
2. [Listar Entidades](/pt/api-reference/entities/list) - Consultar suas entidades
3. [Obter Detalhes da Entidade](/pt/api-reference/entities/get) - Recuperar informações completas da entidade
4. [Aplicar Regras](/pt/api-reference/rules/execute) - Executar regras de conformidade e risco