Skip to main content
POST
http://api.gu1.ai
/
entities
/
automatic
Crear automáticamente
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>",
  "skipRulesExecution": true,
  "status": "<string>",
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {}
}
'
{
  "success": true,
  "data": {},
  "rulesResult": {}
}

​
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": true,
  "executeAllActiveChecks": false,
  "enrichments": ["serpro_cnpj", "receita_federal"],
  "checks": ["sanctions_check", "adverse_media"]
}
​
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"]
  }
}

​
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 la matriz de riesgo (si está configurada), o null

​
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": ["serpro_cpf", "bureau_credit"],
      "checks": ["pep_check", "sanctions_check"]
    }
  }'

​
Ejemplo de respuesta

{
  "success": true,
  "data": {
    "entity": {
      "id": "company_uuid",
      "organizationId": "org_uuid",
      "type": "company",
      "name": "João Silva",
      "taxId": "12345678900",
      "countryCode": "BR",
      "status": "under_review",
      "entityData": {
        "company": {
          "firstName": "João",
          "lastName": "Silva",
          "dateOfBirth": "1985-05-15",
          "nationality": "BR"
        }
      },
      "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