Importar entidades (CSV)
curl --request POST \
--url http://api.gu1.ai/batch-import/import/entities \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/batch-import/import/entities"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/batch-import/import/entities', 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/batch-import/import/entities",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/batch-import/import/entities"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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/batch-import/import/entities")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/batch-import/import/entities")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyReferência API
Importar entidades (CSV)
Envia CSV e enfileira import bulk — formato plataforma sem mappingId ou colunas custom com mappingId. Manual por padrão; automático explícito.
POST
/
batch-import
/
import
/
entities
Importar entidades (CSV)
curl --request POST \
--url http://api.gu1.ai/batch-import/import/entities \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/batch-import/import/entities"
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, headers=headers)
print(response.text)const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/batch-import/import/entities', 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/batch-import/import/entities",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/batch-import/import/entities"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
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/batch-import/import/entities")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/batch-import/import/entities")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyEndpoint
POST https://api.gu1.ai/batch-import/import/entities
Visão geral
Content-Type:multipart/form-data.
Enfileira o mesmo job bulk do hub Importações em lote. Exige entities:bulk_import e importação em massa automática na org. Resposta 202 com jobId e importMode efetivo.
Autenticação
Authorization: Bearer SUA_API_KEY
Modos (entityImportMode)
| Modo | Quando | Comportamento |
|---|---|---|
manual | Padrão se omitir o campo | Entidade mínima com taxId + suggested_name (obrigatório). Sem pipeline de dados básicos (Nosis/CPF). Enrichments opcionais via autoExecuteIntegrations no form e/ou colunas CSV por linha. Sem depth / acionistas. País: qualquer ISO2 válido da plataforma (country_code por linha tem prioridade). Se os enrichments opcionais falharem, a entidade ainda é criada. |
automatic | Enviar entityImportMode=automatic | Mesmo pipeline que Criar entidade automática: dados básicos por tax ID (AR, BR ou CL) + enrichments extras (padrão todos ativos se omitir autoExecuteIntegrations) + depth opcional. Se dados básicos falharem, a entidade não é mantida. |
Valores legacy
manual_no_enrichment e automatic_enriched ainda são aceitos no request e normalizados para manual / automatic. A resposta usa os nomes canônicos.Se um enrichment falhar (por linha)
Cada linha do CSV é processada à parte. Padrão: a linha ficafailed e o job segue para a próxima. Com stopOnFirstError=true o lote para no primeiro erro (as linhas já criadas permanecem).
manual | automatic | |
|---|---|---|
| Equivale a | Alta manual do dashboard | POST /entities/automatic |
| Passo bloqueante | Insert com taxId + suggested_name | Enrichment de dados básicos daquele país e tipo |
| Dados básicos na Argentina | Não é usado | Nosis se estiver ativo no marketplace; senão o fallback do catálogo (em geral ar_arca_contribuyente_enrichment) |
| Falha a alta / dados básicos | A entidade não é criada; linha failed | O stub é descartado; a entidade não permanece; linha failed |
| Falham enrichments extras (ex.: BCRA depois de dados básicos OK) | A entidade permanece; a falha vai ao histórico de enrichments | A entidade permanece; a falha vai ao histórico (partial_success na alta). Não desfaz a linha. |
automatic, enrichments extras (BCRA na Argentina, etc.) só correm depois que dados básicos deram certo. Um erro de BCRA não aborta uma alta cujo passo de dados básicos já teve sucesso.
Padrão enviando só o CSV
curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer SUA_API_KEY' \
-F 'file=@bulk-entities-template.csv'
importMode: manual — entidade mínima, sem enrichments salvo envio explícito.
Manual com enrichments escolhidos
Mesma semântica do modo Manual do hub:curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer SUA_API_KEY' \
-F 'file=@bulk-entities-template.csv' \
-F 'entityImportMode=manual' \
-F 'autoExecuteIntegrations={"executeAllActiveEnrichments":false,"enrichments":["nosis_enrichment"]}' \
-F 'riskMatrixCompanyId=UUID_DA_MATRIZ'
Modo automático (explícito)
-F 'entityImportMode=automatic'
autoExecuteIntegrations no automático → todos os enrichments ativos da org.
Ação de matriz após a conclusão
O campo multipart opcionalpostImportActions aceita um array JSON. A ação run_risk_matrix_filtered enfileira uma execução em massa da matriz de risco quando o job chega a completed:
-F 'postImportActions=[{"type":"run_risk_matrix_filtered","filters":{"type":"company"},"riskMatrixCompanyId":"UUID_DA_MATRIZ","relatedEntitiesOfCreatedEntitiesOnly":true}]'
relatedEntitiesOfCreatedEntitiesOnly=true, a Gu1 avalia somente entidades vinculadas diretamente —como origem ou destino— a linhas cujo resultado neste arquivo foi created. filters.type define se as relacionadas devem ser company ou person, e a matriz correspondente é obrigatória. Linhas com skipped_existing ou failed são excluídas. Sem esse flag, filters é aplicado à lista completa de entidades da organização.
Como alternativa, envie sourceImportJobId com o ID de uma importação de entidades anterior e concluída. A Gu1 executa a matriz somente nas linhas created desse lote que correspondam a filters.type, inclusive entidades sem vínculo com as linhas do arquivo atual. sourceImportJobId e relatedEntitiesOfCreatedEntitiesOnly=true são mutuamente exclusivos. A importação anterior deve pertencer à mesma organização e ter seu relatório completo disponível.
Você também pode enviar onlyWithoutRiskMatrixExecution=true para avaliar todas as entidades de filters.type que ainda não tenham uma auditoria de execução de matriz. Depois que uma entidade é processada com sucesso, importações posteriores não voltam a incluí-la. Os três escopos (sourceImportJobId, entidades relacionadas e sem execução anterior) são mutuamente exclusivos.
CSV plataforma
Cabeçalhos mínimos:tax_id, type. Recomendado: suggested_name (obrigatório no manual). Ver País (ISO2) para country_code.
País (ISO2) — sempre obrigatório
Cada linha precisa de um país para criar a entidade (manual e automático). Informe em um ou ambos os lugares:| Fonte | Quando usar |
|---|---|
Campo do form country | Passo 2 do hub ou multipart na API. Obrigatório em CSV simples (só tax_id + type). Obrigatório em linhas sem country_code. |
Coluna CSV country_code (alias country) | Por linha. Substitui o country do lote quando presente. |
country_code na linha → country do lote.
Se nenhum estiver definido numa linha, o import falha com missing country antes de enfileirar.
| Modo | Países permitidos |
|---|---|
| Automático | AR, BR, CL |
| Manual | Qualquer ISO2 válido da plataforma |
- bulk-entities-template-automatic.csv — com
entityImportMode=automatic. Linhas demo AR/BR/CL,depth, enrichments. - bulk-entities-template-manual.csv — com
entityImportMode=manual(padrão). Linhas demo AR/MX/BR,suggested_nameobrigatório, semdepth.
apps/web/src/lib/bulk-automatic-entity-import-parse.ts.
Referência de colunas (CSV plataforma)
Cabeçalhos case-insensitive; espaços →_. Aliases entre parênteses.
| Coluna CSV | Alias | Campo API / entidade | Notas |
|---|---|---|---|
tax_id | taxId | taxId | Obrigatório. Normalizado por país. |
type | tipo | type | Obrigatório. person / company. |
country_code | country | country | ISO2 por linha. Substitui o country do lote. Coluna opcional no CSV quando o lote envia country (CSV simples) ou quando cada linha inclui country_code. País sempre obrigatório — coluna e/ou campo do lote. |
suggested_name | name, nombre | suggestedName | Nome para exibição. Obrigatório no manual em cada linha. |
gender | — | gender | Dado de criação. Enum: M, F, male, female, other, unknown. Use other para não binário. Ver Criar entidade — Person. |
external_id | externalId | externalId | ID externo. |
email | — | email | Email de contato. |
phone | — | phone | Telefone. |
registration_date | — | registrationDate | Data de registro (ISO). |
risk_matrix_id | — | riskMatrixId | UUID da matriz por linha. |
execute_all_active_enrichments | — | autoExecuteIntegrations.executeAllActiveEnrichments | true / false. |
enrichments | — | autoExecuteIntegrations.enrichments | Códigos separados por , ou ;. |
enrichment_group_refs | — | autoExecuteIntegrations.enrichmentGroupRefs | Slugs de grupos. |
omit_enrichments | exclude_enrichments | autoExecuteIntegrations.excludeEnrichments | Códigos a omitir do conjunto final. Funciona com execute_all_active_enrichments=true. Se for a única coluna de enrichment na linha, funde com a config do lote. |
create_relationships | — | createRelationships | Só modo automático. |
depth | — | depth | 0–5. Só automático (removido no manual). |
related_tax_id | — | relationships[].relatedTaxId | Contraparte existente por tax ID. Exatamente um de related_tax_id / related_external_id / related_entity_id por linha. |
related_external_id | — | relationships[].relatedExternalId | Contraparte por externalId. |
related_entity_id | — | relationships[].relatedEntityId | Contraparte por UUID. |
relationship_type | — | relationships[].relationshipType | Default shareholder se houver contraparte. Enum do grafo. |
relationship_role | — | relationships[].role | Papel em metadata.roles (ex. SOCIO). |
relationship_as_source | — | relationships[].asSource | Default true: a linha criada é source e a contraparte (related_*) é target. Com relationship_type=shareholder, a linha é acionista/sócia dessa contraparte. false inverte a direção. |
status | — | status | Status da entidade. |
attributes.<path> | — | attributes | Dado de negócio aninhado (notação com ponto, como CSV nativo de transações). Ex.: attributes.segment_tag. |
entityData.<path> | — | entityData.{person|company} | Perfil KYC/KYB. Sem person/company na cabeça → usa o type da linha. Ex.: entityData.income, entityData.tradeName. |
entityData.person.<path> / entityData.company.<path> | — | entityData.person / .company | Caminhos explícitos. |
metadata.<path> | — | attributes (legacy) | Deprecado; fundido em attributes. |
| Coluna sem prefixo | — | attributes | Retrocompat: segment_tag → attributes.segment_tag. |
Mesma entidade, vários vínculos (CSV): o CSV da plataforma admite uma relação por linha. Se a mesma pessoa/empresa aparecer em várias linhas com
related_* distintos, a Gu1 não recria a entidade (skip por tax_id duplicado), mas aplica o vínculo daquela linha. Se o edge (source → target + tipo) já existir, esse vínculo é omitido (idempotente). Alternativa em API/JSON: um único create com até 10 itens em relationships[].Removido (2026-06-04): as colunas CSV
execute_all_active_checks e checks não fazem mais parte do contrato de importação. Use enrichments, enrichment_group_refs e execute_all_active_enrichments. Ver Changelog.. geram objetos aninhados. Enrichments podem sobrescrever entityData; valores do CSV são reaplicados no fim (CSV prevalece em conflitos).
attributes: colunas attributes.*, metadata.* (legacy) ou sem prefixo. Form attributes (JSON) do lote funde com os da linha (linha prevalece).
Colunas de enrichment por linha aplicam em ambos modos; depth só em automatic.
Enrichments em relacionadas por linha (CSV plataforma)
Opcional — só modoautomatic. Prefixo relationship_ (alias plural relationships_).
| Coluna | Descrição |
|---|---|
relationship_execute_all_active_enrichments | true = todos os enrichments ativos; false = só dados básicos. Substitui a política do lote (childEnrichmentPolicy) nessa linha. |
relationship_enrichments_company | Códigos de provedor para filhos tipo empresa (separados por , ou ;) |
relationship_enrichments_person | Códigos para filhos tipo pessoa |
relationship_enrichment_group_refs | Grupos do marketplace (opcional) |
relationship_omit_enrichments | Alias de relationship_exclude_enrichments. Códigos a omitir (também com execute_all_active=true). Se for a única coluna relationship_* na linha, funde com a política do lote. |
relationship_exclude_enrichments | Igual a relationship_omit_enrichments (nome legado). |
relationship_execute_all_active_enrichments do CSV para aplicar a política do formulário. Use relationship_omit_enrichments por linha só para exceções.
Exemplo omit em acionistas:
tax_id,type,country_code,depth,relationship_omit_enrichments
67250861000107,company,BR,1,global_gueno_sanctions_enrichment
tax_id + type): envie country (ISO2) no form do lote — obrigatório.
Campos do formulário
| Campo | Obrigatório | Descrição |
|---|---|---|
file | Sim | CSV |
country | Condicional (obrigatório na prática) | ISO2 do lote. Obrigatório se o CSV não traz country_code numa linha. Fallback opcional se todas as linhas incluem country_code. |
entityImportMode | Não | manual (padrão) ou automatic |
stopOnFirstError | Não | true / false. Padrão false: tenta cada linha; falhas vão ao relatório do job. true: para na primeira linha com falha; as altas anteriores permanecem. |
autoExecuteIntegrations | Não | JSON — manual: opcional; automático: padrão todos ativos |
riskMatrixPersonId / CompanyId | Não | UUID — ambos modos |
monitoring | Não | JSON — ambos modos |
autoExecuteIntegrationsShareholders | Não | JSON no lote — automático + depth > 0. Por linha: colunas relationship_* no CSV ou campo no bulk JSON. |
childEnrichmentPolicy | Não | all_active (padrão), by_root_type ou basic_only — ver Enrichments nos filhos e monitoramento. |
monitoringApplyToRelationships | Não | true / false — se false, monitoring só nas entidades principais. Padrão true com depth > 0 se omitido. |
depth | Não | 0–5 — só automático |
monitoring | Não | JSON — ambos modos |
Enrichments nos filhos e monitoramento
ComentityImportMode=automatic e depth > 0 são criados acionistas (raiz empresa) ou entidades relacionadas (raiz pessoa):
childEnrichmentPolicy | Entidade principal | Empresa → acionistas | Pessoa → relacionadas |
|---|---|---|---|
all_active (padrão) | Conforme config | Todos os enrichments ativos do tipo do filho | Igual |
by_root_type | Conforme config | Todos os ativos exceto global_gueno_sanctions_enrichment | Só dados básicos do snapshot do provedor da raiz |
basic_only | Conforme config | Só dados básicos | Só dados básicos |
monitoringApplyToRelationships: com false, o JSON monitoring vale só para a entidade principal. Recomendado false com by_root_type.
-F 'entityImportMode=automatic' \
-F 'depth=1' \
-F 'childEnrichmentPolicy=by_root_type' \
-F 'monitoringApplyToRelationships=false' \
-F 'monitoring={"main":{"global_gueno_sanctions_enrichment":{"watchlist":true}}}'
autoExecuteIntegrationsShareholders por linha no bulk JSON ou colunas relationship_* no CSV ainda prevalece sobre a política do lote para esse item.
Manual vs automático
| Manual | Automático | |
|---|---|---|
| Equivale à alta unitária | Criar entidade (manual) | Criar entidade automática |
| Dados básicos por tax ID (Nosis/CPF / Chile; AR fallback ARCA) | Não | Sim — bloqueante |
| Se dados básicos falharem | N/A (não há esse passo) | Não há entidade nessa linha; segue a próxima (salvo stopOnFirstError) |
| Se enrichments extras falharem | A entidade permanece | A entidade permanece |
suggested_name | Obrigatório | Recomendado |
| País (ISO2) | Obrigatório — country do lote e/ou country_code por linha (linha prevalece) | Igual (automático: só AR, BR, CL) |
| Enrichments | Opcionais | Padrão todos ativos |
depth | Não | Sim (0–5) |
| Países | Qualquer ISO2 válido | AR, BR, CL |
Limites
| Valor | |
|---|---|
| Arquivos por request | 1 CSV (campo file) |
| Máx. linhas por import | Conforme plano, com teto rígido de 20.000: Freemium 4.000 → Startup 12.000 → Growth / Enterprise / Usage based 20.000. Veja overview — Limites por plano. |
| Teto servidor (opcional) | BULK_AUTOMATIC_ENTITY_MAX_ITEMS só pode reduzir o limite efetivo (nunca subir acima de 20.000) |
| Acima do limite | 400 TOO_MANY_ITEMS |
| Já há um job de entidades vivo na org | 409 JOB_IN_PROGRESS (um import de entidades queued/running por organização) |
| Já há um lote de transações na fila | 409 JOB_ALREADY_WAITING (no máximo um job em espera por organização) |
| Há um lote de transações running (e ninguém esperando) | 202 queued (code: "QUEUED_WAITING_PREVIOUS_JOB", queue.waitingForOrgJob: true); começa quando esse job termina |
| Vagas globais ocupadas | 202 com code: "QUEUED_WAITING_SLOT", status: "queued" e queue (máx. 2 orgs processando entidades ao mesmo tempo; o seu espera) |
Was this page helpful?