Crear automáticamente

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 integraciones (verificaciones y 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

UUID de la matriz de riesgo para ejecutar reglas automáticamente

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

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
executeAllActiveChecks (boolean, opcional, predeterminado: false) - Ejecutar todas las integraciones de verificación activas
enrichments (array, opcional, predeterminado: []) - Array de códigos específicos de proveedores de enriquecimiento a ejecutar
checks (array, opcional, predeterminado: []) - Array de códigos específicos de proveedores de verificación a ejecutar

{
  executeAllActiveEnrichments?: boolean; // predeterminado: false
  executeAllActiveChecks?: boolean; // predeterminado: false
  enrichments?: ValidProviderCodesEnum[]; // predeterminado: []
  checks?: ValidProviderCodesEnum[]; // predeterminado: []
}

Ejemplo:

{
  "executeAllActiveEnrichments": false,
  "enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
  "checks": ["sanctions_check"]
}

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
executeAllActiveChecks (boolean, opcional, predeterminado: false) - Ejecutar todas las verificaciones activas 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
checks (object, opcional) - Verificaciones específicas por tipo de entidad
- company (array, predeterminado: []) - Verificaciones para accionistas empresa
- person (array, predeterminado: []) - Verificaciones para accionistas persona

{
  executeAllActiveEnrichments?: boolean;
  executeAllActiveChecks?: boolean;
  enrichments?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
  checks?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
}

Ejemplo:

{
  "enrichments": {
    "person": ["br_cpfcnpj_complete_person_enrichment"],
    "company": ["br_cpfcnpj_complete_company_enrichment"]
  },
  "checks": {
    "person": ["global_complyadvantage_person_search_check"]
  }
}

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)

Escenario	Código(s) de Enrichment Obligatorio(s)	Descripción
Entidad principal	`br_cpfcnpj_complete_company_enrichment`	Obtiene datos de la empresa de CNPJ/Receita Federal (razón social, nombre comercial, dirección, industria, etc.)
Accionistas (`depth > 0`)	`br_bdc_shareholders_enrichment`	Obligatorio 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)

Escenario	Código de Enrichment Obligatorio	Descripción
Entidad principal	`ar_nosis_extended_verification_enrichment`	Obtiene 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.

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 se proporcionó riskMatrixId), 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,
      "executeAllActiveChecks": 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"],
      "checks": []
    }
  }'

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

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

Próximos pasos

Obtener empresa - Recuperar detalles de la empresa
Crear empresa manualmente - Crear empresas con tus propios datos
Crear validación KYB - Iniciar verificación de identidad

Comenzando

Casos de Uso

Webhooks

Persona

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Documentos

Enriquecimiento

Integraciones

Tutoriales Interactivos

Crear automáticamente

Descripción general

Endpoint

Autenticación

Cuerpo de la solicitud

Códigos de Enrichment Obligatorios por País

Brasil (BR)

Argentina (AR)

Respuesta

Ejemplos

Crear empresa con todas las integraciones activas

Crear empresa con integraciones específicas

Ejemplo de respuesta

Respuestas de error

400 Bad Request - Tax ID inválido

404 Not Found - Empresa no encontrada en el registro

409 Conflict - La empresa ya existe

Mejores prácticas

Próximos pasos

Comenzando

Casos de Uso

Webhooks

Persona

Empresa

Dispositivos

Eventos

Conozca Su Cliente (KYC)

Transacciones

Métodos de Pago

Reglas

Matriz de Riesgo

Alertas

Investigaciones

Ingesta de Datos

Documentos

Enriquecimiento

Integraciones

Tutoriales Interactivos

​Descripción general

​Endpoint

​Autenticación

​Cuerpo de la solicitud

​Códigos de Enrichment Obligatorios por País

​Brasil (BR)

​Argentina (AR)

​Respuesta

​Ejemplos

​Crear empresa con todas las integraciones activas

​Crear empresa con integraciones específicas

​Ejemplo de respuesta

​Respuestas de error

​400 Bad Request - Tax ID inválido

​404 Not Found - Empresa no encontrada en el registro

​409 Conflict - La empresa ya existe

​Mejores prácticas

​Próximos pasos

Descripción general

Endpoint

Autenticación

Cuerpo de la solicitud

Códigos de Enrichment Obligatorios por País

Brasil (BR)

Argentina (AR)

Respuesta

Ejemplos

Crear empresa con todas las integraciones activas

Crear empresa con integraciones específicas

Ejemplo de respuesta

Respuestas de error

400 Bad Request - Tax ID inválido

404 Not Found - Empresa no encontrada en el registro

409 Conflict - La empresa ya existe

Mejores prácticas

Próximos pasos