Esquemas Personalizados

Descripción General

Los Esquemas Personalizados te permiten definir la estructura de tus datos antes de importarlos a gu1. Cada esquema describe los campos, tipos, reglas de validación y metadatos para tu fuente de datos.

Los esquemas son específicos de la organización y pueden marcarse como públicos para compartirlos en toda tu organización.

Crear Esquema

Crea un nuevo esquema personalizado para tu fuente de datos.

curl -X POST http://api.gu1.ai/custom-schemas \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate KYB Data",
    "version": "1.0.0",
    "description": "Company information for KYB analysis",
    "type": "database",
    "category": "financial",
    "schemaData": {
      "fields": [
        {
          "name": "company_name",
          "type": "string",
          "required": true,
          "description": "Legal company name"
        },
        {
          "name": "tax_id",
          "type": "string",
          "required": true,
          "description": "Tax identification number"
        }
      ]
    },
    "isPublic": false
  }'

const response = await fetch('http://api.gu1.ai/custom-schemas', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Corporate KYB Data',
    version: '1.0.0',
    description: 'Company information for KYB analysis',
    type: 'database',
    category: 'financial',
    schemaData: {
      fields: [
        {
          name: 'company_name',
          type: 'string',
          required: true,
          description: 'Legal company name'
        },
        {
          name: 'tax_id',
          type: 'string',
          required: true,
          description: 'Tax identification number'
        }
      ]
    },
    isPublic: false
  })
});

const data = await response.json();

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
}

data = {
    'name': 'Corporate KYB Data',
    'version': '1.0.0',
    'description': 'Company information for KYB analysis',
    'type': 'database',
    'category': 'financial',
    'schemaData': {
        'fields': [
            {
                'name': 'company_name',
                'type': 'string',
                'required': True,
                'description': 'Legal company name'
            },
            {
                'name': 'tax_id',
                'type': 'string',
                'required': True,
                'description': 'Tax identification number'
            }
        ]
    },
    'isPublic': False
}

response = requests.post(
    'http://api.gu1.ai/custom-schemas',
    headers=headers,
    json=data
)

Cuerpo de la Solicitud

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del esquema (1-255 caracteres)
`version`	string	No	Número de versión (predeterminado: “1.0.0”)
`description`	string	No	Descripción del esquema
`type`	enum	Sí	Tipo de esquema: `database`, `api`, `file`, `custom`
`category`	enum	Sí	Categoría: `financial`, `identity`, `compliance`, `transaction`, `general`
`schemaData`	object	Sí	Definición del esquema con campos
`isPublic`	boolean	No	Compartir en toda la organización (predeterminado: false)

Objeto de Datos del Esquema

Campo	Tipo	Requerido	Descripción
`fields`	array	Sí	Array de definiciones de campos
`metadata`	object	No	Metadatos adicionales (formato, codificación, etc.)
`analysisResults`	object	No	Resultados de autodetección

Definición de Campo

Campo	Tipo	Requerido	Descripción
`name`	string	Sí	Nombre del campo
`type`	enum	Sí	`string`, `number`, `boolean`, `date`, `array`, `object`
`required`	boolean	No	¿Es el campo requerido? (predeterminado: false)
`description`	string	No	Descripción del campo
`format`	string	No	Sugerencia de formato (ej., “email”, “url”)
`constraints`	object	No	Restricciones de validación
`examples`	array	No	Valores de ejemplo

Objeto de Restricciones

{
  "minLength": 5,
  "maxLength": 100,
  "pattern": "^[A-Z0-9]+$",
  "enum": ["active", "inactive", "pending"],
  "min": 0,
  "max": 1000
}

Respuesta

{
  "success": true,
  "schema": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Corporate KYB Data",
    "version": "1.0.0",
    "description": "Company information for KYB analysis",
    "type": "database",
    "category": "financial",
    "organizationId": "org_abc123",
    "createdBy": "user_xyz789",
    "isPublic": false,
    "createdAt": "2025-10-03T12:00:00Z",
    "updatedAt": "2025-10-03T12:00:00Z",
    "schemaData": {
      "fields": [...]
    }
  }
}

Listar Esquemas

Obtiene todos los esquemas de tu organización con filtrado opcional.

