Crear una entidad empresa

curl --request POST \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "externalId": "<string>",
  "name": "<string>",
  "countryCode": "<string>",
  "taxId": "<string>",
  "operationalHours": {},
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "monitoring": {}
}
'

{
  "success": true,
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

POST

entities

curl --request POST \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "externalId": "<string>",
  "name": "<string>",
  "countryCode": "<string>",
  "taxId": "<string>",
  "operationalHours": {},
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "monitoring": {}
}
'

{
  "success": true,
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

Descripción general

Crea una nueva entidad de empresa con los atributos especificados. Las entidades de empresa representan organizaciones comerciales que deseas analizar en términos de riesgo y cumplimiento (KYB).

Endpoint

POST http://api.gu1.ai/entities

Autenticación

Requiere una clave API válida en el encabezado Authorization:

Authorization: Bearer YOUR_API_KEY

Cuerpo de la solicitud

type

string

required

Debe ser company para crear una entidad de empresa

externalId

string

required

Tu identificador único para esta empresa en tu sistema

name

string

required

Nombre para mostrar de la empresa

countryCode

string

required

Código de país ISO 3166-1 alpha-2 (ej., “US”, “BR”, “AR”)

taxId

string

Número de identificación fiscal (validado según el país)

📋 Ver Formatos de Tax ID por País para formatos aceptados y reglas de validación para cada país.

operationalHours

object | null

Horario operativo opcional en raíz para reglas KYT. Misma forma que en Crear entidad: timezone + weekly.

attributes

object

Atributos personalizados como pares clave-valor

entityData

object

required

Estructura de datos específica de la empresa (ver abajo)

registrationDate

string

Fecha de registro de la empresa en formato ISO 8601 datetime (ej., “2024-01-15T10:30:00Z”)

isClient

boolean

default:"false"

Marcar esta empresa como cliente para fines de seguimiento

riskMatrixId

string | string[]

Uno o más UUIDs de matrices de riesgo (legacy: un solo UUID). Si se envían, tras la creación el sistema evalúa la empresa solo contra reglas activas de esas matrices (salvo skipRulesExecution: true). Misma semántica que riskMatrixIds cuando enviás un único id como string. Ver Ejecución de Matriz de Riesgo abajo.

riskMatrixIds

string[]

Forma preferida para varias matrices: lista ordenada de UUIDs de tu organización. Si viene informada y no vacía, tiene precedencia sobre riskMatrixId.

skipRulesExecution

boolean

default:"false"

Omitir la ejecución automática de reglas después de la creación de la empresa. Use esto para crear la entidad primero y activar las reglas manualmente más tarde.

status

string

default:"under_review"

Estado inicial de la empresa. Opciones:

active - Empresa activa
inactive - Empresa inactiva
blocked - Empresa bloqueada
under_review - Empresa bajo revisión (predeterminado)
suspended - Empresa suspendida
expired - Registro de empresa expirado
deleted - Eliminación lógica
rejected - Empresa rechazada

autoExecuteIntegrations

object

Configurar la ejecución automática de enriquecimientos al crear la empresa.Estructura:

{
  "executeAllActiveEnrichments": false,
  "enrichments": [
    "ar_nosis_extended_verification_enrichment",
    "ar_bcra_deudas_enrichment",
    "global_gueno_sanctions_enrichment"
  ],
  "excludeEnrichments": []
}

Propiedades:

executeAllActiveEnrichments (boolean) - Ejecutar todas las integraciones de enriquecimiento activas configuradas en su organización
enrichments (string[]) - Array de códigos específicos de proveedores de enriquecimiento a ejecutar

Ejemplos de códigos válidos (empresa AR — deben coincidir con los valores string de ValidProviderCodesEnum):

ar_nosis_extended_verification_enrichment — enriquecimiento NOSIS extendido
ar_bcra_deudas_enrichment — deudas BCRA
ar_repet_entity_enrichment — REPET / listas (empresa)
global_complyadvantage_sanctions_enrichment — ComplyAdvantage sanciones
global_gueno_sanctions_enrichment — sanciones Gu1 (si está configurado)

Ver Códigos de proveedores y la referencia completa en provider-codes.

monitoring

object

Opcional. Igual que en Crear entidad: usá monitoring.main con global_gueno_sanctions_enrichment: true para lista vigilada cuando ese enriquecimiento corre desde autoExecuteIntegrations. Solo está soportado ese código hoy. Requiere monitoreo habilitado en Marketplace. Ejemplos: Crear entidad — ejemplo Gu1.

Monitoreo de sanciones Gu1 (empresa)

{
  "type": "company",
  "externalId": "co_screening_001",
  "name": "Tech Solutions S.A.",
  "countryCode": "AR",
  "taxId": "30-71000001-2",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "tradeName": "Tech Solutions",
      "industry": "Software"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": true
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": ["global_gueno_sanctions_enrichment"],
  }
}

