Atualizar uma entidade empresa

Atualizar

curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "attributes": {},
  "entityData": {},
  "status": "<string>",
  "reason": "<string>",
  "riskMatrixId": "<string>"
}
'

{
  "entity": {},
  "evaluation": {},
  "previousEntity": {}
}

PATCH

entities

{id}

Atualizar

curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "attributes": {},
  "entityData": {},
  "status": "<string>",
  "reason": "<string>",
  "riskMatrixId": "<string>"
}
'

{
  "entity": {},
  "evaluation": {},
  "previousEntity": {}
}

Visão Geral

Atualiza os atributos e dados de uma empresa existente. Este endpoint aciona automaticamente uma reavaliação da pontuação de risco da empresa e emite eventos de atualização em tempo real.

Endpoint

PATCH http://api.gu1.ai/entities/{id}

Autenticação

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

Authorization: Bearer YOUR_API_KEY

Parâmetros de Caminho

string

required

O ID do gu1 da empresa a atualizar

Corpo da Requisição

Todos os campos são opcionais - inclua apenas os campos que deseja atualizar.

name

string

Atualizar o nome de exibição da empresa

O ID externo não é atualizado neste endpoint. Use Alterar ID externo (POST /entities/change-external-id) com reason obrigatório (mín. 5 caracteres).

taxId

string

Atualizar número de identificação fiscal

countryCode

string

Atualizar código de país ISO 3166-1 alpha-2

attributes

object

Atualizar atributos personalizados (mescla com atributos existentes)

entityData

object

Atualizar dados específicos da empresa (mescla com entityData existente)

status

string

Atualizar status da empresa. Status disponíveis:

pending - Estado inicial, aguardando processamento
under_review - Sob revisão manual
active - Aprovado e ativo
suspended - Temporariamente suspenso (requer reason)
blocked - Permanentemente bloqueado (requer reason)
rejected - Rejeitado durante onboarding (requer reason)

Nota: Mudanças de status para suspended, blocked ou rejected requerem um campo reason para fins de auditoria.

reason

string

Obrigatório ao mudar status para suspended, blocked ou rejected. Fornece trilha de auditoria para mudanças de status.

riskMatrixId

string

UUID da matriz de risco para associar a esta empresa. Atualiza quais regras são usadas para avaliação de risco.

Resposta

entity

object

O objeto de empresa atualizado com todos os valores atuais

evaluation

object

Avaliação recém-criada acionada pela atualização

id - ID da avaliação
entityId - ID da entidade
decision - “PENDING” (aguardando processamento)
evaluationType - “SYSTEM”
reasons - Array com “Re-evaluation triggered by attribute change”

previousEntity

object

O estado da empresa antes da atualização (para auditoria/comparação)

Este endpoint não retorna rulesResult nem rulesExecutionSummary. O motor de regras não é executado na atualização; esses campos são retornados apenas por endpoints que executam regras (criar, criar-automático, enriquecer, refrescar, analisar).

Comportamento

Quando você atualiza uma empresa, o sistema automaticamente:

Registra a mudança no log de eventos da entidade com um snapshot antes/depois
Aciona reavaliação para recalcular a pontuação de risco com base nos novos dados
Emite evento em tempo real para notificar clientes conectados sobre a atualização
Mantém trilha de auditoria para fins de conformidade e revisão

Exemplos

Atualizar Renda e Ocupação da Empresa

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "company": {
        "income": 95000,
        "occupation": "Senior Software Engineer"
      }
    }
  }'

Atualizar Informações de Contato

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "company": {
        "email": "new.email@example.com",
        "phone": "+54 11 9876-5432",
        "address": "Av. Libertador 2500, Buenos Aires"
      }
    }
  }'

Atualizar Apenas Atributos Personalizados

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "accountTier": "premium",
      "loyaltyPoints": 15000,
      "lastLoginDate": "2024-10-03T14:00:00Z"
    }
  }'

Atualizar Status da Empresa

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "suspended",
    "reason": "Suspicious activity detected - pending investigation"
  }'

Exemplo de Resposta

