Skip to main content
POST
/
entities
/
automatic
Crear una empresa automáticamente con enriquecimiento
curl --request POST \
  --url http://api.gu1.ai/entities/automatic \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taxId": "<string>",
  "country": "<string>",
  "type": "<string>",
  "externalId": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'
{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

​
Descripción general

El endpoint de creación automática de empresas te permite crear empresas proporcionando información mínima (Tax ID y país). El sistema automáticamente:
  • Obtiene datos de la empresa de registros oficiales
  • Enriquece la empresa con información adicional
  • Ejecuta enriquecimientos automáticamente
Esto es ideal para procesos KYB (Know Your Business) donde deseas incorporar negocios con información completa automáticamente.

​
Endpoint

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

​
Autenticación

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

​
Cuerpo de la solicitud

​
taxId
string
required
Número de identificación fiscal de la empresa (ej., CNPJ para Brasil, RFC para México, CUIT para Argentina)
📋 Ver Formatos de Tax ID por País para formatos aceptados y reglas de validación para cada país.
​
country
string
required
Código de país ISO 3166-1 alpha-2 (ej., “BR”, “MX”, “AR”, “CL”)
​
type
string
required
Debe establecerse como company
​
externalId
string
Tu identificador único para esta empresa (opcional, se generará automáticamente si no se proporciona)
​
isClient
boolean
default:"false"
Marcar esta empresa como cliente/negocio para fines de seguimiento
​
riskMatrixId
string | string[]
Uno o más UUIDs de matrices de riesgo (legacy: un solo UUID). Tras la creación se ejecutan reglas activas de esas matrices (salvo skipRulesExecution: true).
​
riskMatrixIds
string[]
Preferido para varias matrices: lista ordenada de UUIDs. Tiene precedencia sobre riskMatrixId cuando viene informada y no vacía.
​
skipRulesExecution
boolean
default:"false"
Omitir la ejecución automática de reglas después de la creación de la empresa
​
status
string
default:"under_review"
Estado inicial de la empresa
​
operationalHours
object | null
Horario operativo opcional de la entidad principal (timezone + weekly). Se persiste en creación automática igual que en creación manual de entidades. No se aplica a accionistas/relaciones creadas por depth.
​
depth
number
default:"0"
Profundidad de extracción de relaciones (0-5). Controla cuántos niveles de accionistas/relaciones obtener y crear automáticamente.
  • 0: Sin relaciones (solo entidad principal)
  • 1: Solo accionistas directos
  • 2: Accionistas + sus accionistas
  • 3-5: Niveles adicionales (usar con precaución - puede crear muchas entidades)
​
autoExecuteIntegrations
object
Configurar la ejecución automática de integraciones para la entidad principal de la empresa. Ver Referencia de códigos de proveedores para códigos disponibles.Tipo: object (opcional)Propiedades:
  • executeAllActiveEnrichments (boolean, opcional, predeterminado: false) - Ejecutar todas las integraciones de enriquecimiento activas
  • enrichments (array, opcional, predeterminado: []) - Array de códigos específicos de proveedores de enriquecimiento a ejecutar
  • enrichmentGroupRefs (array de strings, opcional) - Slugs de grupos de enriquecimiento del Marketplace (solo enriquecimientos). Con executeAllActiveEnrichments: false, se resuelven los grupos y se fusionan con enrichments explícitos. Con executeAllActiveEnrichments: true, los refs de grupo no se usan; los enrichments explícitos pueden seguir añadiendo códigos tras el conjunto activo.
{
  executeAllActiveEnrichments?: boolean; // predeterminado: false
  enrichments?: ValidProviderCodesEnum[]; // predeterminado: []
  enrichmentGroupRefs?: string[];
}
Ejemplo:
{
  "executeAllActiveEnrichments": false,
  "enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
  "enrichmentGroupRefs": ["my_marketplace_group_slug"],
}
​
autoExecuteIntegrationsShareholders
object
Configurar la ejecución automática de integraciones para accionistas/relaciones descubiertos. Útil cuando se usa depth > 0. Ver Referencia de códigos de proveedores para códigos disponibles.Tipo: object (opcional)Propiedades:
  • executeAllActiveEnrichments (boolean, opcional, predeterminado: false) - Ejecutar todos los enriquecimientos activos en accionistas
  • enrichments (object, opcional) - Enriquecimientos específicos por tipo de entidad
    • company (array, predeterminado: []) - Enriquecimientos para accionistas empresa
    • person (array, predeterminado: []) - Enriquecimientos para accionistas persona
  • enrichmentGroupRefs (array de strings, opcional) - Mismos slugs que en el objeto principal; con executeAllActiveEnrichments: false se aplican tanto a company como a person. Con executeAllActiveEnrichments: true en este objeto, los refs de grupo no se usan; los enrichments explícitos por tipo pueden seguir añadiendo códigos tras el activo de cada lado.
{
  executeAllActiveEnrichments?: boolean;
  enrichments?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
  enrichmentGroupRefs?: string[];
}
Ejemplo:
{
  "enrichments": {
    "person": [
      "br_cpfcnpj_complete_person_enrichment",
      "global_complyadvantage_person_search_enrichment"
    ],
    "company": ["br_cpfcnpj_complete_company_enrichment"]
  },
  "enrichmentGroupRefs": ["shareholder_pipeline_group_slug"]
}

​
Códigos de Enrichment Obligatorios por País

Al usar códigos de enrichment específicos (no executeAllActiveEnrichments: true), ciertos enrichments son obligatorios para que la creación automática funcione. Sin ellos, el sistema no puede obtener los datos básicos de la empresa de los registros oficiales y la solicitud fallará.

​
Brasil (BR)

EscenarioCódigo(s) de Enrichment Obligatorio(s)Descripción
Entidad principalbr_cpfcnpj_complete_company_enrichmentObtiene datos de la empresa de CNPJ/Receita Federal (razón social, nombre comercial, dirección, industria, etc.)
Accionistas (depth > 0)br_bdc_shareholders_enrichmentObligatorio en autoExecuteIntegrations.enrichments. Obtiene el QSA (Quadro Societário) para descubrir accionistas y directores
El enrichment de accionistas debe incluirse en el array autoExecuteIntegrations.enrichments de la entidad principal (no en autoExecuteIntegrationsShareholders), porque el sistema necesita ejecutarlo sobre la empresa principal para descubrir el QSA. El campo autoExecuteIntegrationsShareholders controla qué enrichments ejecutar sobre cada accionista después de ser creado.

​
Argentina (AR)

EscenarioCódigo de Enrichment ObligatorioDescripción
Entidad principalar_nosis_extended_verification_enrichmentObtiene datos de la empresa de Nosis (razón social, estado CUIT, dirección, actividades, etc.)
Argentina no soporta la creación automática de accionistas aún. El parámetro depth debe ser 0. Si se proporciona depth > 0, la solicitud fallará con un error.
​
customData
object
Opcional — Datos del cliente para la empresa principal que no deben ser reemplazados por enrichments. Detalle completo: Creación automática de entidades.Campos: name, email, phone, address → entityData.company.address (birthDate no aplica a empresas).Ejemplo:
{
  "taxId": "30712345678",
  "country": "AR",
  "type": "company",
  "customData": {
    "name": "Acme Argentina S.A. (nombre comercial)",
    "email": "contacto@acme.com",
    "phone": "+541140000000",
    "address": { "fullAddress": "Av. del Libertador 100, CABA", "city": "Buenos Aires" }
  }
}
​
attributes
object
Opcional - Atributos personalizados como pares clave-valor para la entidad creada.Se aplican solo a la entidad principal (la empresa creada), no a accionistas/relaciones. Útil para segmentos de negocio, etiquetas, IDs internos o cualquier metadato que quieras asociar desde el momento de la creación.Estructura: objeto con claves string y valores de cualquier tipo (string, number, boolean, array, etc.).Ejemplo:
{
  "businessSegments": ["retail", "fintech"],
  "source": "onboarding_web",
  "tags": ["vip", "high_volume"]
}

​
Respuesta

​
success
boolean
Indica si la empresa se creó exitosamente
​
data
object
Información completa sobre la creación:
  • entity (object) - La empresa creada con todos los datos
  • summary (object) - Resumen de creación
  • errors (object, opcional) - Detalles de cualquier error
​
rulesResult
object
Resultado de la ejecución de reglas (solo presente cuando se ejecutaron reglas, p. ej. cuando skipRulesExecution es false y hay matriz configurada vía riskMatrixId o riskMatrixIds), o null. Cuando está presente, incluye:
  • 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 y se ejecutó la matriz de riesgo). Resumen de qué reglas hicieron match (hit) vs no (no hit), acciones ejecutadas y puntuación total. Omitido cuando las reglas no se ejecutaron. Estructura completa y ejemplo: Resumen de Ejecución de Reglas.
  • 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.

