Skip to main content
POST
Crear una entidad automáticamente con enriquecimiento

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 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

Autenticación

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

Cuerpo de la Solicitud

string
required
Número de identificación fiscal de la entidad (CNPJ/CPF para Brasil, CUIT/CUIL para Argentina, RUT para Chile).En una organización, un taxId activo (normalizado: solo letras y dígitos) puede pertenecer a una sola entidad — sea person o company. Si ya existe el mismo tipo, la API lo reutiliza (alreadyExisted). Si otro tipo ya tiene ese tax ID, la solicitud falla con 409 y código DUPLICATE_TAX_ID.Tipo: string (longitud mínima: 1)
string
required
Código de país ISO 3166-1 alpha-2. La creación automática soporta solo BR, AR y CL. Cualquier otro país devuelve un error indicando que la creación automática no está soportada para ese país — usá Crear una entidad.Tipo: string (longitud: 2)
string
required
Tipo de entidad a crear:
  • company - Entidad empresarial
  • person - Persona física
Tipo: enum - 'company' | 'person'
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).
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.
string
Su identificador único para esta entidad en su sistema. Opcional.Si se omite, externalId se establece con el tax ID normalizado a partir del taxId obligatorio: solo letras y dígitos, mayúsculas (sin puntos, guiones ni espacios). Ejemplo: 30-12345678-9 → 30123456789.El campo taxId se sigue guardando en el formato de visualización del país. Mismas reglas que Crear una entidad (persona o empresa) cuando hay taxId.Tipo: string (opcional)
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)
Brasil + depth > 0 falla toda la solicitud si faltan los enrichments de descubrimiento. La API lo valida antes de crear la entidad principal: no crea la persona o empresa y después omite los relacionados.
  • Persona: br_bdc_related_companies_enrichment y br_bdc_related_persons_enrichment deben estar en el conjunto resuelto de la entidad principal (autoExecuteIntegrations.enrichments, o todos los enrichments habilitados del marketplace si executeAllActiveEnrichments: true). Ambos deben estar habilitados en la organización. executeAllActiveEnrichments: true no saltea esto si alguno está deshabilitado o en excludeEnrichments.
  • Empresa: br_bdc_shareholders_enrichment debe estar en ese mismo conjunto resuelto y habilitado.
Si no podés ejecutar esos enrichments, enviá depth: 0. autoExecuteIntegrationsShareholders solo controla enrichments en los hijos después de existir; no cumple este chequeo.
array
Vínculos declarativos a entidades ya existentes (por relatedEntityId / relatedTaxId / relatedExternalId + relationshipType + role). Independiente de depth / enrichment de proveedores. Máx. 10. Si la contraparte no existe → error RELATED_ENTITY_NOT_FOUND y no se crea la entidad. Misma semántica que Crear entidad.
boolean
default:"false"
Con true, después de vincular las contrapartes de relationships, también ejecuta los enrichments de autoExecuteIntegrationsShareholders sobre esas entidades existentes (por tipo de relacionada: listas company vs person). Independiente de depth.Tipo: boolean (opcional, predeterminado: false)
string | number
Fecha de registro opcional para la entidad principal. String datetime ISO 8601 o epoch en milisegundos.Tipo: string (datetime ISO) | number (opcional)
boolean
default:"false"
Con true, la creación se encola y la API responde de inmediato con 202 y data.status: "processing" más un jobId; el final se informa por Socket.IO (ver Eventos WebSocket). Con false (predeterminado), la solicitud corre sincrónica y devuelve el resultado completo.Tipo: boolean (opcional, predeterminado: false)
string
UUID de una automatización con trigger create_entity_flow (o entity_created + flujo automático). Si se envía, la solicitud pasa a ser un flujo de creación: se ignoran autoExecuteIntegrations, autoExecuteIntegrationsShareholders y depth, corre solo esa automatización (enrichments, matriz de riesgo, condiciones y acciones van en el workflow) y no se emite entity_created. Si el id no es una automatización create_entity_flow habilitada, se usa el flujo del body.Tipo: string (uuid, opcional)
boolean
default:"false"
Marcar esta entidad como cliente para fines de seguimientoTipo: boolean (predeterminado: false)
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).Tipo: string | string[] | null (opcional)
string[]
Preferido para varias matrices: lista ordenada de UUIDs. Tiene precedencia sobre riskMatrixId cuando viene informada y no vacía.Tipo: string[] (opcional)
boolean
default:"false"
Omitir ejecución automática de reglas después de la creación de la entidadTipo: boolean (opcional, predeterminado: false)
string
default:"under_review"
Estado inicial para la entidad. Opciones:
  • active
  • inactive
  • blocked
  • under_review (predeterminado)
  • pending_verification - Esperando completar KYC/KYB
  • awaiting_information - Esperando datos del cliente (p. ej. documentos de onboarding pedidos por correo)
  • suspended
  • expired
  • deleted
  • rejected
Tipo: enum - 'active' | 'inactive' | 'blocked' | 'under_review' | 'pending_verification' | 'awaiting_information' | 'suspended' | 'expired' | 'deleted' | 'rejected' | 'not_started' (predeterminado: ‘under_review’)
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.
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. Si el código es el de datos básicos que se ejecutaría (primario habilitado o sustituto), esa creación no lo corre y usa el siguiente de la cadena que esté habilitado y no excluido.
Ejemplo:
No actives un fallback de catálogo en Marketplace (ni lo listes acá) si solo lo querés cuando falle el primario. Ver Fallbacks del Marketplace.
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. También salta el datos básicos de esas entidades relacionadas si el código excluido es el que se ejecutaría.
Ejemplo:

Códigos de Enrichment Obligatorios por País