{
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "business_12345",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "company",
    "name": "María González",
    "taxId": "20-12345678-9",
    "countryCode": "AR",
    "riskScore": 22,
    "riskFactors": [...],
    "status": "active",
    "kycVerified": true,
    "entityData": {
      "company": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Senior Software Engineer",
        "income": 95000
      }
    },
    "attributes": {
      "email": "maria.gonzalez@example.com",
      "phone": "+54 11 1234-5678",
      "accountTier": "premium"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T16:45:00.000Z",
    "deletedAt": null
  },
  "evaluation": {
    "id": "eval_new_123",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "decision": "PENDING",
    "evaluationType": "SYSTEM",
    "reasons": ["Re-evaluation triggered by attribute change"],
    "rules": [],
    "entitySnapshot": {...}
  },
  "previousEntity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entityData": {
      "company": {
        "occupation": "Software Engineer",
        "income": 85000
      }
    },
    "updatedAt": "2024-10-03T14:35:00.000Z"
  }
}

Respostas de Erro

404 Not Found

{
  "error": "Entity not found"
}

400 Bad Request - Dados Inválidos

{
  "error": "Validation failed",
  "details": ["Invalid country code format"]
}

400 Bad Request - Motivo Ausente para Mudança de Status

{
  "error": "Changing status to 'suspended' requires a reason for audit purposes."
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Failed to update entity"
}

Casos de Uso

Atualizar Após Verificação KYB

// Após completar a verificação KYB, atualize a empresa
const response = await fetch(`http://api.gu1.ai/entities/${companyId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    attributes: {
      kycVerified: true,
      kycVerificationDate: new Date().toISOString(),
      kycProvider: 'manual_review'
    }
  })
});

Enriquecimento Progressivo de Perfil

# Enriqueça o perfil da empresa à medida que mais informações ficam disponíveis
def update_business_info(company_id, new_data):
    response = requests.patch(
        f'http://api.gu1.ai/entities/{company_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'entityData': {
                'company': new_data
            },
            'attributes': {
                'lastDataUpdate': datetime.now().isoformat(),
                'dataCompleteness': calculate_completeness(new_data)
            }
        }
    )
    return response.json()

Melhores Práticas

Atualizações Parciais: Envie apenas os campos que deseja alterar - não é necessário enviar a empresa inteira
Monitorar Reavaliações: Verifique o ID de avaliação retornado para rastrear o recálculo da pontuação de risco
Trilha de Auditoria: Use o previousEntity na resposta para manter o histórico de mudanças
Sincronização em Tempo Real: Atualizações emitem eventos WebSocket para sincronização de UI em tempo real
Idempotência: Seguro para retentar - atualizações com os mesmos dados não criarão eventos duplicados

Próximos Passos

Obter Empresa - Visualizar detalhes da empresa atualizada
Listar Empresas - Consultar empresas com filtros
Upsert Empresa - Criar ou atualizar em uma operação

Listar empresas Atualizar uma empresa por ID externo

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Caminho

​Corpo da Requisição

​Resposta

​Comportamento

​Exemplos

​Atualizar Renda e Ocupação da Empresa

​Atualizar Informações de Contato

​Atualizar Apenas Atributos Personalizados

​Atualizar Status da Empresa

​Exemplo de Resposta

​Respostas de Erro

​404 Not Found

​400 Bad Request - Dados Inválidos

​400 Bad Request - Motivo Ausente para Mudança de Status

​401 Unauthorized

​500 Internal Server Error

​Casos de Uso

​Atualizar Após Verificação KYB

​Enriquecimento Progressivo de Perfil

​Melhores Práticas

​Próximos Passos

Visão Geral

Endpoint

Autenticação

Parâmetros de Caminho

Corpo da Requisição

Resposta

Comportamento

Exemplos

Atualizar Renda e Ocupação da Empresa

Atualizar Informações de Contato

Atualizar Apenas Atributos Personalizados

Atualizar Status da Empresa

Exemplo de Resposta

Respostas de Erro

404 Not Found

400 Bad Request - Dados Inválidos

400 Bad Request - Motivo Ausente para Mudança de Status

401 Unauthorized

500 Internal Server Error

Casos de Uso

Atualizar Após Verificação KYB

Enriquecimento Progressivo de Perfil

Melhores Práticas

Próximos Passos