Skip to main content
POST
/
entities
Crear
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>",
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": "<string>",
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "monitoring": {}
}
'
{
  "success": true,
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

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.

​
Descripción general

Crea una nueva entidad de empresa con los atributos especificados. Las entidades de empresa representan organizaciones comerciales que deseas analizar en términos de riesgo y cumplimiento (KYB).

​
Endpoint

POST http://api.gu1.ai/entities

​
Autenticación

Requiere una clave API válida en el encabezado Authorization: 
Authorization: Bearer YOUR_API_KEY

​
Cuerpo de la solicitud

​
type
string
required
Debe ser company para crear una entidad de empresa
​
externalId
string
required
Tu identificador único para esta empresa en tu sistema
​
name
string
required
Nombre para mostrar de la empresa
​
countryCode
string
required
Código de país ISO 3166-1 alpha-2 (ej., “US”, “BR”, “AR”)
​
taxId
string
Número de identificación fiscal (validado según el país)
📋 Ver Formatos de Tax ID por País para formatos aceptados y reglas de validación para cada país.
​
attributes
object
Atributos personalizados como pares clave-valor
​
entityData
object
required
Estructura de datos específica de la empresa (ver abajo)
​
registrationDate
string
Fecha de registro de la empresa en formato ISO 8601 datetime (ej., “2024-01-15T10:30:00Z”)
​
isClient
boolean
default:"false"
Marcar esta empresa como cliente para fines de seguimiento
​
riskMatrixId
string
UUID de la matriz de riesgo para ejecutar reglas automáticamente. Ver sección Ejecución de Matriz de Riesgo abajo para más detalles.
​
skipRulesExecution
boolean
default:"false"
Omitir la ejecución automática de reglas después de la creación de la empresa. Use esto para crear la entidad primero y activar las reglas manualmente más tarde.
​
status
string
default:"under_review"
Estado inicial de la empresa. Opciones:
  • active - Empresa activa
  • inactive - Empresa inactiva
  • blocked - Empresa bloqueada
  • under_review - Empresa bajo revisión (predeterminado)
  • suspended - Empresa suspendida
  • expired - Registro de empresa expirado
  • deleted - Eliminación lógica
  • rejected - Empresa rechazada
​
autoExecuteIntegrations
object
Configurar la ejecución automática de integraciones (enriquecimientos y verificaciones) al crear la empresa.Estructura:
{
  "executeAllActiveEnrichments": false,
  "executeAllActiveChecks": false,
  "enrichments": [
    "ar_nosis_extended_verification_enrichment",
    "ar_bcra_deudas_enrichment"
  ],
  "checks": [
    "ar_nosis_basic_verification_check",
    "ar_repet_entity_check",
    "global_complyadvantage_sanctions_check"
  ]
}
Propiedades:
  • executeAllActiveEnrichments (boolean) - Ejecutar todas las integraciones de enriquecimiento activas configuradas en su organización
  • executeAllActiveChecks (boolean) - Ejecutar todas las integraciones de verificación activas configuradas en su organización
  • enrichments (string[]) - Array de códigos específicos de proveedores de enriquecimiento a ejecutar
  • checks (string[]) - Array de códigos específicos de proveedores de verificación a ejecutar
Ejemplos de códigos válidos (empresa AR — deben coincidir con los valores string de ValidProviderCodesEnum):
  • ar_nosis_extended_verification_enrichment — enriquecimiento NOSIS extendido
  • ar_bcra_deudas_enrichment — deudas BCRA
  • ar_nosis_basic_verification_check — verificación básica NOSIS
  • ar_repet_entity_check — REPET / listas (empresa)
  • global_complyadvantage_sanctions_check — ComplyAdvantage sanciones
  • global_gueno_sanctions_check — sanciones Güeno (si está configurado)
Ver Códigos de proveedores y la referencia completa en provider-codes.
​
monitoring
object
Opcional. Igual que en Crear entidad: usá monitoring.main con global_gueno_sanctions_enrichment: true para lista vigilada cuando ese enriquecimiento corre desde autoExecuteIntegrations. Solo está soportado ese código hoy. Requiere monitoreo habilitado en Marketplace. Ejemplos: Crear entidad — ejemplo Gueno.

​
Monitoreo de sanciones Gueno (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,
    "executeAllActiveChecks": false,
    "enrichments": ["global_gueno_sanctions_enrichment"],
    "checks": []
  }
}

​
Estructura de datos de la entidad empresa

El objeto entityData.company debe contener: 
{
  "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 (ver nota de Formato de dirección)",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string"
  }
}
Formato de dirección: El campo address admite ambos formatos:
  • Formato de cadena (simple): "Av. Paulista, 1000, São Paulo, SP, Brazil"
  • Formato de objeto (estructurado): 
    {
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Suite 200",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "Brazil",
  "postalCode": "01310-100"
}

