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,
"relationships": [
{}
],
"enrichDeclaredRelationships": true,
"registrationDate": {},
"runInBackground": true,
"workflowId": "<string>",
"isClient": true,
"riskMatrixId": [
"<string>"
],
"riskMatrixIds": [
"<string>"
],
"skipRulesExecution": true,
"status": "<string>",
"operationalHours": {},
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
'import requests
url = "http://api.gu1.ai/entities/automatic"
payload = {
"taxId": "<string>",
"country": "<string>",
"type": "<string>",
"nationality": {},
"monitoring": {},
"externalId": "<string>",
"depth": 123,
"relationships": [{}],
"enrichDeclaredRelationships": True,
"registrationDate": {},
"runInBackground": True,
"workflowId": "<string>",
"isClient": True,
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"skipRulesExecution": True,
"status": "<string>",
"operationalHours": {},
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
taxId: '<string>',
country: '<string>',
type: '<string>',
nationality: {},
monitoring: {},
externalId: '<string>',
depth: 123,
relationships: [{}],
enrichDeclaredRelationships: true,
registrationDate: {},
runInBackground: true,
workflowId: '<string>',
isClient: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
operationalHours: {},
autoExecuteIntegrations: {},
autoExecuteIntegrationsShareholders: {},
customData: {},
attributes: {}
})
};
fetch('http://api.gu1.ai/entities/automatic', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/automatic",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'taxId' => '<string>',
'country' => '<string>',
'type' => '<string>',
'nationality' => [
],
'monitoring' => [
],
'externalId' => '<string>',
'depth' => 123,
'relationships' => [
[
]
],
'enrichDeclaredRelationships' => true,
'registrationDate' => [
],
'runInBackground' => true,
'workflowId' => '<string>',
'isClient' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'operationalHours' => [
],
'autoExecuteIntegrations' => [
],
'autoExecuteIntegrationsShareholders' => [
],
'customData' => [
],
'attributes' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/automatic"
payload := strings.NewReader("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/automatic")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/automatic")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {},
"rulesResult": {},
"rulesExecutionSummary": {}
}Referencia API
Crear una entidad automáticamente con enriquecimiento
Crea automáticamente con datos enriquecidos de registros oficiales — en el modelo universal de entidades gu1 para KYC, KYB y análisis de riesgo.
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,
"relationships": [
{}
],
"enrichDeclaredRelationships": true,
"registrationDate": {},
"runInBackground": true,
"workflowId": "<string>",
"isClient": true,
"riskMatrixId": [
"<string>"
],
"riskMatrixIds": [
"<string>"
],
"skipRulesExecution": true,
"status": "<string>",
"operationalHours": {},
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
'import requests
url = "http://api.gu1.ai/entities/automatic"
payload = {
"taxId": "<string>",
"country": "<string>",
"type": "<string>",
"nationality": {},
"monitoring": {},
"externalId": "<string>",
"depth": 123,
"relationships": [{}],
"enrichDeclaredRelationships": True,
"registrationDate": {},
"runInBackground": True,
"workflowId": "<string>",
"isClient": True,
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"skipRulesExecution": True,
"status": "<string>",
"operationalHours": {},
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
taxId: '<string>',
country: '<string>',
type: '<string>',
nationality: {},
monitoring: {},
externalId: '<string>',
depth: 123,
relationships: [{}],
enrichDeclaredRelationships: true,
registrationDate: {},
runInBackground: true,
workflowId: '<string>',
isClient: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
operationalHours: {},
autoExecuteIntegrations: {},
autoExecuteIntegrationsShareholders: {},
customData: {},
attributes: {}
})
};
fetch('http://api.gu1.ai/entities/automatic', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/automatic",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'taxId' => '<string>',
'country' => '<string>',
'type' => '<string>',
'nationality' => [
],
'monitoring' => [
],
'externalId' => '<string>',
'depth' => 123,
'relationships' => [
[
]
],
'enrichDeclaredRelationships' => true,
'registrationDate' => [
],
'runInBackground' => true,
'workflowId' => '<string>',
'isClient' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'operationalHours' => [
],
'autoExecuteIntegrations' => [
],
'autoExecuteIntegrationsShareholders' => [
],
'customData' => [
],
'attributes' => [
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/automatic"
payload := strings.NewReader("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/automatic")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/automatic")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"relationships\": [\n {}\n ],\n \"enrichDeclaredRelationships\": true,\n \"registrationDate\": {},\n \"runInBackground\": true,\n \"workflowId\": \"<string>\",\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {},
"rulesResult": {},
"rulesExecutionSummary": {}
}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
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
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 empresarialperson- Persona física
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 condepth> 0 (mismas claves de código que enautoExecuteIntegrationsShareholders).
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 directos2- Crear accionistas y sus accionistas- Máximo:
5
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_enrichmentybr_bdc_related_persons_enrichmentdeben estar en el conjunto resuelto de la entidad principal (autoExecuteIntegrations.enrichments, o todos los enrichments habilitados del marketplace siexecuteAllActiveEnrichments: true). Ambos deben estar habilitados en la organización.executeAllActiveEnrichments: trueno saltea esto si alguno está deshabilitado o enexcludeEnrichments. - Empresa:
br_bdc_shareholders_enrichmentdebe estar en ese mismo conjunto resuelto y habilitado.
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:
activeinactiveblockedunder_review(predeterminado)pending_verification- Esperando completar KYC/KYBawaiting_information- Esperando datos del cliente (p. ej. documentos de onboarding pedidos por correo)suspendedexpireddeletedrejected
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: 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 (opcional)Propiedades:executeAllActiveEnrichments(boolean, opcional, predeterminado:false) - Ejecutar todas las integraciones de enriquecimiento activasenrichments(array, opcional, predeterminado:[]) - Array de códigos específicos de proveedores de enriquecimiento para ejecutarenrichmentGroupRefs(array de strings, opcional) - Slugs de grupos de enriquecimiento del Marketplace (solo enriquecimientos). ConexecuteAllActiveEnrichments: false, se resuelven los grupos y se fusionan conenrichmentsexplícitos. ConexecuteAllActiveEnrichments: true, los refs de grupo no se usan; losenrichmentsexplí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.
{
executeAllActiveEnrichments?: boolean; // predeterminado: false
enrichments?: ValidProviderCodesEnum[]; // predeterminado: []
enrichmentGroupRefs?: string[];
excludeEnrichments?: ValidProviderCodesEnum[]; // predeterminado: []
}
{
"executeAllActiveEnrichments": true,
"excludeEnrichments": ["br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["my_marketplace_group_slug"]
}
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: Ejemplo:
object (opcional)Propiedades:executeAllActiveEnrichments(boolean, opcional, predeterminado:false) - Ejecutar todas las integraciones de enriquecimiento activas para todos los accionistasenrichments(object, opcional) - Códigos específicos de proveedores de enriquecimiento por tipo de entidad:company(array, opcional, predeterminado:[]) - Enriquecimientos para accionistas empresasperson(array, opcional, predeterminado:[]) - Enriquecimientos para accionistas personas
enrichmentGroupRefs(array de strings, opcional) - Mismos slugs que en el objeto principal; conexecuteAllActiveEnrichments: falsese aplican tanto acompanycomo aperson. ConexecuteAllActiveEnrichments: trueen este objeto, los refs de grupo no se usan; losenrichmentsexplícitos por tipo pueden seguir añadiendo códigos tras el activo de cada lado.excludeEnrichments(array, opcional, predeterminado:[]) - Códigos omitidos en las listascompanyypersontras el merge. También salta el datos básicos de esas entidades relacionadas si el código excluido es el que se ejecutaría.
{
executeAllActiveEnrichments?: boolean; // predeterminado: false
enrichments?: {
company?: ValidProviderCodesEnum[]; // predeterminado: []
person?: ValidProviderCodesEnum[]; // predeterminado: []
};
enrichmentGroupRefs?: string[];
excludeEnrichments?: ValidProviderCodesEnum[]; // predeterminado: []
}
{
"executeAllActiveEnrichments": true,
"excludeEnrichments": ["br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["shareholder_pipeline_group_slug"]
}
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 Persona en Brasil usa la misma frase 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.{
"success": false,
"error": {
"code": "BASIC_DATA_ENRICHMENT_REQUIRED",
"message": "Automatic creation requires at least one active basic-data enrichment for BR company. Activate one of: br_cpfcnpj_complete_company_enrichment, br_brasilapi_company_enrichment, br_cnpjws_company_enrichment, br_opencnpj_company_enrichment, br_bdc_basic_data_company_enrichment (marketplace)."
},
"data": {
"entity": null,
"errors": {
"creationFailed": [
{
"entityType": "company",
"level": 0,
"code": "BASIC_DATA_ENRICHMENT_REQUIRED",
"error": "Automatic creation requires at least one active basic-data enrichment for BR company. Activate one of: br_cpfcnpj_complete_company_enrichment, br_brasilapi_company_enrichment, br_cnpjws_company_enrichment, br_opencnpj_company_enrichment, br_bdc_basic_data_company_enrichment (marketplace)."
}
]
}
}
}
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
| Tipo de Entidad | Primario (primero si está activo) | También alcanza, en este orden, si está habilitado |
|---|---|---|
| Company | br_cpfcnpj_complete_company_enrichment | br_brasilapi_company_enrichment, br_cnpjws_company_enrichment, br_opencnpj_company_enrichment, br_bdc_basic_data_company_enrichment |
| Person | br_bdc_basic_data_enrichment | br_cpfcnpj_complete_person_enrichment, br_cpfcnpj_complete_person_9_enrichment |
Accionistas / Entidades Relacionadas (solo cuando depth > 0)
| Tipo de Entidad Principal | Código(s) de Enrichment Obligatorio(s) | Descripción |
|---|---|---|
| Company | br_bdc_shareholders_enrichment | Obligatorio para descubrir el QSA. Si falta → falla toda la solicitud; la empresa no se crea. |
| Person | br_bdc_related_companies_enrichment Y br_bdc_related_persons_enrichment | Ambos obligatorios. Si falta, está deshabilitado o excluido alguno → falla toda la solicitud; la persona no se crea. |
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
| Tipo de Entidad | Primario (primero si está activo) | También alcanza si está habilitado |
|---|---|---|
| Company y Person | ar_nosis_extended_verification_enrichment | ar_arca_contribuyente_enrichment (solo en esa dirección: ARCA no vuelve al primario) |
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
| Tipo de Entidad | Primario (único de la cadena) | Sustitutos de catálogo |
|---|---|---|
| Company | cl_rutsinfo_info_company_enrichment | Ninguno. Si está apagado, la creación automática de empresa falla. |
| Person | cl_baseapi_basic_data_person_enrichment | Ninguno. Si está apagado, la creación automática de persona falla. |
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 (
Propiedades documentadas: Ejemplo (empresa):
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 customData | Columna root (entities) | entityData | |
|---|---|---|---|
name | name | — | |
email | email | person.email / company.email | |
phone | phone | person.phone / company.phone | |
birthDate | — | Solo person.dateOfBirth (personas) | |
address | — | person.address o company.address | |
gender | — | person.gender | Opcional. Enum cerrado: M, F, male, female, other, unknown. Usar other para identidad no binaria. Valores como X o non_binary se rechazan. En AR, solo M/F (o male/female) aplican a derivación CUIL y RENAPER. Ver Crear entidad — Persona. |
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):{
"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"
}
}
{
"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"
}
}
}
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
boolean
default:"false"
Fuerza el re-enriquecimiento de la entidad principal incluso si ya existe en el sistema.Tipo: Nota de Costo: Puede incurrir en cargos adicionales de proveedores de datos terceros.
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
falseu omitido: Utiliza datos de enriquecimiento en caché si están disponibles - Sobreescribe la configuración de organización
enrichmentsConfig.reEnrichExistingEntities
- 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
POST http://api.gu1.ai/entities/automatic?refresh=true
boolean
default:"false"
Fuerza el re-enriquecimiento de TODOS los accionistas y entidades relacionadas en la estructura corporativa.Tipo: Esto actualizará la empresa principal Y todos los accionistas hasta 3 niveles de profundidad.Nota de Rendimiento:
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 (hastadepth) - Cuando es
falseu omitido: Solo actualiza la entidad principal sirefresh=true, los accionistas usan datos en caché - Funciona en combinación con el parámetro
depthpara determinar qué tan profundo actualizar - Sobreescribe configuración de organización para todas las entidades relacionadas
- 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
POST http://api.gu1.ai/entities/automatic?reEnrichExistingChildEntities=true&depth=3
- Establecer esto en
truecon valores altos dedepth(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
- Use
refresh=truesolo para actualizaciones de entidad única - Use
reEnrichExistingChildEntities=truesolo 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. ConrunInBackground: true la respuesta es 202 y el trabajo continúa en segundo plano:
{
"success": true,
"data": { "status": "processing", "jobId": "...", "taxId": "...", "type": "company" }
}
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 datosshareholders(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 creadasrelationshipsCreated(number) - Número total de relaciones creadaserrorsCount(number) - Número de errores encontrados
errors(object, opcional) - Detalles de cualquier error que ocurrió:creationFailed(array) - Creaciones de entidades que fallaronenrichmentFailed(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 defailedProviderstraeproviderCode,error(inglés) ycodeopcional. Si el request pidió un enrichment que la organización no tiene habilitado,codeesINTEGRATION_NOT_ENABLED(tambiénINTEGRATION_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, ysuccesssigue entruesi 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 decreationFailed[]correspondiente.
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.
{
"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
EnPOST /entities/automatic:
| Campo | Aplica a |
|---|---|
monitoring.main | Entidad principal (taxId del body) cuando su enrichment corre desde autoExecuteIntegrations. |
monitoring.relationships | Cada accionista/relacionada con depth > 0 cuando su enrichment corre desde autoExecuteIntegrationsShareholders (por type company/person). |
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 heredarriskMatrixIddel body o usar matriz dedicada en el objeto.relationships:riskMatrixId: nullhereda 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 usanmonitoring; 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
}
}'
const response = await fetch('http://api.gu1.ai/entities/automatic', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
taxId: '12.345.678/0001-90',
country: 'BR',
type: 'company',
depth: 1,
isClient: true,
autoExecuteIntegrations: {
executeAllActiveEnrichments: true,
}
})
});
const data = await response.json();
console.log(data);
// Escuchar eventos WebSocket
socket.on('entity:creation-completed', (result) => {
console.log('Entidad creada:', result.mainEntity);
console.log('Total de entidades creadas:', result.stats.totalEntitiesCreated);
});
import requests
response = requests.post(
'http://api.gu1.ai/entities/automatic',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'taxId': '12.345.678/0001-90',
'country': 'BR',
'type': 'company',
'depth': 1,
'isClient': True,
'autoExecuteIntegrations': {
'executeAllActiveEnrichments': True,
}
}
)
data = response.json()
print(data)
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"]
}
}'
const response = await fetch('http://api.gu1.ai/entities/automatic', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
taxId: '123.456.789-00',
country: 'BR',
type: 'person',
externalId: 'customer_12345',
depth: 0,
autoExecuteIntegrations: {
enrichments: ['br_bdc_basic_data_enrichment']
}
})
});
const data = await response.json();
import requests
response = requests.post(
'http://api.gu1.ai/entities/automatic',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'taxId': '123.456.789-00',
'country': 'BR',
'type': 'person',
'externalId': 'customer_12345',
'depth': 0,
'autoExecuteIntegrations': {
'enrichments': ['br_bdc_basic_data_enrichment']
}
}
)
data = response.json()
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",
"cnae": "6202-3/00",
"cnaeDescription": "Desarrollo y licenciamiento de programas informáticos personalizables",
"industry": "Desarrollo y licenciamiento de programas informáticos personalizables"
}
},
"createdAt": "2024-12-23T10:30:00.000Z",
"updatedAt": "2024-12-23T10:30:00.000Z"
},
"shareholders": [
{
"id": "shareholder_1_uuid",
"name": "João Silva",
"taxId": "12345678900",
"type": "person"
},
{
"id": "shareholder_2_uuid",
"name": "Maria Santos",
"taxId": "98765432100",
"type": "person"
}
],
"summary": {
"entitiesCreated": 3,
"relationshipsCreated": 2,
"errorsCount": 0
}
},
"rulesResult": null
}
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
{
"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
Se devuelve cuando eltaxId 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.
{
"success": false,
"error": {
"code": "DUPLICATE_TAX_ID",
"message": "This tax ID is already registered for a company in this organization (Entity ID: uuid).",
"details": {
"existingEntityId": "uuid",
"existingEntityType": "company"
}
}
}
500 Internal Server Error
{
"success": false,
"error": "Error al crear entidad automáticamente",
"details": {
"message": "Timeout de API externa"
}
}
Mejores Prácticas
- 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.
-
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). - Maneje timeouts: Para jerarquías complejas con alta profundidad, la solicitud puede tomar varios minutos. Configure valores de timeout HTTP apropiados en su cliente.
-
Manejo de errores: Siempre verifique el campo
successy el objetoerrorsen la respuesta. Algunas entidades pueden crearse exitosamente mientras otras fallan. - 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
- Crear Entidad Manualmente - Crear entidades con sus propios datos
- Obtener Entidad - Recuperar detalles de la entidad
- Listar Entidades - Consultar sus entidades
Was this page helpful?