​
Ejemplos

​
Crear empresa con todas las integraciones activas

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "123.456.789-00",
    "country": "BR",
    "type": "company",
    "isClient": true,
    "autoExecuteIntegrations": {
      "executeAllActiveEnrichments": true
    }
  }'

​
Crear empresa con integraciones específicas

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "123.456.789-00",
    "country": "BR",
    "type": "company",
    "externalId": "business_12345",
    "autoExecuteIntegrations": {
      "enrichments": ["br_cpfcnpj_complete_company_enrichment"],
    }
  }'

​
Ejemplo de respuesta

{
  "success": true,
  "data": {
    "entity": {
      "id": "company_uuid",
      "organizationId": "org_uuid",
      "type": "company",
      "name": "Tech Solutions LTDA",
      "taxId": "12345678900",
      "countryCode": "BR",
      "status": "under_review",
      "entityData": {
        "company": {
          "legalName": "Tech Solutions LTDA",
          "tradeName": "Tech Solutions",
          "incorporationDate": "2020-01-15",
          "industry": "Technology"
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:00.000Z"
    },
    "summary": {
      "entitiesCreated": 1,
      "relationshipsCreated": 0,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

​
Respuestas de error

​
400 Bad Request - Tax ID inválido

{
  "success": false,
  "error": "Invalid CPF format for Brazil"
}

​
404 Not Found - Empresa no encontrada en el registro

{
  "success": false,
  "error": "Entity not found in official registry",
  "details": {
    "taxId": "123.456.789-00",
    "country": "BR",
    "registry": "Receita Federal"
  }
}

​
409 Conflict - La empresa ya existe

{
  "success": false,
  "error": "Entity with this tax ID already exists",
  "details": {
    "existingEntityId": "uuid",
    "taxId": "123.456.789-00"
  }
}

​
Mejores prácticas

  1. Manejo de errores: Siempre verifica el campo success en la respuesta
  2. Límite de velocidad: Ten en cuenta los límites de velocidad al crear múltiples empresas
  3. Selección de integración: Elige integraciones específicas para un mejor control sobre el costo y el rendimiento

​
Próximos pasos