Skip to main content
POST
/
entities
/
automatic
Crear una entidad 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>",
  "nationality": {},
  "monitoring": {},
  "externalId": "<string>",
  "depth": 123,
  "isClient": true,
  "riskMatrixId": "<string>",
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'
{
  "success": true,
  "data": {},
  "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

El endpoint de creación automática de entidades le permite crear entidades proporcionando información mínima (ID fiscal y país). El sistema automáticamente:
  • Obtiene datos de empresa/persona de registros oficiales
  • Enriquece la entidad con información adicional
  • Crea entidades relacionadas (accionistas, directores) según la profundidad especificada
  • Ejecuta integraciones (verificaciones y enriquecimientos) automáticamente
Esto es ideal para procesos KYB (Know Your Business) y KYC (Know Your Customer) donde desea incorporar entidades 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 entidad (ej: CNPJ para Brasil, RFC para México, CUIT para Argentina)Tipo: string (longitud mínima: 1)
​
country
string
required
Código de país ISO 3166-1 alpha-2 (ej: “BR”, “MX”, “AR”, “CL”)Tipo: string (longitud: 2)
​
type
string
required
Tipo de entidad a crear:
  • company - Entidad empresarial
  • person - Persona física
Tipo: enum - 'company' | 'person'
​
nationality
string | null
Opcional. ISO 3166-1 alfa-2 o etiqueta mapeable; se guarda en la fila de la entidad principal (misma validación que Crear entidad).
​
monitoring
object
Opcional. Misma semántica que en Crear entidad, con dos mapas:
  • main: watchlist para enrichments de la entidad raíz (taxId del request).
  • relationships: watchlist para enrichments de accionistas/relacionadas creadas con depth > 0 (mismas claves de código que en autoExecuteIntegrationsShareholders).
Hoy solo global_gueno_sanctions_enrichment. Valor recomendado: { "watchlist": true } o { "watchlist": true, "riskMatrixId": "<uuid>" | null } (también acepta boolean legacy).Cada mapa solo afecta entidades que reciben ese enrichment en el job. Requiere el código en el arreglo de enrichments correspondiente y monitoreo ON en Marketplace.
​
externalId
string
Su identificador único para esta entidad en su sistema (opcional, se generará automáticamente si no se proporciona)Tipo: string (opcional)
​
depth
number
default:"0"
Cuántos niveles de accionistas/relaciones crear automáticamente:
  • 0 - Crear solo la entidad principal (sin relaciones)
  • 1 - Crear accionistas/directores directos
  • 2 - Crear accionistas y sus accionistas
  • Máximo: 5
Tipo: number (mín: 0, máx: 5, predeterminado: 0)
​
isClient
boolean
default:"false"
Marcar esta entidad como cliente para fines de seguimientoTipo: boolean (predeterminado: false)
​
riskMatrixId
string
UUID de la matriz de riesgo para ejecutar reglas automáticamenteTipo: string | null (opcional)
​
skipRulesExecution
boolean
default:"false"
Omitir ejecución automática de reglas después de la creación de la entidadTipo: boolean (opcional, predeterminado: false)
​
status
string
default:"under_review"
Estado inicial para la entidad. Opciones:
  • active
  • inactive
  • blocked
  • under_review (predeterminado)
  • suspended
  • expired
  • deleted
  • rejected
Tipo: enum - 'active' | 'inactive' | 'blocked' | 'under_review' | 'suspended' | 'expired' | 'deleted' | 'rejected' (predeterminado: ‘under_review’)
​
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.
​
autoExecuteIntegrations
object
Configurar ejecución automática de integraciones para la entidad principal. Vea 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 para 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.
  • excludeEnrichments (array, opcional, predeterminado: []) - Códigos de proveedor que se omiten del conjunto final resuelto
{
  executeAllActiveEnrichments?: boolean; // predeterminado: false
  enrichments?: ValidProviderCodesEnum[]; // predeterminado: []
  enrichmentGroupRefs?: string[];
  excludeEnrichments?: ValidProviderCodesEnum[]; // predeterminado: []
}
Ejemplo:
{
  "executeAllActiveEnrichments": true,
  "excludeEnrichments": ["br_bdc_shareholders_enrichment"],
  "enrichmentGroupRefs": ["my_marketplace_group_slug"]
}
​
autoExecuteIntegrationsShareholders
object
Configurar ejecución automática de integraciones para accionistas y entidades relacionadas creadas durante el recorrido de la jerarquía. Esto le permite especificar diferentes integraciones para empresas vs personas. Vea 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 para todos los accionistas
  • enrichments (object, opcional) - Códigos específicos de proveedores de enriquecimiento por tipo de entidad:
    • company (array, opcional, predeterminado: []) - Enriquecimientos para accionistas empresas
    • person (array, opcional, predeterminado: []) - Enriquecimientos para accionistas personas
  • 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.
  • excludeEnrichments (array, opcional, predeterminado: []) - Códigos omitidos en las listas company y person tras el merge
{
  executeAllActiveEnrichments?: boolean; // predeterminado: false
  enrichments?: {
    company?: ValidProviderCodesEnum[]; // predeterminado: []
    person?: ValidProviderCodesEnum[]; // predeterminado: []
  };
  enrichmentGroupRefs?: string[];
  excludeEnrichments?: ValidProviderCodesEnum[]; // predeterminado: []
}
Ejemplo:
{
  "executeAllActiveEnrichments": true,
  "excludeEnrichments": ["br_bdc_shareholders_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 entidad de los registros oficiales y la solicitud fallará.

​
Brasil (BR)

​
Entidad Principal

Tipo de EntidadCódigo de Enrichment ObligatorioDescripción
Companybr_cpfcnpj_complete_company_enrichmentObtiene datos de la empresa de CNPJ/Receita Federal (razón social, nombre comercial, dirección, industria, etc.)
Personbr_bdc_basic_data_enrichmentObtiene datos de la persona vía BDC/CPF (nombre completo, fecha de nacimiento, dirección, etc.)

​
Accionistas / Entidades Relacionadas (solo cuando depth > 0)

Tipo de Entidad PrincipalCódigo(s) de Enrichment Obligatorio(s)Descripción
Companybr_bdc_shareholders_enrichmentObtiene el QSA (Quadro Societário) para descubrir accionistas y directores de la empresa
Personbr_bdc_related_companies_enrichment Y br_bdc_related_persons_enrichmentAmbos son obligatorios. Obtiene empresas y personas relacionadas con el individuo
Los enrichments de accionistas deben incluirse en el array autoExecuteIntegrations.enrichments de la entidad principal (no en autoExecuteIntegrationsShareholders), porque el sistema necesita ejecutarlos sobre la entidad principal para descubrir quiénes son los accionistas. El campo autoExecuteIntegrationsShareholders controla qué enrichments ejecutar sobre cada accionista después de ser creado.

​
Argentina (AR)

​
Entidad Principal

Tipo de EntidadCódigo de Enrichment ObligatorioDescripción
Companyar_nosis_extended_verification_enrichmentObtiene datos de la empresa de Nosis (razón social, estado CUIT, dirección, actividades, etc.)
Personar_nosis_extended_verification_enrichmentMismo proveedor para ambos tipos de entidad

​
Accionistas / Entidades Relacionadas

Argentina no soporta la creación automática de accionistas/relaciones aún. El parámetro depth debe ser 0. Si se proporciona depth > 0, la solicitud fallará con un error.
​
customData
object
Opcional — Datos que envía el cliente para la entidad principal y que no deben ser reemplazados por los enrichments del registro. No aplica a accionistas ni entidades relacionadas (depth > 0).Tras los enrichments, la API re-aplica los valores enviados en customData para que no se pierdan (p. ej. sincronización automática de nombre).Dónde se persiste cada campo:
Campo en customDataColumna root (entities)entityData
namename—
emailemailperson.email / company.email
phonephoneperson.phone / company.phone
birthDate—Solo person.dateOfBirth (personas)
address—person.address o company.address
gender—person.gender (AR, derivación CUIL)
Propiedades documentadas: name, email, phone, birthDate (persona), address (string o objeto con fullAddress, street, city, …), gender (opcional, AR).Claves adicionales (solo API): cualquier otra clave en customData se acepta y se guarda en entityData.person o entityData.company (misma protección contra enrichments). Ej.: firstName, occupation, tradeName. El dashboard solo envía los campos del formulario; integraciones vía API pueden ampliar el objeto.Ejemplo (persona):
{
  "taxId": "23450679909",
  "country": "AR",
  "type": "person",
  "customData": {
    "name": "LEDESMA BRUNO EZEQUIEL",
    "email": "cliente@empresa.com",
    "phone": "+541112345678",
    "birthDate": "1990-05-15",
    "address": "Av. Corrientes 1234, CABA"
  }
}
Ejemplo (empresa):
{
  "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 (persona o 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"]
}

​
Parámetros de Query

​
refresh
boolean
default:"false"
Fuerza el re-enriquecimiento de la entidad principal incluso si ya existe en el sistema.Tipo: boolean (query string: "true" o "false")Comportamiento:
  • Cuando es true: Fuerza la búsqueda de datos actualizados de registros oficiales y proveedores de enriquecimiento
  • Cuando es false u omitido: Utiliza datos de enriquecimiento en caché si están disponibles
  • Sobreescribe la configuración de organización enrichmentsConfig.reEnrichExistingEntities
Casos de Uso:
  • Revisiones periódicas de cumplimiento que requieren información actualizada
  • Re-validar datos de entidad después de cambios regulatorios
  • Actualizar estructura empresarial después de cambios corporativos conocidos
  • Actualización manual activada por oficiales de cumplimiento
Ejemplo:
POST http://api.gu1.ai/entities/automatic?refresh=true
Nota de Costo: Puede incurrir en cargos adicionales de proveedores de datos terceros.
​
reEnrichExistingChildEntities
boolean
default:"false"
Fuerza el re-enriquecimiento de TODOS los accionistas y entidades relacionadas en la estructura corporativa.Tipo: boolean (query string: "true" o "false")Comportamiento:
  • Cuando es true: Fuerza la búsqueda de datos actualizados para la entidad principal Y todos los accionistas en todos los niveles (hasta depth)
  • Cuando es false u omitido: Solo actualiza la entidad principal si refresh=true, los accionistas usan datos en caché
  • Funciona en combinación con el parámetro depth para determinar qué tan profundo actualizar
  • Sobreescribe configuración de organización para todas las entidades relacionadas
Casos de Uso:
  • Auditoría completa de estructura corporativa
  • Due diligence que requiere cadena de propiedad actualizada
  • Revisiones anuales de cumplimiento de todo el árbol corporativo
  • Investigación de estructuras de propiedad complejas
Ejemplo - Actualizar estructura completa:
POST http://api.gu1.ai/entities/automatic?reEnrichExistingChildEntities=true&depth=3
Esto actualizará la empresa principal Y todos los accionistas hasta 3 niveles de profundidad.Nota de Rendimiento:
  • Establecer esto en true con valores altos de depth (4-5) puede tomar varios minutos
  • Puede resultar en costos significativos si la estructura corporativa es compleja
  • Considere usar selectivamente solo para entidades de alto riesgo
Mejor Práctica:
  • Use refresh=true solo para actualizaciones de entidad única
  • Use reEnrichExistingChildEntities=true solo cuando necesite validación completa de la cadena de propiedad

​
Respuesta

El endpoint se ejecuta síncronamente y retorna el resultado completo incluyendo la entidad principal y todas las entidades relacionadas creadas.
​
success
boolean
Indica si la entidad se creó correctamente
​
data
object
Información completa sobre la creación:
  • entity (object) - La entidad principal creada con todos sus datos
  • shareholders (array) - Array de entidades de accionistas creadas (para empresas)
  • relationships (array) - Array de entidades relacionadas creadas (para personas)
  • summary (object):
    • entitiesCreated (number) - Número total de entidades creadas
    • relationshipsCreated (number) - Número total de relaciones creadas
    • errorsCount (number) - Número de errores encontrados
  • errors (object, opcional) - Detalles de cualquier error que ocurrió:
    • creationFailed (array) - Creaciones de entidades que fallaron
    • enrichmentFailed (array) - Ejecuciones de enriquecimiento que fallaron
​
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 (array de { name?, type?, severity?, description? }), 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.

​
Eventos WebSocket

El sistema emite eventos en tiempo real durante el proceso de creación:

​
entity:creation-started

Emitido cuando el proceso de creación comienza. 
{
  "taxId": "12.345.678/0001-90",
  "type": "company",
  "userId": "user_id"
}

​
entity:creation-completed

Emitido cuando la entidad y todas las relaciones han sido creadas. 
{
  "success": true,
  "mainEntity": {
    "id": "uuid",
    "name": "Nombre de la Empresa",
    "taxId": "12.345.678/0001-90"
  },
  "stats": {
    "totalEntitiesCreated": 15,
    "companiesCreated": 8,
    "peopleCreated": 7,
    "relationshipsCreated": 14
  }
}

​
entity:creation-failed

Emitido si el proceso de creación falla. 
{
  "success": false,
  "error": "Mensaje de error",
  "taxId": "12.345.678/0001-90"
}

​
Monitoreo de sanciones Gu1 en creación automática

En POST /entities/automatic:
CampoAplica a
monitoring.mainEntidad principal (taxId del body) cuando su enrichment corre desde autoExecuteIntegrations.
monitoring.relationshipsCada accionista/relacionada con depth > 0 cuando su enrichment corre desde autoExecuteIntegrationsShareholders (por type company/person).
Hoy el único código con monitoreo vía body es global_gueno_sanctions_enrichment. Debe estar en el arreglo de enrichments del nivel que corresponda y en el mapa main o relationships con watchlist activo. 
{
  "taxId": "30-71000001-2",
  "country": "AR",
  "type": "company",
  "depth": 1,
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    },
    "relationships": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true,
        "riskMatrixId": null
      }
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": [
      "ar_afip_registration_enrichment",
      "global_gueno_sanctions_enrichment"
    ]
  },
  "autoExecuteIntegrationsShareholders": {
    "executeAllActiveEnrichments": false,
    "enrichments": {
      "company": ["global_gueno_sanctions_enrichment"],
      "person": ["global_gueno_sanctions_enrichment"]
    }
  }
}
  • main: la matriz Gu1 de la empresa matriz puede heredar riskMatrixId del body o usar matriz dedicada en el objeto.
  • relationships: riskMatrixId: null hereda la matriz global de cada entidad hija; un UUID fija matriz solo para screening de monitoreo de esas hijas.
  • Los enrichments de registro (p. ej. ar_afip_registration_enrichment) no usan monitoring; corren siempre como consulta normal.