Estructura de datos de la entidad empresa

El objeto entityData.company debe contener:

{
  "company": {
    "legalName": "string",
    "tradeName": "string",
    "incorporationDate": "YYYY-MM-DD",
    "companySubtype": "merchant | investment_fund | holding | bank | payment_processor | other",
    "industry": "string",
    "websiteUrl": "string",
    "employeeCount": number,
    "revenue": number,
    "revenueCurrency": "string",
    "contactInfo": {
      "email": "string",
      "phone": "string",
      "alternativePhone": "string"
    },
    "address": "string | object (ver nota de Formato de dirección)",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string"
  }
}

Formato de dirección: El campo address admite ambos formatos:

Formato de cadena (simple): "Av. Paulista, 1000, São Paulo, SP, Brazil"

Formato de objeto (estructurado):

{
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Suite 200",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "Brazil",
  "postalCode": "01310-100"
}

Ejecución de Matriz de Riesgo

Puede ejecutar automáticamente una o más matrices de riesgo (reglas de cumplimiento KYB) al crear una empresa proporcionando riskMatrixId o riskMatrixIds.

Cómo funciona

Obtenga su(s) ID(s) de Matriz de Riesgo desde el panel de gu1 (formato: UUID)
Incluya riskMatrixId o riskMatrixIds en su solicitud de creación
El sistema automáticamente:
- Crea la entidad empresa
- Ejecuta todas las reglas KYB en la matriz
- Calcula el puntaje de riesgo
- Genera alertas de cumplimiento si es necesario
- Actualiza el estado de la empresa según los resultados

Ejemplo con Matriz de Riesgo

{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech",
      "revenue": 5000000
    }
  }
}

Ejemplo con varias matrices de riesgo

{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech"
    }
  }
}

Combinado con enriquecimientos y monitoreo Gu1

{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": [
      "ar_nosis_extended_verification_enrichment",
      "ar_bcra_deudas_enrichment",
      "global_gueno_sanctions_enrichment"
    ]
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    }
  },
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "industry": "fintech"
    }
  }
}

Ver el detalle de monitoring en Crear entidad.

Respuesta

success

boolean

Indica si la empresa se creó exitosamente

entity

object

El objeto de empresa creado incluyendo:

id - ID interno de gu1
externalId - Tu ID externo
organizationId - ID de tu organización
type - Siempre “company”
name - Nombre de la empresa
riskScore - Puntuación de riesgo inicial (0-100)
status - Estado de la empresa
entityData - Datos específicos de la empresa
attributes - Atributos personalizados
createdAt - Marca de tiempo de creación
updatedAt - Marca de tiempo de última actualización

rulesResult

object

Resultado de la ejecución de reglas (solo presente cuando se ejecutaron reglas, p. ej. cuando skipRulesExecution es false y hay matriz de riesgo configurada), incluyendo:

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.

rulesExecutionSummary

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). Resumen de qué reglas hicieron match (hit) vs no (no hit), acciones ejecutadas y puntuación total. Omitido cuando las reglas no se ejecutaron.

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, 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.