GET /custom-schemas?type=database&category=financial&isPublic=false

Parámetros de Consulta

Parámetro	Tipo	Descripción
`type`	enum	Filtrar por tipo: `database`, `api`, `file`, `custom`
`category`	enum	Filtrar por categoría: `financial`, `identity`, `compliance`, `transaction`, `general`
`isPublic`	boolean	Filtrar por esquemas públicos/privados

Respuesta

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Corporate KYB Data",
      "version": "1.0.0",
      "type": "database",
      "category": "financial",
      "isPublic": false,
      "createdAt": "2025-10-03T12:00:00Z"
    }
  ],
  "meta": {
    "total": 1,
    "filters": {
      "type": "database",
      "category": "financial"
    }
  }
}

Obtener Esquema

Recupera un esquema específico por ID.

GET /custom-schemas/:id

Respuesta

{
  "success": true,
  "schema": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Corporate KYB Data",
    "version": "1.0.0",
    "description": "Company information for KYB analysis",
    "type": "database",
    "category": "financial",
    "organizationId": "org_abc123",
    "createdBy": "user_xyz789",
    "isPublic": false,
    "createdAt": "2025-10-03T12:00:00Z",
    "updatedAt": "2025-10-03T12:00:00Z",
    "schemaData": {
      "fields": [
        {
          "name": "company_name",
          "type": "string",
          "required": true,
          "description": "Legal company name"
        },
        {
          "name": "tax_id",
          "type": "string",
          "required": true,
          "description": "Tax identification number"
        }
      ],
      "metadata": {
        "sourceFormat": "database",
        "encoding": "UTF-8"
      }
    }
  }
}

Actualizar Esquema

Actualiza un esquema existente (se admiten actualizaciones parciales).

PATCH /custom-schemas/:id

Cuerpo de la Solicitud

{
  "description": "Updated description",
  "schemaData": {
    "fields": [
      {
        "name": "company_name",
        "type": "string",
        "required": true,
        "description": "Updated field description"
      }
    ]
  }
}

Actualizar los campos de un esquema puede afectar los mapeos existentes. Revisa los mapeos dependientes antes de realizar cambios.

Respuesta

{
  "success": true,
  "schema": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Corporate KYB Data",
    "version": "1.0.0",
    "description": "Updated description",
    "updatedAt": "2025-10-03T13:00:00Z",
    ...
  }
}

Eliminar Esquema

Elimina un esquema permanentemente.

DELETE /custom-schemas/:id

Eliminar un esquema romperá los mapeos de campos existentes que dependan de él. Asegúrate de que no haya mapeos activos que referencien este esquema.

Respuesta

{
  "success": true,
  "message": "Schema deleted successfully",
  "deletedId": "550e8400-e29b-41d4-a716-446655440000"
}

Ejemplo Completo

Aquí hay un esquema completo de cliente bancario con todas las características:

{
  "name": "Banking Customer Schema",
  "version": "2.0.0",
  "description": "Complete customer data structure for retail banking",
  "type": "database",
  "category": "financial",
  "schemaData": {
    "fields": [
      {
        "name": "customer_id",
        "type": "string",
        "required": true,
        "description": "Unique customer identifier",
        "format": "uuid",
        "constraints": {
          "pattern": "^CUST[0-9]{8}$"
        },
        "examples": ["CUST12345678", "CUST87654321"]
      },
      {
        "name": "full_name",
        "type": "string",
        "required": true,
        "description": "Customer full legal name",
        "constraints": {
          "minLength": 2,
          "maxLength": 200
        },
        "examples": ["John Doe", "Jane Smith"]
      },
      {
        "name": "email",
        "type": "string",
        "required": true,
        "description": "Primary email address",
        "format": "email",
        "constraints": {
          "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
        },
        "examples": ["john.doe@example.com"]
      },
      {
        "name": "date_of_birth",
        "type": "date",
        "required": true,
        "description": "Customer date of birth",
        "format": "ISO8601",
        "examples": ["1990-01-15"]
      },
      {
        "name": "account_balance",
        "type": "number",
        "required": false,
        "description": "Current account balance in USD",
        "constraints": {
          "min": 0
        },
        "examples": [1000.50, 50000.00]
      },
      {
        "name": "risk_level",
        "type": "string",
        "required": true,
        "description": "Customer risk classification",
        "constraints": {
          "enum": ["low", "medium", "high", "critical"]
        },
        "examples": ["low", "medium"]
      },
      {
        "name": "kyc_verified",
        "type": "boolean",
        "required": true,
        "description": "Whether KYC verification is complete",
        "examples": [true, false]
      },
      {
        "name": "account_types",
        "type": "array",
        "required": false,
        "description": "Types of accounts customer holds",
        "examples": [["checking", "savings"], ["credit"]]
      },
      {
        "name": "address",
        "type": "object",
        "required": false,
        "description": "Customer address details",
        "examples": [
          {
            "street": "123 Main St",
            "city": "New York",
            "state": "NY",
            "zip": "10001",
            "country": "US"
          }
        ]
      }
    ],
    "metadata": {
      "sourceFormat": "database",
      "encoding": "UTF-8",
      "delimiter": null,
      "hasHeaders": true
    }
  },
  "isPublic": false
}