Este cuerpo solo muestra monitoring y los códigos Gu1. Un request real debe incluir también los enriquecimientos obligatorios de registro para el country y type elegidos (ver Códigos de enriquecimiento requeridos por país más arriba); si no, la creación automática fallará.

​
Ejemplos

​
Crear Empresa con Accionistas (Profundidad 1)

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

​
Crear Persona (KYC) 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": "person",
    "externalId": "customer_12345",
    "depth": 0,
    "autoExecuteIntegrations": {
      "enrichments": ["br_bdc_basic_data_enrichment"]
    }
  }'

​
Crear Empresa Argentina (Sin Soporte de Accionistas)

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "30-12345678-9",
    "country": "AR",
    "type": "company",
    "depth": 0,
    "isClient": true,
    "riskMatrixId": "risk_matrix_uuid",
    "autoExecuteIntegrations": {
      "enrichments": ["ar_nosis_extended_verification_enrichment"]
    }
  }'

​
Crear Empresa Brasileña con Accionistas e Integraciones Selectivas

curl -X POST http://api.gu1.ai/entities/automatic \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxId": "12.345.678/0001-90",
    "country": "BR",
    "type": "company",
    "depth": 2,
    "isClient": true,
    "riskMatrixId": "risk_matrix_uuid",
    "autoExecuteIntegrations": {
      "enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
      "enrichmentGroupRefs": ["main_entity_group_slug"]
    },
    "autoExecuteIntegrationsShareholders": {
      "enrichments": {
        "company": ["br_cpfcnpj_complete_company_enrichment"],
        "person": ["br_bdc_basic_data_enrichment"]
      },
      "enrichmentGroupRefs": ["child_entities_group_slug"]
    }
  }'

