Visão Geral Este guia de início rápido irá guiá-lo através da criação de sua primeira análise de risco Know Your Business (KYB) usando a API do gu1. Você aprenderá como:
Autenticar-se com a API
Definir um esquema personalizado para seus dados de empresas
Criar uma entidade de empresa
Aplicar regras de risco (pelo dashboard)
Monitorar alertas e investigações
Pré-requisitos : Você precisará de uma conta gu1 e uma API key. Cadastre-se em app.gu1.ai se ainda não o fez.Passo 1: Obtenha sua API Key Primeiro, obtenha sua API key no dashboard do gu1:
Navegue até API Keys
Clique em Configurações → API Keys na barra lateral
Crie uma Nova Key
Clique em Criar API Key , dê um nome (ex. “Integração KYB”) e copie a key
Mantenha sua API key segura! Nunca a compartilhe publicamente nem a adicione ao controle de versão.
Passo 2: Defina seu Esquema de Empresas Informe ao gu1 quais campos de dados você enviará para as empresas:
curl -X POST http://api.gu1.ai/custom-schemas \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Dados KYB Corporativos", "version": "1.0.0", "description": "Informações de empresas para análise KYB", "type": "database", "category": "financial", "schemaData": { "fields": [ { "name": "company_name", "type": "string", "required": true, "description": "Nome legal da empresa" }, { "name": "tax_id", "type": "string", "required": true, "description": "Número de identificação fiscal" }, { "name": "country", "type": "string", "required": true, "description": "País de incorporação" }, { "name": "industry", "type": "string", "required": false, "description": "Setor industrial" }, { "name": "annual_revenue", "type": "number", "required": false, "description": "Receita anual em USD" } ] } }'
{ "success" : true , "schema" : { "id" : "550e8400-e29b-41d4-a716-446655440000" , "name" : "Dados KYB Corporativos" , "version" : "1.0.0" , "organizationId" : "sua-org-id" , "createdAt" : "2025-10-03T12:00:00Z" } } Passo 3: Mapeie Campos para o Modelo do gu1 Crie uma configuração de mapeamento para informar ao gu1 como seus campos se mapeiam para seu modelo unificado de entidades:
curl -X POST http://api.gu1.ai/custom-schemas/mappings \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Mapeamento de Campos KYB", "sourceSchemaId": "550e8400-e29b-41d4-a716-446655440000", "targetSchemaType": "gueno_entity", "mappingData": { "mappings": [ { "id": "1", "sourceField": "company_name", "targetField": "name", "transformation": { "type": "direct" }, "required": true, "dataType": "string" }, { "id": "2", "sourceField": "tax_id", "targetField": "external_id", "transformation": { "type": "direct" }, "required": true, "dataType": "string" }, { "id": "3", "sourceField": "country", "targetField": "country", "transformation": { "type": "direct" }, "required": true, "dataType": "string" } ] } }' Passo 4: Crie uma Entidade de Empresa Agora você pode criar uma entidade de empresa usando o esquema mapeado:
curl -X POST http://api.gu1.ai/entities \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "company", "name": "Acme Corporation", "externalId": "TAX123456789", "country": "US", "entityData": { "industry": "Tecnologia", "annual_revenue": 5000000, "incorporation_date": "2010-01-15", "employees": 50 } }'
{ "success" : true , "entity" : { "id" : "a7c4c07f-a1f5-49d6-8c17-1577d0787a2e" , "type" : "company" , "name" : "Acme Corporation" , "externalId" : "TAX123456789" , "country" : "US" , "riskScore" : 0 , "status" : "active" , "createdAt" : "2025-10-03T12:05:00Z" } } Passo 5: Ver Análise de IA O gu1 gera automaticamente uma análise de risco com IA para a entidade. Consulte-a:
curl -X POST http://api.gu1.ai/ai-analysis/entity/a7c4c07f-a1f5-49d6-8c17-1577d0787a2e \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "language": "pt" }'
{ "success" : true , "analysis" : { "executive_summary" : "Acme Corporation é uma empresa de tecnologia sediada nos EUA com perfil de risco moderado. A empresa demonstra operações estáveis com receita consistente..." , "behavioral_analysis" : "A entidade demonstra padrões de negócios normais sem sinais de alerta no histórico de transações..." , "risk_factors" : [ "Informação pública limitada disponível" , "Operando no setor de tecnologia de alto risco" ], "recommendations" : [ "Solicitar documentação adicional dos beneficiários finais" , "Monitorar mudanças na estrutura da empresa" ], "confidence_score" : 0.85 , "generated_at" : "2025-10-03T12:05:30Z" }, "cached" : false } Passo 6: Aplicar Regras (Dashboard) A configuração de regras é feita através do dashboard do gu1 por segurança e facilidade de uso.
Acesse seu Dashboard do gu1
Navegue até Análise de Risco → Entidades
Encontre “Acme Corporation” e clique para ver detalhes
Vá para a aba Regras e clique em Aplicar Regras
Selecione regras KYB pré-construídas ou crie as suas personalizadas
As regras gerarão automaticamente alertas e investigações com base em limites de risco.
Configure webhooks para receber notificações em tempo real quando alertas ou investigações forem criados:
curl -X POST http://api.gu1.ai/webhooks \ -H "Authorization: Bearer SUA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "url": "https://seu-app.com/webhooks/gueno", "events": [ "investigation.created", "investigation.updated", "alert.created", "entity.risk_score_changed" ], "active": true }' Próximos Passos Precisa de Ajuda? 