Respuestas de Error

Error de Validación

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid schema data",
    "details": [
      {
        "field": "schemaData.fields[0].type",
        "message": "Invalid field type. Must be one of: string, number, boolean, date, array, object"
      }
    ]
  }
}

Esquema No Encontrado

{
  "success": false,
  "error": {
    "code": "SCHEMA_NOT_FOUND",
    "message": "Schema with ID 550e8400-e29b-41d4-a716-446655440000 not found"
  }
}

Esquema Duplicado

{
  "success": false,
  "error": {
    "code": "DUPLICATE_SCHEMA",
    "message": "A schema with this name and version already exists"
  }
}

Mejores Prácticas

Versionado

Usa versionado semántico (1.0.0, 1.1.0, 2.0.0)
Incrementa la versión mayor para cambios que rompen compatibilidad
Incrementa la versión menor para nuevos campos
Incrementa la versión de parche para actualizaciones de descripción

Documentación

Proporciona descripciones claras para cada campo
Incluye ejemplos para tipos de campos complejos
Documenta cualquier regla de negocio o restricción
Explica el origen de los datos

Validación

Siempre establece required: true para campos obligatorios
Usa restricciones para garantizar la calidad de los datos
Valida formatos de email con patrones regex
Establece valores mínimos/máximos razonables para números

Marca los esquemas comunes como públicos para uso en toda la organización
Mantén los esquemas sensibles como privados
Documenta cualquier dependencia entre esquemas
Coordina las actualizaciones de esquemas con tu equipo

Próximos Pasos

Crear Mapeos de Campos

Mapea los campos de tu esquema al modelo de entidades de gu1

Detección Inteligente de Campos

Autodetecta tipos de campos a partir de datos de muestra

Importar Entidades

Usa tu esquema para importar entidades en masa

Guía de Mapeo de Datos

Guía completa de flujos de trabajo de mapeo de datos

​Descripción General

​Crear Esquema

​Cuerpo de la Solicitud

​Objeto de Datos del Esquema

​Definición de Campo

​Objeto de Restricciones

​Respuesta

​Listar Esquemas

​Parámetros de Consulta

​Respuesta

​Obtener Esquema

​Respuesta

​Actualizar Esquema

​Cuerpo de la Solicitud

​Respuesta

​Eliminar Esquema

​Respuesta

​Ejemplo Completo

​Respuestas de Error

​Error de Validación

​Esquema No Encontrado

​Esquema Duplicado

​Mejores Prácticas

​Próximos Pasos

Crear Mapeos de Campos

Detección Inteligente de Campos

Importar Entidades

Guía de Mapeo de Datos

Descripción General

Crear Esquema

Cuerpo de la Solicitud

Objeto de Datos del Esquema

Definición de Campo

Objeto de Restricciones

Respuesta

Listar Esquemas

Parámetros de Consulta

Respuesta

Obtener Esquema

Respuesta

Actualizar Esquema

Cuerpo de la Solicitud

Respuesta

Eliminar Esquema

Respuesta

Ejemplo Completo

Respuestas de Error

Error de Validación

Esquema No Encontrado

Esquema Duplicado

Mejores Prácticas

Próximos Pasos