Materializar relaciones
curl --request POST \
--url http://api.gu1.ai/entities/{entityId}/relationships/materialize \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"runEnrichmentFirst": true,
"depth": 123,
"autoExecuteIntegrationsShareholders": {},
"executeOnlyRootData": true,
"runInBackground": true,
"riskMatrix": {},
"refreshEnrichShareholders": true
}
'import requests
url = "http://api.gu1.ai/entities/{entityId}/relationships/materialize"
payload = {
"runEnrichmentFirst": True,
"depth": 123,
"autoExecuteIntegrationsShareholders": {},
"executeOnlyRootData": True,
"runInBackground": True,
"riskMatrix": {},
"refreshEnrichShareholders": True
}
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({
runEnrichmentFirst: true,
depth: 123,
autoExecuteIntegrationsShareholders: {},
executeOnlyRootData: true,
runInBackground: true,
riskMatrix: {},
refreshEnrichShareholders: true
})
};
fetch('http://api.gu1.ai/entities/{entityId}/relationships/materialize', 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/{entityId}/relationships/materialize",
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([
'runEnrichmentFirst' => true,
'depth' => 123,
'autoExecuteIntegrationsShareholders' => [
],
'executeOnlyRootData' => true,
'runInBackground' => true,
'riskMatrix' => [
],
'refreshEnrichShareholders' => true
]),
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/{entityId}/relationships/materialize"
payload := strings.NewReader("{\n \"runEnrichmentFirst\": true,\n \"depth\": 123,\n \"autoExecuteIntegrationsShareholders\": {},\n \"executeOnlyRootData\": true,\n \"runInBackground\": true,\n \"riskMatrix\": {},\n \"refreshEnrichShareholders\": true\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/{entityId}/relationships/materialize")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"runEnrichmentFirst\": true,\n \"depth\": 123,\n \"autoExecuteIntegrationsShareholders\": {},\n \"executeOnlyRootData\": true,\n \"runInBackground\": true,\n \"riskMatrix\": {},\n \"refreshEnrichShareholders\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/{entityId}/relationships/materialize")
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 \"runEnrichmentFirst\": true,\n \"depth\": 123,\n \"autoExecuteIntegrationsShareholders\": {},\n \"executeOnlyRootData\": true,\n \"runInBackground\": true,\n \"riskMatrix\": {},\n \"refreshEnrichShareholders\": true\n}"
response = http.request(request)
puts response.read_bodyReferencia API
Materializar relaciones
Crea o actualiza accionistas y entidades relacionadas a partir del enriquecimiento normalizado (Brasil y países soportados). Consulta el esquema del request.
POST
/
entities
/
{entityId}
/
relationships
/
materialize
Materializar relaciones
curl --request POST \
--url http://api.gu1.ai/entities/{entityId}/relationships/materialize \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"runEnrichmentFirst": true,
"depth": 123,
"autoExecuteIntegrationsShareholders": {},
"executeOnlyRootData": true,
"runInBackground": true,
"riskMatrix": {},
"refreshEnrichShareholders": true
}
'import requests
url = "http://api.gu1.ai/entities/{entityId}/relationships/materialize"
payload = {
"runEnrichmentFirst": True,
"depth": 123,
"autoExecuteIntegrationsShareholders": {},
"executeOnlyRootData": True,
"runInBackground": True,
"riskMatrix": {},
"refreshEnrichShareholders": True
}
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({
runEnrichmentFirst: true,
depth: 123,
autoExecuteIntegrationsShareholders: {},
executeOnlyRootData: true,
runInBackground: true,
riskMatrix: {},
refreshEnrichShareholders: true
})
};
fetch('http://api.gu1.ai/entities/{entityId}/relationships/materialize', 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/{entityId}/relationships/materialize",
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([
'runEnrichmentFirst' => true,
'depth' => 123,
'autoExecuteIntegrationsShareholders' => [
],
'executeOnlyRootData' => true,
'runInBackground' => true,
'riskMatrix' => [
],
'refreshEnrichShareholders' => true
]),
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/{entityId}/relationships/materialize"
payload := strings.NewReader("{\n \"runEnrichmentFirst\": true,\n \"depth\": 123,\n \"autoExecuteIntegrationsShareholders\": {},\n \"executeOnlyRootData\": true,\n \"runInBackground\": true,\n \"riskMatrix\": {},\n \"refreshEnrichShareholders\": true\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/{entityId}/relationships/materialize")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"runEnrichmentFirst\": true,\n \"depth\": 123,\n \"autoExecuteIntegrationsShareholders\": {},\n \"executeOnlyRootData\": true,\n \"runInBackground\": true,\n \"riskMatrix\": {},\n \"refreshEnrichShareholders\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/{entityId}/relationships/materialize")
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 \"runEnrichmentFirst\": true,\n \"depth\": 123,\n \"autoExecuteIntegrationsShareholders\": {},\n \"executeOnlyRootData\": true,\n \"runInBackground\": true,\n \"riskMatrix\": {},\n \"refreshEnrichShareholders\": true\n}"
response = http.request(request)
puts response.read_bodyDescripción general
Materializa relaciones y entidades relacionadas para una persona o empresa existente usando la fila más reciente denormalized_enrichment. Casos típicos:
- Brasil — empresa: crea o actualiza la cadena de accionistas (QSA) a partir de datos normalizados.
- Brasil — persona: crea o actualiza empresas y personas relacionadas a partir de datos normalizados.
runEnrichmentFirst): solo los proveedores que la estrategia del país exige para ese tipo de entidad a fin de refrescar socios/relaciones en el normalizado (no el listado completo del marketplace). Para ese paso siempre se piden datos frescos a los proveedores. Luego ejecuta el mismo tipo de pipeline que en la creación automática.
La entidad debe ser
company o person. Otros tipos devuelven 400. El país del dossier debe tener estrategia de creación automática (hoy el flujo se usa principalmente en Brasil; en otros países puede devolverse 400 si faltan valores por defecto o la configuración de profundidad/proveedores no es válida).Endpoint
POST http://api.gu1.ai/entities/{entityId}/relationships/materialize
Autenticación
Requiere una clave de API válida:Authorization: Bearer YOUR_API_KEY
Parámetros de ruta
string
required
UUID de la entidad raíz (persona o empresa) cuyas relaciones querés materializar.
Cuerpo de la solicitud
boolean
default:"false"
Si es
true, la API vuelve a ejecutar en la raíz solo los enriquecimientos que la estrategia del país requiere para ese tipo de entidad a fin de poblar socios/relaciones en el normalizado (p. ej. Brasil empresa vs persona). No ejecuta todos los enriquecimientos del marketplace sobre la raíz.Si es false, debe existir ya una fila de normalized_enrichment; si no, la API responde 422 (NO_NORMALIZED_ENRICHMENT).integer
default:"1"
Niveles de socios o relacionados a procesar. Rango permitido 0–5 (por defecto en esquema 1).
object
{
"executeAllActiveEnrichments": false,
"enrichments": {
"company": ["br_bdc_shareholders_enrichment"],
"person": ["br_cpfcnpj_complete_person_enrichment"]
},
"enrichmentGroupRefs": ["child_entities_group_slug"]
}
boolean
default:"false"
Con
true, cada nuevo hijo se crea solo con datos del normalizado del dossier raíz (nombre + tax ID) y no se aplica el pipeline de hijos de autoExecuteIntegrationsShareholders. Aplica a empresa (QSA) y persona en Brasil. No puede combinarse con un autoExecuteIntegrationsShareholders con pipeline no vacío.boolean
default:"true"
Con
true (predeterminado), la API responde 202 al instante con data.status: "processing" y ejecuta en segundo plano enriquecimiento, materialización y matriz de riesgo opcional. El fin del proceso se notifica por Socket.IO (ver más abajo).Con false, el servidor espera a terminar todo el pipeline y responde 200 con contadores y flags en data.object
Opcional. Tras el pipeline, ejecuta reglas / matriz de riesgo solo sobre la entidad raíz.
execute(boolean, obligatorio si enviás el objeto):truepara correr la matriz al finalizar la materialización.riskMatrixId(UUID | null, opcional):nullu omitido → usa la matriz asignada a la entidad; un UUID → ejecuta esa matriz solo en esta corrida (override; no modifica la entidad).
"riskMatrix": { "execute": true, "riskMatrixId": null }
boolean
Con
true, si una entidad hija (socio / relacionado) ya existía en tu organización (mismo tax ID), el pipeline vuelve a ejecutar los enriquecimientos configurados para esa hija en lugar de omitir el refresco.Comportamiento asíncrono (predeterminado): HTTP 202 + Socket.IO
ConrunInBackground: true, la respuesta es 202:
{
"success": true,
"data": {
"status": "processing",
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"countryCode": "BR",
"entityType": "company"
}
}
| Evento | Cuándo | Payload (resumen) |
|---|---|---|
entity:relationship-materialize-started | Pipeline encolado | entityId, mainEntityName, mainEntityTaxId, mainEntityType, userId |
entity:relationship-materialize-completed | Fin correcto o parcial | entityId, success, entitiesCreated, relationshipsCreated, enrichmentExecuted, enrichmentProviders, riskMatrixExecuted, opcional error (string) |
entity:relationship-materialize-failed | Fallo no controlado | entityId, error: { code, message, details? }, userId |
completed o failed, volvé a consultar entidad, relaciones y listados según tu integración (GET /entities/:id, etc.).
Respuesta síncrona (runInBackground: false): HTTP 200
{
"success": true,
"data": {
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"countryCode": "BR",
"entityType": "company",
"entitiesCreated": 3,
"relationshipsCreated": 5,
"enrichmentExecuted": true,
"enrichmentProviders": ["br_bdc_shareholders_enrichment"],
"riskMatrixExecuted": true
}
}
success puede ser true y data.error traer un mensaje legible: revisá ambos.
Ejemplo: empresa BR, asíncrono + matriz de riesgo
curl -X POST "http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/relationships/materialize" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"runEnrichmentFirst": true,
"depth": 2,
"autoExecuteIntegrationsShareholders": {
"executeAllActiveEnrichments": false,
"enrichments": {
"company": ["br_bdc_shareholders_enrichment"],
"person": ["br_cpfcnpj_complete_person_enrichment"]
},
"enrichmentGroupRefs": ["child_entities_group_slug"]
},
"runInBackground": true,
"riskMatrix": { "execute": true, "riskMatrixId": null }
}'
Ejemplo: forzar una matriz concreta solo en esta ejecución
{
"runEnrichmentFirst": false,
"depth": 1,
"runInBackground": false,
"riskMatrix": {
"execute": true,
"riskMatrixId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
}
Errores (selección)
| HTTP | Código (típico) | Significado |
|---|---|---|
| 400 | INVALID_ENTITY_TYPE | La entidad no es company ni person |
| 400 | COUNTRY_NOT_SUPPORTED | Sin estrategia / país no soportado para este flujo |
| 400 | NO_DEFAULT_RELATIONSHIP_ENRICHMENTS | La estrategia del país no define proveedores de relación para este tipo de entidad |
| 404 | ENTITY_NOT_FOUND | entityId inexistente para la organización |
| 422 | NO_NORMALIZED_ENRICHMENT | runEnrichmentFirst: false sin fila normalizada |
| 422 | INVALID_RELATIONSHIP_ENRICHMENT_CONFIG | Configuración inválida de enriquecimientos hijos / profundidad |
| 500 | ENRICHMENT_FAILED | Falló el enriquecimiento con runEnrichmentFirst: true (detalle en el cuerpo del error) |
Ver también
Was this page helpful?