La creación automática necesita al menos un enrichment de datos básicos habilitado en Marketplace para ese país y ese tipo (empresa o persona). El primario canónico corre primero si está activo y no está en excludeEnrichments. Si está apagado o excluido, corre el primer sustituto de su cadena que sí esté habilitado y no excluido. Si ninguno de la cadena queda disponible, la solicitud falla antes de crear la entidad.executeAllActiveEnrichments: true solo incluye enrichments habilitados. Un sustituto apagado no cuenta como fuente de datos básicos. Si el primario está activo y falla, un sustituto puede correr igual con la tarjeta apagada cuando el catálogo tiene fallback_requires_activation: false. Eso no reemplaza el requisito de tener alguno habilitado para arrancar.
Si falta toda la cadena, la respuesta es HTTP 422 con success: false y error.code BASIC_DATA_ENRICHMENT_REQUIRED. El texto de error.message y de data.errors.creationFailed[].error es el mismo que el log de la API (inglés, recortado a 500 caracteres). No es el mensaje genérico de lookup (We could not complete the basic data lookup for this document.). El texto nombra los códigos a activar, en el orden de la cadena del catálogo.
Persona en Brasil usa la misma frase con BR person y los códigos de persona de la tabla de abajo. Argentina y Chile, igual, con su propia cadena. La importación masiva en modo automatic guarda ese mismo texto en el error de la fila.

Brasil (BR)

Entidad Principal

Accionistas / Entidades Relacionadas (solo cuando depth > 0)

Estos códigos deben estar en el conjunto resuelto de la entidad principal, no solo en autoExecuteIntegrationsShareholders. Faltar un enrichment de relacionados (o el de accionistas en empresas) es un fallo duro, no una creación parcial.
La API ejecuta esos enrichments sobre la entidad principal para descubrir accionistas o personas/empresas relacionadas. autoExecuteIntegrationsShareholders solo controla qué corre en cada hijo después de crearlo.

Argentina (AR)

Entidad Principal

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.

Chile (CL)

Entidad Principal

Accionistas / Entidades Relacionadas

Chile 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 falla.
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:Propiedades documentadas: name, email, phone, birthDate (persona), address (string o objeto con fullAddress, street, city, …), gender (enum opcional — other para no binario).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):
Ejemplo (empresa):
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:

Parámetros de Query

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:
Nota de Costo: Puede incurrir en cargos adicionales de proveedores de datos terceros.
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:
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

Por defecto el endpoint se ejecuta síncronamente y retorna el resultado completo incluyendo la entidad principal y todas las entidades relacionadas creadas. Con runInBackground: true la respuesta es 202 y el trabajo continúa en segundo plano:
boolean
Indica si la entidad se creó correctamente
object
Información completa sobre la creación:
  • entity (object) - La entidad principal creada con todos sus datos
  • shareholders (array) - Fichas hijas materializadas en esa corrida (solo empresas). Cada ítem es { id, name, taxId, type }. El porcentaje y los roles quedan en la relación; se leen después con Obtener socios materializados.
  • 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) - Enrichments extra que fallaron después de persistir la entidad (entityId + failedProviders). Vacío si falla datos básicos y la entidad no se crea. Cada ítem de failedProviders trae providerCode, error (inglés) y code opcional. Si el request pidió un enrichment que la organización no tiene habilitado, code es INTEGRATION_NOT_ENABLED (también INTEGRATION_NOT_CONFIGURED, INTEGRATION_BLOCKED, INTEGRATION_GLOBALLY_DISABLED, CONTRACT_ACCESS_NOT_INCLUDED, INTEGRATION_NOT_FOUND). Esos códigos no se reintentan. El resto del request sí corre, y success sigue en true si la entidad se creó.
    • enrichmentFailedDetails (array, aditivo) - Cada intento de datos básicos que falló (primario + fallbacks de catálogo) cuando la entidad no se creó. Ítems: providerCode (código marketplace), code (semántico, p. ej. DOCUMENT_RESTRICTED, UPSTREAM_CREDITS_ERROR), errorMessage (inglés). También anidado en la fila de creationFailed[] correspondiente.
Para organizaciones donde esta configuración esté habilitada, si la fuente primaria identifica a una persona como menor, la entidad se crea inmediatamente como Person <taxId> con attributes.isMinor: true. No se ejecutan reintentos, fallbacks ni enrichments adicionales; el análisis de riesgo se ejecuta normalmente. Este comportamiento está desactivado por defecto.
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.
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.

entity:creation-completed

Emitido cuando la entidad y todas las relaciones han sido creadas.

entity:creation-failed

Emitido si el proceso de creación falla.

Monitoreo de sanciones Gu1 en creación automática

En POST /entities/automatic: 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.
  • 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)

Crear Persona (KYC) con Integraciones Específicas

Crear Empresa Argentina (Sin Soporte de Accionistas)

Crear Empresa Brasileña con Accionistas e Integraciones Selectivas

Ejemplo de Respuesta

Creación Exitosa de Empresa con Accionistas

Para empresas de Brasil, entityData.company.cnae y cnaeDescription contienen la actividad económica principal del resultado normalizado de datos básicos. industry mantiene la misma descripción por compatibilidad con las fichas existentes.

Creación Exitosa de Persona

Respuestas de Error

400 Bad Request - ID Fiscal Inválido

404 Not Found - Entidad No Encontrada en el Registro

409 Conflict - La Entidad Ya Existe

Se devuelve cuando el taxId normalizado ya está usado por una entidad activa de un tipo distinto en la misma organización (persona vs empresa). Los matches del mismo tipo se reutilizan en lugar de fallar.

500 Internal Server Error

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