Schemas Personalizados

Visão Geral

Schemas Personalizados permitem que você defina a estrutura dos seus dados antes de importá-los para o gu1. Cada schema descreve os campos, tipos, regras de validação e metadados para sua fonte de dados.

Schemas são específicos da organização e podem ser marcados como públicos para compartilhar em toda a sua organização.

Criar Schema

Crie um novo schema personalizado para sua fonte de dados.

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
  }'

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do schema (1-255 caracteres)
`version`	string	Não	Número da versão (padrão: “1.0.0”)
`description`	string	Não	Descrição do schema
`type`	enum	Sim	Tipo do schema: `database`, `api`, `file`, `custom`
`category`	enum	Sim	Categoria: `financial`, `identity`, `compliance`, `transaction`, `general`
`schemaData`	object	Sim	Definição do schema com campos
`isPublic`	boolean	Não	Compartilhar na organização (padrão: false)

Objeto Schema Data

Campo	Tipo	Obrigatório	Descrição
`fields`	array	Sim	Array de definições de campos
`metadata`	object	Não	Metadados adicionais (formato, codificação, etc.)
`analysisResults`	object	Não	Resultados de detecção automática

Definição de Campo

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do campo
`type`	enum	Sim	`string`, `number`, `boolean`, `date`, `array`, `object`
`required`	boolean	Não	Campo é obrigatório (padrão: false)
`description`	string	Não	Descrição do campo
`format`	string	Não	Dica de formato (ex: “email”, “url”)
`constraints`	object	Não	Restrições de validação
`examples`	array	Não	Valores de exemplo

Objeto Constraints

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

Resposta

{
  "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 Schemas

Obtenha todos os schemas da sua organização com filtragem opcional.

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

Parâmetros de Consulta

Parâmetro	Tipo	Descrição
`type`	enum	Filtrar por tipo: `database`, `api`, `file`, `custom`
`category`	enum	Filtrar por categoria: `financial`, `identity`, `compliance`, `transaction`, `general`
`isPublic`	boolean	Filtrar por schemas públicos/privados

Resposta

{
  "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"
    }
  }
}

Obter Schema

Recupere um schema específico por ID.

GET /custom-schemas/:id

Resposta

{
  "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"
      }
    }
  }
}

Atualizar Schema

Atualize um schema existente (atualizações parciais são suportadas).

PATCH /custom-schemas/:id

Corpo da Requisição

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

Atualizar os campos de um schema pode afetar mapeamentos existentes. Revise os mapeamentos dependentes antes de fazer alterações.

Resposta

{
  "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",
    ...
  }
}

Excluir Schema

Exclua um schema permanentemente.

DELETE /custom-schemas/:id

Excluir um schema quebrará mapeamentos de campos existentes que dependem dele. Certifique-se de que nenhum mapeamento ativo faça referência a este schema.

Resposta

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

Exemplo Completo

Aqui está um schema completo de cliente bancário com todos os recursos:

{
  "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": ["[email protected]"]
      },
      {
        "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
}

Respostas de Erro

Erro de Validação

{
  "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"
      }
    ]
  }
}

Schema Não Encontrado

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

Schema Duplicado

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

Melhores Práticas

Versionamento

Use versionamento semântico (1.0.0, 1.1.0, 2.0.0)
Incremente a versão principal para mudanças incompatíveis
Incremente a versão secundária para novos campos
Incremente a versão de patch para atualizações de descrição

Documentação

Forneça descrições claras para cada campo
Inclua exemplos para tipos de campos complexos
Documente quaisquer regras de negócio ou restrições
Explique a origem dos dados

Validação

Sempre defina required: true para campos obrigatórios
Use constraints para garantir qualidade dos dados
Valide formatos de e-mail com padrões regex
Defina valores min/max razoáveis para números

Compartilhamento

Marque schemas comuns como públicos para uso em toda a organização
Mantenha schemas sensíveis privados
Documente quaisquer dependências entre schemas
Coordene atualizações de schema com sua equipe

Próximos Passos

Criar Mapeamentos de Campos

Mapeie os campos do seu schema para o modelo de entidade do gu1

Detecção Inteligente de Campos

Detecte automaticamente tipos de campos a partir de dados de amostra

Importar Entidades

Use seu schema para importar entidades em massa

Guia de Mapeamento de Dados

Guia completo para fluxos de trabalho de mapeamento de dados

Começando

Referência API

Ingestão de Dados

Entidades

Conheça Seu Negócio (KYB)

Conheça Seu Cliente (KYC)

Monitoramento de Transações

Tutoriais Interativos

Schemas Personalizados

Visão Geral

Criar Schema

Corpo da Requisição

Objeto Schema Data

Definição de Campo

Objeto Constraints

Resposta

Listar Schemas

Parâmetros de Consulta

Resposta

Obter Schema

Resposta

Atualizar Schema

Corpo da Requisição

Resposta

Excluir Schema

Resposta

Exemplo Completo

Respostas de Erro

Erro de Validação

Schema Não Encontrado

Schema Duplicado

Melhores Práticas

Próximos Passos

Criar Mapeamentos de Campos

Detecção Inteligente de Campos

Importar Entidades

Guia de Mapeamento de Dados

Começando

Referência API

Ingestão de Dados

Entidades

Conheça Seu Negócio (KYB)

Conheça Seu Cliente (KYC)

Monitoramento de Transações

Tutoriais Interativos

​Visão Geral

​Criar Schema

​Corpo da Requisição

​Objeto Schema Data

​Definição de Campo

​Objeto Constraints

​Resposta

​Listar Schemas

​Parâmetros de Consulta

​Resposta

​Obter Schema

​Resposta

​Atualizar Schema

​Corpo da Requisição

​Resposta

​Excluir Schema

​Resposta

​Exemplo Completo

​Respostas de Erro

​Erro de Validação

​Schema Não Encontrado

​Schema Duplicado

​Melhores Práticas

​Próximos Passos

Criar Mapeamentos de Campos

Detecção Inteligente de Campos

Importar Entidades

Guia de Mapeamento de Dados

Visão Geral

Criar Schema

Corpo da Requisição

Objeto Schema Data

Definição de Campo

Objeto Constraints

Resposta

Listar Schemas

Parâmetros de Consulta

Resposta

Obter Schema

Resposta

Atualizar Schema

Corpo da Requisição

Resposta

Excluir Schema

Resposta

Exemplo Completo

Respostas de Erro

Erro de Validação

Schema Não Encontrado

Schema Duplicado

Melhores Práticas

Próximos Passos