Ejemplo de solicitud

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "externalId": "company_789",
    "name": "Tech Solutions S.A.",
    "countryCode": "BR",
    "taxId": "12.345.678/0001-90",
    "entityData": {
      "company": {
        "legalName": "Tech Solutions Sociedade Anônima",
        "tradeName": "Tech Solutions",
        "incorporationDate": "2020-06-15",
        "industry": "Software Development",
        "employeeCount": 50,
        "revenue": 5000000,
        "revenueCurrency": "BRL",
        "contactInfo": {
          "email": "contact@techsolutions.com.br",
          "phone": "+55 11 3456-7890"
        },
        "address": "Av. Paulista, 1000",
        "city": "São Paulo",
        "state": "SP",
        "country": "Brazil",
        "postalCode": "01310-100"
      }
    },
    "attributes": {
      "website": "https://techsolutions.com.br",
      "partnershipTier": "gold"
    }
  }'

Ejemplo de respuesta

{
  "success": true,
  "entity": {
    "id": "660e9511-f39c-52e5-b827-557766551111",
    "externalId": "company_789",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "company",
    "name": "Tech Solutions S.A.",
    "taxId": "12.345.678/0001-90",
    "countryCode": "BR",
    "riskScore": 35,
    "status": "active",
    "entityData": {
      "company": {
        "legalName": "Tech Solutions Sociedade Anônima",
        "tradeName": "Tech Solutions",
        "incorporationDate": "2020-06-15",
        "industry": "Software Development",
        "employeeCount": 50,
        "revenue": 5000000,
        "revenueCurrency": "BRL"
      }
    },
    "attributes": {
      "website": "https://techsolutions.com.br",
      "partnershipTier": "gold"
    },
    "createdAt": "2024-10-03T15:00:00.000Z",
    "updatedAt": "2024-10-03T15:00:00.000Z"
  }
}

Respuestas de error

400 Bad Request - Tax ID inválido

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid CNPJ format. Please check the format and try again.",
    "details": {
      "field": "taxId",
      "taxIdName": "CNPJ",
      "providedValue": "12.345.678/0001-90"
    }
  },
  "entity": null
}

400 Bad Request - Campos requeridos faltantes

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields for company creation",
    "details": {
      "missingFields": ["legalName", "industry"],
      "requiredFields": ["legalName", "tradeName", "industry", "incorporationDate"],
      "countryCode": "BR"
    }
  },
  "entity": null
}

409 Conflict - Entidad duplicada

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Entity with this external_id already exists",
    "details": {
      "field": "external_id",
      "value": "company_789",
      "constraint": "entities_organization_external_id_unique"
    }
  },
  "entity": null
}

401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "INVALID_KEY"
}

Próximos pasos

Después de crear una empresa, puedes:

Obtener detalles de empresa - Recuperar información completa de la empresa
Listar empresas - Consultar tus empresas
Actualizar empresa - Modificar datos de la empresa
Crear validación KYB - Iniciar proceso de verificación KYB

Formatos de Tax ID por País Crear una empresa automáticamente con enriquecimiento

⌘I

​Descripción general

​Endpoint

​Autenticación

​Cuerpo de la solicitud

​Monitoreo de sanciones Gu1 (empresa)

​Estructura de datos de la entidad empresa

​Ejecución de Matriz de Riesgo

​Cómo funciona

​Ejemplo con Matriz de Riesgo

​Ejemplo con varias matrices de riesgo

​Combinado con enriquecimientos y monitoreo Gu1

​Respuesta

​Ejemplo de solicitud

​Ejemplo de respuesta

​Respuestas de error

​400 Bad Request - Tax ID inválido

​400 Bad Request - Campos requeridos faltantes

​409 Conflict - Entidad duplicada

​401 Unauthorized

​Próximos pasos

Descripción general

Endpoint

Autenticación

Cuerpo de la solicitud

Monitoreo de sanciones Gu1 (empresa)

Estructura de datos de la entidad empresa

Ejecución de Matriz de Riesgo

Cómo funciona

Ejemplo con Matriz de Riesgo

Ejemplo con varias matrices de riesgo

Combinado con enriquecimientos y monitoreo Gu1

Respuesta

Ejemplo de solicitud

Ejemplo de respuesta

Respuestas de error

400 Bad Request - Tax ID inválido

400 Bad Request - Campos requeridos faltantes

409 Conflict - Entidad duplicada

401 Unauthorized

Próximos pasos