​
Ejecución de Matriz de Riesgo

Puede ejecutar automáticamente una matriz de riesgo (reglas de cumplimiento KYB) al crear una empresa proporcionando el parámetro riskMatrixId.

​
Cómo funciona

  1. Obtenga su ID de Matriz de Riesgo desde el panel de gu1 (formato: UUID)
  2. Incluya riskMatrixId en su solicitud de creación
  3. El sistema automáticamente:
    • Crea la entidad empresa
    • Ejecuta todas las reglas KYB en la matriz
    • Calcula el puntaje de riesgo
    • Genera alertas de cumplimiento si es necesario
    • Actualiza el estado de la empresa según los resultados

​
Ejemplo con Matriz de Riesgo

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

​
Combinado con Enriquecimientos

Para mejores resultados, combine la ejecución de matriz con enriquecimientos automáticos: 
{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "enrichments": [
      "ar_nosis_extended_verification_enrichment",
      "ar_bcra_deudas_enrichment"
    ],
    "checks": [
      "ar_repet_entity_check",
      "global_complyadvantage_sanctions_check"
    ]
  },
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech"
    }
  }
}
Flujo de Ejecución:
  1. Se crea la entidad empresa
  2. Se ejecutan los enriquecimientos indicados (p. ej. ar_nosis_extended_verification_enrichment, ar_bcra_deudas_enrichment)
  3. Se ejecutan los checks indicados (p. ej. ar_repet_entity_check, global_complyadvantage_sanctions_check)
  4. Las reglas de la matriz de riesgo evalúan los datos recopilados
  5. Se calcula el puntaje de riesgo final
  6. Se generan alertas de cumplimiento si las reglas se activan

​
Respuesta

​
success
boolean
Indica si la empresa se creó exitosamente
​
entity
object
El objeto de empresa creado incluyendo:
  • id - ID interno de gu1
  • externalId - Tu ID externo
  • organizationId - ID de tu organización
  • type - Siempre “company”
  • name - Nombre de la empresa
  • riskScore - Puntuación de riesgo inicial (0-100)
  • status - Estado de la empresa
  • entityData - Datos específicos de la empresa
  • attributes - Atributos personalizados
  • createdAt - Marca de tiempo de creación
  • updatedAt - Marca de tiempo de última actualización
​
rulesResult
object
Resultado de la ejecución de reglas (solo presente cuando se ejecutaron reglas, p. ej. cuando skipRulesExecution es false y hay matriz de riesgo configurada), incluyendo:
  • success (boolean) - Si las reglas se ejecutaron correctamente
  • rulesTriggered (number) - Número de reglas disparadas
  • alerts (array) - Alertas generadas por las reglas
  • riskScore (number) - Puntuación de riesgo final
  • decision (string) - Decisión final (APPROVE, REJECT, HOLD, REVIEW_REQUIRED)
  • rulesExecutionSummary (object) - Presente cuando se ejecutaron reglas. Ver abajo la estructura.
​
rulesExecutionSummary
object
En la raíz de la respuesta (igual que la API de transacciones). Mismo valor que rulesResult.rulesExecutionSummary. Solo presente cuando se ejecutaron reglas (p. ej. skipRulesExecution es false). Resumen de qué reglas hicieron match (hit) vs no (no hit), acciones ejecutadas y puntuación total. Omitido cuando las reglas no se ejecutaron.
  • rulesHit (array) - Reglas cuyas condiciones se cumplieron. Cada ítem: name, description, score, priority, category, status (p. ej. active, shadow), conditions (array de { field, value, operator? }), actions (alerts, suggestion, status, assignedUser).
  • rulesNoHit (array) - Reglas evaluadas pero cuyas condiciones no se cumplieron. Misma estructura que rulesHit (incluye acciones configuradas, no ejecutadas).
  • actionsExecuted (object) - Acciones ejecutadas agregadas de todas las reglas que hicieron hit: alerts, suggestion (BLOCK | SUSPEND | FLAG, mayor peso), status (estado aplicado a la entidad, si hay), assignedUser ({ userId }, si hay), customKeys (array de strings, opcional) — claves de acciones personalizadas de las reglas que hicieron match; para integraciones/workflows.
  • totalScore (number) - Suma del score de todas las reglas que hicieron hit y no están en estado shadow.

​
Ejemplo de solicitud

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"
    }
  }'

​
Ejemplo de respuesta

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

​
Respuestas de error

​
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 requeridos faltantes

{
  "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 - Entidad 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 pasos

Después de crear una empresa, puedes:
  1. Obtener detalles de empresa - Recuperar información completa de la empresa
  2. Listar empresas - Consultar tus empresas
  3. Actualizar empresa - Modificar datos de la empresa
  4. Crear validación KYB - Iniciar proceso de verificación KYB