​
Ejemplo de Respuesta

​
Creación Exitosa de Empresa con Accionistas

{
  "success": true,
  "data": {
    "entity": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "organizationId": "org_uuid",
      "type": "company",
      "name": "Tech Solutions LTDA",
      "taxId": "12345678000190",
      "countryCode": "BR",
      "status": "under_review",
      "riskScore": null,
      "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"
    },
    "shareholders": [
      {
        "id": "shareholder_1_uuid",
        "type": "person",
        "name": "João Silva",
        "taxId": "12345678900",
        "countryCode": "BR",
        "entityData": {
          "person": {
            "firstName": "João",
            "lastName": "Silva"
          }
        },
        "shareholderInfo": {
          "percentage": 60.0,
          "role": "Sócio Administrador"
        }
      },
      {
        "id": "shareholder_2_uuid",
        "type": "person",
        "name": "Maria Santos",
        "taxId": "98765432100",
        "countryCode": "BR",
        "entityData": {
          "person": {
            "firstName": "Maria",
            "lastName": "Santos"
          }
        },
        "shareholderInfo": {
          "percentage": 40.0,
          "role": "Sócia"
        }
      }
    ],
    "summary": {
      "entitiesCreated": 3,
      "relationshipsCreated": 2,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

​
Creación Exitosa de Persona

{
  "success": true,
  "data": {
    "entity": {
      "id": "person_uuid",
      "organizationId": "org_uuid",
      "type": "person",
      "name": "João Silva",
      "taxId": "12345678900",
      "countryCode": "BR",
      "status": "under_review",
      "entityData": {
        "person": {
          "firstName": "João",
          "lastName": "Silva",
          "dateOfBirth": "1985-05-15"
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:00.000Z"
    },
    "relationships": [],
    "summary": {
      "entitiesCreated": 1,
      "relationshipsCreated": 0,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

​
Respuestas de Error

​
400 Bad Request - ID Fiscal Inválido

{
  "success": false,
  "error": "Formato de CNPJ inválido para Brasil"
}

​
404 Not Found - Entidad No Encontrada en el Registro

{
  "success": false,
  "error": "Entidad no encontrada en el registro oficial",
  "details": {
    "taxId": "12.345.678/0001-90",
    "country": "BR",
    "registry": "Receita Federal"
  }
}

​
409 Conflict - La Entidad Ya Existe

{
  "success": false,
  "error": "La entidad con este ID fiscal ya existe",
  "details": {
    "existingEntityId": "uuid",
    "taxId": "12.345.678/0001-90"
  }
}

​
500 Internal Server Error

{
  "success": false,
  "error": "Error al crear entidad automáticamente",
  "details": {
    "message": "Timeout de API externa"
  }
}

​
Mejores Prácticas

  1. Use la profundidad sabiamente: Valores de profundidad más altos (3-5) pueden crear muchas entidades y tardar más en completarse. Comience con profundidad 0-1 para pruebas.
  2. Monitoree eventos WebSocket: Aunque la API retorna síncronamente, los eventos WebSocket también se emiten para actualizaciones de UI en tiempo real (entity:creation-started, entity:creation-completed, entity:creation-failed).
  3. Maneje timeouts: Para jerarquías complejas con alta profundidad, la solicitud puede tomar varios minutos. Configure valores de timeout HTTP apropiados en su cliente.
  4. Manejo de errores: Siempre verifique el campo success y el objeto errors en la respuesta. Algunas entidades pueden crearse exitosamente mientras otras fallan.
  5. Limitación de velocidad: Tenga cuidado con los límites de velocidad al crear múltiples entidades en rápida sucesión. El endpoint obtiene datos de APIs externas que pueden tener sus propios límites de velocidad.

​
Endpoints Relacionados