Materializar relações
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_bodyReferência API
Materializar relações
Cria ou atualiza acionistas e entidades relacionadas a partir do enriquecimento normalizado (Brasil e países suportados) — no modelo universal de entidades gu1.
POST
/
entities
/
{entityId}
/
relationships
/
materialize
Materializar relações
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_bodyVisão geral
Materializa relações e entidades relacionadas para uma pessoa ou empresa existente usando a linha mais recente denormalized_enrichment. Casos típicos:
- Brasil — empresa: cria ou atualiza a cadeia de acionistas (QSA) a partir dos dados normalizados.
- Brasil — pessoa: cria ou atualiza empresas e pessoas relacionadas a partir dos dados normalizados.
runEnrichmentFirst): apenas os provedores que a estratégia do país exige para aquele tipo de entidade a fim de atualizar sócios/relações no normalizado (não a lista completa do marketplace). Nesse passo sempre se pedem dados novos aos provedores. Em seguida executa o mesmo tipo de pipeline usado na criação automática.
A entidade deve ser
company ou person. Outros tipos retornam 400. O país do dossiê precisa ter estratégia de criação automática (hoje o fluxo é usado principalmente no Brasil; em outros países pode retornar 400 se faltarem padrões ou a configuração de profundidade/provedores for inválida).Endpoint
POST http://api.gu1.ai/entities/{entityId}/relationships/materialize
Autenticação
Requer uma chave de API válida:Authorization: Bearer YOUR_API_KEY
Parâmetros de rota
string
required
UUID da entidade raiz (pessoa ou empresa) cujas relações você quer materializar.
Corpo da requisição
boolean
default:"false"
Se
true, a API reexecuta na raiz apenas os enriquecimentos que a estratégia do país exige para aquele tipo de entidade a fim de preencher sócios/relações no normalizado (ex.: Brasil empresa vs pessoa). Não executa todos os enriquecimentos do marketplace na raiz.Se false, já deve existir uma linha em normalized_enrichment; caso contrário a API retorna 422 (NO_NORMALIZED_ENRICHMENT).integer
default:"1"
Quantos níveis de sócios ou relacionados processar. Faixa 0–5 (padrão do 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"
Com
true, cada novo filho é criado só com dados do normalizado do dossier raiz (nome + tax ID) e não roda o pipeline de filhos de autoExecuteIntegrationsShareholders. Vale para empresa (QSA) e pessoa no Brasil. Não pode ser combinado com um autoExecuteIntegrationsShareholders com pipeline não vazio.boolean
default:"true"
Com
true (padrão), a API responde 202 na hora com data.status: "processing" e executa em segundo plano enriquecimento, materialização e matriz de risco opcional. O término é sinalizado via Socket.IO (abaixo).Com false, o servidor aguarda o pipeline completo e responde 200 com contadores e flags em data.object
Opcional. Após o pipeline, executa regras / matriz de risco apenas na entidade raiz.
execute(boolean, obrigatório se o objeto for enviado):truepara rodar a matriz ao finalizar a materialização.riskMatrixId(UUID | null, opcional):nullou omitido → usa a matriz atribuída à entidade; UUID → executa essa matriz somente nesta execução (override; não altera a linha da entidade).
"riskMatrix": { "execute": true, "riskMatrixId": null }
boolean
Com
true, se uma entidade filha (sócio / relacionado) já existia na organização (mesmo tax ID), o pipeline reexecuta os enriquecimentos configurados para essa filha em vez de pular o refresh.Assíncrono (padrão): HTTP 202 + Socket.IO
ComrunInBackground: true, a resposta é 202:
{
"success": true,
"data": {
"status": "processing",
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"countryCode": "BR",
"entityType": "company"
}
}
| Evento | Quando | Payload (resumo) |
|---|---|---|
entity:relationship-materialize-started | Pipeline enfileirado | entityId, mainEntityName, mainEntityTaxId, mainEntityType, userId |
entity:relationship-materialize-completed | Fim com sucesso ou parcial | entityId, success, entitiesCreated, relationshipsCreated, enrichmentExecuted, enrichmentProviders, riskMatrixExecuted, opcional error (string) |
entity:relationship-materialize-failed | Falha não tratada | entityId, error: { code, message, details? }, userId |
completed ou failed, busque novamente entidade, relações e listas conforme sua integração (GET /entities/:id, etc.).
Resposta 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 pode ser true e data.error trazer mensagem legível — verifique ambos.
Exemplo: empresa BR, assíncrono + matriz de risco
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 }
}'
Exemplo: forçar uma matriz específica só nesta execução
{
"runEnrichmentFirst": false,
"depth": 1,
"runInBackground": false,
"riskMatrix": {
"execute": true,
"riskMatrixId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
}
Erros (seleção)
| HTTP | Código (típico) | Significado |
|---|---|---|
| 400 | INVALID_ENTITY_TYPE | Entidade não é company nem person |
| 400 | COUNTRY_NOT_SUPPORTED | Sem estratégia / país não suportado para este fluxo |
| 400 | NO_DEFAULT_RELATIONSHIP_ENRICHMENTS | A estratégia do país não define provedores de relação para este tipo de entidade |
| 404 | ENTITY_NOT_FOUND | entityId inexistente para a organização |
| 422 | NO_NORMALIZED_ENRICHMENT | runEnrichmentFirst: false sem linha normalizada |
| 422 | INVALID_RELATIONSHIP_ENRICHMENT_CONFIG | Configuração inválida de enrichments filhos / profundidade |
| 500 | ENRICHMENT_FAILED | Falha no enriquecimento com runEnrichmentFirst: true (detalhes no corpo) |
Ver também
Was this page helpful?