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_bodyReferencia API
Importar entidades (CSV)
Sube un CSV y encola import bulk de entidades — formato plataforma sin mappingId o columnas custom con mappingId. Default manual; 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
Descripción
Content-Type:multipart/form-data.
Encola el mismo job bulk que el hub Importaciones masivas. Requiere entities:bulk_import y la flag org de importación masiva automática. Respuesta 202 con jobId e importMode efectivo.
Autenticación
Authorization: Bearer TU_API_KEY
Modos de importación (entityImportMode)
| Modo | Cuándo | Comportamiento |
|---|---|---|
manual | Default si omitís el campo | Entidad mínima con taxId + suggested_name (obligatorio). Sin pipeline de datos básicos (Nosis/CPF). Enrichments opcionales vía autoExecuteIntegrations en el form y/o columnas CSV por fila. Sin depth / accionistas. País: cualquier ISO2 válido de plataforma (prioridad country_code por fila). Si los enrichments opcionales fallan, la entidad igual se crea. |
automatic | Enviás entityImportMode=automatic | Mismo pipeline que Crear entidad automática: datos básicos por tax ID (AR, BR o CL) + enrichments extra (default todos activos si omitís autoExecuteIntegrations) + depth / accionistas opcional. Si datos básicos fallan, la entidad no se conserva. |
Los valores legacy
manual_no_enrichment y automatic_enriched siguen aceptándose en el request y se normalizan a manual / automatic. La respuesta usa los nombres canónicos.Si un enrichment falla (por fila)
Cada fila del CSV se procesa por separado. Default: la fila queda enfailed y el job sigue con la siguiente. Con stopOnFirstError=true se corta en el primer fallo (las filas ya creadas se mantienen).
manual | automatic | |
|---|---|---|
| Equivale a | Alta manual del dashboard | POST /entities/automatic |
| Paso bloqueante | Insert con taxId + suggested_name | Enrichment de datos básicos de ese país y tipo |
| Datos básicos en Argentina | No se usa | Nosis si está activo en el marketplace; si no, el fallback del catálogo (en general ar_arca_contribuyente_enrichment) |
| Falla el alta / datos básicos | La entidad no se crea; fila failed | Se descarta el stub; la entidad no queda; fila failed |
| Fallan enrichments extra (p. ej. BCRA después de datos básicos OK) | La entidad queda; el fallo va al historial de enrichments | La entidad queda; el fallo va al historial (partial_success en el alta). No se deshace la fila. |
automatic, los enrichments extra (BCRA en Argentina, etc.) corren solo si datos básicos salieron bien. Un error de BCRA no aborta un alta cuyo paso de datos básicos ya fue exitoso.
Default si mandás solo el CSV
curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer TU_API_KEY' \
-F 'file=@bulk-entities-template.csv'
importMode: manual — entidad mínima, sin enrichments salvo que los agregues explícitamente.
Manual con enrichments elegidos
Misma semántica que el modo Manual del hub:curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer TU_API_KEY' \
-F 'file=@bulk-entities-template.csv' \
-F 'entityImportMode=manual' \
-F 'autoExecuteIntegrations={"executeAllActiveEnrichments":false,"enrichments":["nosis_enrichment"]}' \
-F 'riskMatrixCompanyId=UUID_DE_TU_MATRIZ'
monitoring JSON (solo entidad principal en manual).
Modo automático (explícito)
curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
-H 'Authorization: Bearer TU_API_KEY' \
-F 'file=@bulk-entities-template.csv' \
-F 'entityImportMode=automatic'
autoExecuteIntegrations en automático → todos los enrichments activos de la org.
Con depth > 0 podés enviar autoExecuteIntegrationsShareholders (JSON) para accionistas.
Manual sin reglas post-creación
-F 'entityImportMode=manual' \
-F 'skipRulesExecution=true'
entityImportMode — ya es manual por default.)
Acción de matriz al finalizar
El campo multipart opcionalpostImportActions acepta un array JSON. La acción run_risk_matrix_filtered encola una ejecución masiva de matriz cuando el job termina en completed:
-F 'postImportActions=[{"type":"run_risk_matrix_filtered","filters":{"type":"company"},"riskMatrixCompanyId":"UUID_DE_TU_MATRIZ","relatedEntitiesOfCreatedEntitiesOnly":true}]'
relatedEntitiesOfCreatedEntitiesOnly=true, Gu1 evalúa únicamente entidades vinculadas directamente —como origen o destino— con filas cuyo resultado en este archivo fue created. filters.type define si las relacionadas deben ser company o person, y se requiere la matriz correspondiente a ese tipo. No incluye filas skipped_existing ni failed. Sin el flag, filters se aplica al listado completo de entidades de la organización.
Como alternativa, enviá sourceImportJobId con el ID de una importación de entidades anterior y completada. Gu1 ejecutará la matriz únicamente sobre las filas created de ese lote que coincidan con filters.type, incluso si no están relacionadas con las filas del archivo actual. sourceImportJobId y relatedEntitiesOfCreatedEntitiesOnly=true son mutuamente excluyentes. La importación anterior debe pertenecer a la misma organización y tener disponible su reporte completo.
También podés enviar onlyWithoutRiskMatrixExecution=true para evaluar todas las entidades de filters.type que todavía no tengan ninguna auditoría de ejecución de matriz. Cuando una entidad se procesa correctamente, las cargas posteriores ya no vuelven a incluirla. Los tres alcances (sourceImportJobId, relacionados y sin ejecución previa) son mutuamente excluyentes.
CSV formato plataforma (sin mappingId)
Cabeceras mínimas: tax_id, type. Recomendado: suggested_name (obligatorio en manual). Ver País (ISO2) para country_code.
País (ISO2) — siempre obligatorio
Cada fila necesita un país para crear la entidad (manual y automático). Podés indicarlo en uno o ambos lugares:| Fuente | Cuándo usarla |
|---|---|
Campo del form country | Paso 2 del hub o campo multipart en la API. Obligatorio en CSV simple (solo tax_id + type). Obligatorio en filas sin country_code. |
Columna CSV country_code (alias country) | Por fila. Pisa el country del lote cuando está presente. |
country_code en la fila → country del lote.
Si ninguno está definido en una fila, el import falla con missing country antes de encolar el job.
| Modo | Países permitidos |
|---|---|
Automático (automatic) | AR, BR, CL (pipeline datos básicos) |
Manual (manual) | Cualquier ISO2 válido de plataforma |
- CSV simple, todo AR → cabeceras
tax_id,type+ formcountry=AR. - CSV avanzado, países mixtos →
country_codeen cada fila (countrydel lote opcional como respaldo). - CSV avanzado, un solo país → todas las filas con
country_code=ARo formcountry=ARsin la columna.
- bulk-entities-template-automatic.csv — con
entityImportMode=automatic. Filas demo AR/BR/CL,depth, enrichments. - bulk-entities-template-manual.csv — con
entityImportMode=manual(default). Filas demo AR/MX/BR,suggested_nameobligatorio, sindepth.
apps/web/src/lib/bulk-automatic-entity-import-parse.ts.
tax_id,type,country_code,suggested_name,...,execute_all_active_enrichments,...,depth,status,segment_tag
20123456789,company,AR,Acme Argentina SA,...,true,...,0,under_review,retail
tax_id,type,country_code,suggested_name,...,status,segment_tag
20123456789,company,AR,Empresa Manual AR SA,...,under_review,retail
XAXX010101000,company,MX,Empresa México Demo SA,...,active,latam
Referencia de columnas (CSV plataforma)
Cabeceras sin distinguir mayúsculas; espacios →_. Alias entre paréntesis.
| Columna CSV | Alias | Campo API / entidad | Notas |
|---|---|---|---|
tax_id | taxId | taxId | Obligatorio. Se normaliza por país. |
type | tipo | type | Obligatorio. person / company (persona, empresa, pf, pj). |
country_code | country | country | ISO2 por fila. Pisa el country del form del lote. La columna es opcional en el CSV si enviás country en el lote (CSV simple) o si cada fila trae country_code. El país siempre es obligatorio — columna y/o campo del lote. |
suggested_name | name, nombre | suggestedName | Nombre para mostrar. Obligatorio en manual en cada fila. |
gender | — | gender | Dato de creación (customData). Enum: M, F, male, female, other, unknown. Usar other para no binario. Ver Crear entidad — Persona. |
external_id | externalId | externalId | ID externo de la entidad. |
email | — | email | Email de contacto. |
phone | — | phone | Teléfono de contacto. |
registration_date | — | registrationDate | Fecha de registro (ISO). |
risk_matrix_id | — | riskMatrixId | UUID de matriz por fila; vacío / null limpia. Pisa matrices del lote si viene informado. |
execute_all_active_enrichments | — | autoExecuteIntegrations.executeAllActiveEnrichments | true / false. Aplica enrichments por fila si esta columna, enrichments o enrichment_group_refs están presentes. |
enrichments | — | autoExecuteIntegrations.enrichments | Códigos de proveedor separados por , o ;. |
enrichment_group_refs | — | autoExecuteIntegrations.enrichmentGroupRefs | Slugs de grupos de enrichment. |
omit_enrichments | exclude_enrichments | autoExecuteIntegrations.excludeEnrichments | Códigos a omitir del conjunto final. Funciona con execute_all_active_enrichments=true (todos los activos menos estos). Si es la única columna de enrichment en la fila, se suma a la config del lote (no la reemplaza). |
create_relationships | — | createRelationships | Solo modo automático (ignorado en manual). |
depth | — | depth | Entero 0–5. Accionistas/relaciones. Solo automático (se elimina en manual). |
related_tax_id | — | relationships[].relatedTaxId | Contraparte existente por tax ID. Exactamente uno de related_tax_id / related_external_id / related_entity_id por fila. |
related_external_id | — | relationships[].relatedExternalId | Contraparte por externalId. |
related_entity_id | — | relationships[].relatedEntityId | Contraparte por UUID. |
relationship_type | — | relationships[].relationshipType | Default shareholder si hay contraparte. Enum del grafo. |
relationship_role | — | relationships[].role | Rol en metadata.roles (ej. SOCIO). |
relationship_as_source | — | relationships[].asSource | Default true: la fila creada es source y la contraparte (related_*) es target. Con relationship_type=shareholder, la fila es accionista/socio de esa contraparte. false invierte la dirección. |
status | — | status | active, under_review, pending_verification, awaiting_information, blocked, etc. |
attributes.<path> | — | attributes | Dato de negocio anidado (misma idea que transacciones con puntos). Ej.: attributes.segment_tag, attributes.tags.tier. |
entityData.<path> | — | entityData.{person|company} | Perfil KYC/KYB. Sin person/company en la cabecera → usa el type de la fila (person → entityData.person.*, company → entityData.company.*). Ej.: entityData.income, entityData.tradeName. |
entityData.person.<path> | — | entityData.person | Explícito para persona (ignora mismatch con type=company en la misma fila). |
entityData.company.<path> | — | entityData.company | Explícito para empresa. |
metadata.<path> | — | attributes (legacy) | Deprecado; se fusiona en attributes. Preferí attributes.*. |
| Columna sin prefijo | — | attributes | Retrocompat: segment_tag → attributes.segment_tag. |
Misma entidad, varios vínculos (CSV): el CSV plataforma admite una relación por fila. Si la misma persona/empresa aparece en varias filas con distinto
related_*, Gu1 no recrea la entidad (skip por tax_id duplicado) pero sí aplica el vínculo de esa fila. Si el edge (source → target + tipo) ya existe, se omite ese vínculo (idempotente). Alternativa en API/JSON: un solo create con hasta 10 ítems en relationships[].Eliminado (2026-06-04): las columnas CSV
execute_all_active_checks y checks ya no forman parte del contrato de importación. Usá enrichments, enrichment_group_refs y execute_all_active_enrichments. Ver Changelog.. generan objetos anidados. Enriquecimientos pueden sobrescribir entityData; los valores del CSV se re-aplican al final (el CSV gana en conflictos).
Qué va a attributes: columnas attributes.*, metadata.* (legacy) o sin prefijo. El form attributes (JSON) del lote se fusiona con los de fila (gana la fila en conflicto de clave).
CSV simple (solo tax_id + type): enviá country (ISO2) en el form del lote — obligatorio. No hace falta columna country_code.
CSV custom: requiere mappingId (mapeo guardado en el dashboard).
- Columnas de enrichment por fila aplican en ambos modos;
depth/ accionistas solo enautomatic.
Enrichments en relacionados por fila (CSV plataforma)
Opcional — solo modoautomatic. Prefijo relationship_ (alias plural relationships_).
| Columna | Descripción |
|---|---|
relationship_execute_all_active_enrichments | true = todos los activos en accionistas/relacionadas; false = solo datos básicos. Reemplaza la política del lote (childEnrichmentPolicy) para esa fila. |
relationship_enrichments_company | Códigos de proveedor para hijos tipo empresa (separados por , o ;) |
relationship_enrichments_person | Códigos para hijos tipo persona |
relationship_enrichment_group_refs | Grupos de marketplace (opcional) |
relationship_omit_enrichments | Alias de relationship_exclude_enrichments. Códigos a omitir del conjunto final (también con execute_all_active=true). Si es la única columna relationship_* en la fila, se fusiona con la política del lote en lugar de reemplazarla. |
relationship_exclude_enrichments | Igual que relationship_omit_enrichments (nombre legacy). |
childEnrichmentPolicy custom: omití relationship_execute_all_active_enrichments del CSV si querés que aplique la política del formulario paso 2. Usá relationship_omit_enrichments por fila solo para excepciones puntuales.
Ejemplo omit en accionistas (all active del lote, menos sanciones globales en hijos):
tax_id,type,country_code,depth,relationship_omit_enrichments
67250861000107,company,BR,1,global_gueno_sanctions_enrichment
CSV custom
Columnas distintas al formato plataforma →mappingId obligatorio.
Campos del formulario
| Campo | Obligatorio | Descripción |
|---|---|---|
file | Sí | CSV |
mappingId | Condicional | Custom; opcional con formato plataforma |
entityImportMode | No | manual (default) o automatic |
country | Condicional (obligatorio en la práctica) | ISO2 del lote. Obligatorio si el CSV no trae country_code en una fila (CSV simple típico). Respaldo opcional si todas las filas incluyen country_code. |
riskMatrixPersonId | No | UUID — ambos modos |
riskMatrixCompanyId | No | UUID — ambos modos |
skipRulesExecution | No | true / false |
stopOnFirstError | No | true / false. Default false: se intenta cada fila; los fallos van al reporte del job. true: se corta en la primera fila fallida; las altas anteriores se mantienen. |
autoExecuteIntegrations | No | JSON — manual: enrichments opcionales; automático: default todos activos |
autoExecuteIntegrationsShareholders | No | JSON a nivel lote — solo automático + depth > 0. Por fila: columnas relationship_* en CSV o campo en bulk JSON. |
childEnrichmentPolicy | No | all_active (default), by_root_type o basic_only — ver Enrichments en hijos y monitoreo. |
monitoringApplyToRelationships | No | true / false — si false, monitoring solo en entidades principales. Default true con depth > 0 si se omite. |
depth | No | 0–5 — solo automático |
monitoring | No | JSON — ambos modos |
reportRecipientEmails | No | JSON array |
emailLocale | No | en / es / pt |
Enrichments en hijos y monitoreo
ConentityImportMode=automatic y depth > 0 se crean accionistas (raíz empresa) o entidades relacionadas (raíz persona). Dos campos del lote controlan enrichments y watchlist en esos hijos:
childEnrichmentPolicy | Entidad principal | Empresa → accionistas | Persona → relacionadas |
|---|---|---|---|
all_active (default) | Según config | Todos los enrichments activos del tipo del hijo | Igual |
by_root_type | Según config | Todos los activos excepto global_gueno_sanctions_enrichment | Solo datos básicos del snapshot del proveedor de la raíz |
basic_only | Según config | Solo datos básicos | Solo datos básicos |
monitoringApplyToRelationships: con false, el JSON monitoring aplica solo a la entidad principal (monitoring.main). Recomendado false con by_root_type cuando la raíz entra a monitoreo de sanciones pero los hijos no.
Ejemplo (CSV mixto, depth 1):
-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 fila en bulk JSON o columnas relationship_* en CSV sigue pisando la política del lote para ese ítem.
Manual vs automático
| Manual | Automático | |
|---|---|---|
| Equivale al alta unitaria | Crear entidad (manual) | Crear entidad automática |
| Datos básicos por tax ID (Nosis/CPF / Chile; AR fallback ARCA) | No | Sí — bloqueante |
| Si fallan datos básicos | N/A (no hay ese paso) | No hay entidad en esa fila; sigue la siguiente (salvo stopOnFirstError) |
| Si fallan enrichments extra | La entidad queda | La entidad queda |
suggested_name | Obligatorio | Recomendado |
| País (ISO2) | Obligatorio — country del lote y/o country_code por fila (gana la fila) | Igual (automático: solo AR, BR, CL) |
| Enrichments | Opcionales | Default todos activos |
| Matrices de riesgo | Sí | Sí |
depth accionistas | No | Sí (0–5) |
| Países | Cualquier ISO2 válido | AR, BR, CL |
Límites
| Valor | |
|---|---|
| Archivos por request | 1 CSV (campo file) |
| Máx. filas por import | Según plan de la org, con tope duro de 20.000: Freemium 4.000 → Startup 12.000 → Growth / Enterprise / Usage based 20.000. Ver overview — Límites por plan. |
| Tope servidor (opcional) | BULK_AUTOMATIC_ENTITY_MAX_ITEMS solo puede bajar el límite efectivo (nunca subir de 20.000) |
| Supera límite | 400 TOO_MANY_ITEMS |
| Ya hay un job de entidades vivo en la org | 409 JOB_IN_PROGRESS (un import de entidades queued/running por organización) |
| Ya hay un lote de transacciones en cola | 409 JOB_ALREADY_WAITING (como máximo un job en espera por organización) |
| Hay un lote de transacciones running (y nadie esperando) | 202 queued (code: "QUEUED_WAITING_PREVIOUS_JOB", queue.waitingForOrgJob: true); arranca cuando ese job termina |
| Cupos globales ocupados | 202 con code: "QUEUED_WAITING_SLOT", status: "queued" y queue (máx. 2 orgs procesando entidades a la vez; el tuyo espera) |
Default si omitís modo
| Endpoint | Default |
|---|---|
POST /batch-import/import/entities | manual |
Hub vs API
| Flujo | Endpoint | Default |
|---|---|---|
| Pantalla Entidades | Este endpoint (POST /batch-import/import/entities) | UI (automático → entityImportMode=automatic) |
| API multipart | POST /batch-import/import/entities | Manual |
| Custom | POST /batch-import/import/entities + mappingId | Selector UI |
Was this page helpful?