> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Schemas Personalizados

> Defina e gerencie schemas de dados personalizados para ingestão flexível de dados — no pipeline de ingestão de dados da gu1 com 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.

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

## Criar Schema

Crie um novo schema personalizado para sua fonte de dados.

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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
  )
  ```
</CodeGroup>

### 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

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

### Resposta

```json theme={null}
{
  "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.

```bash theme={null}
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

```json theme={null}
{
  "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.

```bash theme={null}
GET /custom-schemas/:id
```

### Resposta

```json theme={null}
{
  "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).

```bash theme={null}
PATCH /custom-schemas/:id
```

### Corpo da Requisição

```json theme={null}
{
  "description": "Updated description",
  "schemaData": {
    "fields": [
      {
        "name": "company_name",
        "type": "string",
        "required": true,
        "description": "Updated field description"
      }
    ]
  }
}
```

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

### Resposta

```json theme={null}
{
  "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.

```bash theme={null}
DELETE /custom-schemas/:id
```

<Warning>
  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.
</Warning>

### Resposta

```json theme={null}
{
  "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:

```json theme={null}
{
  "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
}
```

## Respostas de Erro

### Erro de Validação

```json theme={null}
{
  "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

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

### Schema Duplicado

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

## Melhores Práticas

<AccordionGroup>
  <Accordion icon="tag" title="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
  </Accordion>

  <Accordion icon="file-lines" title="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
  </Accordion>

  <Accordion icon="shield-check" title="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
  </Accordion>

  <Accordion icon="users" title="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
  </Accordion>
</AccordionGroup>

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Criar Mapeamentos de Campos" icon="arrows-left-right" href="/api-reference/data-ingestion/field-mappings">
    Mapeie os campos do seu schema para o modelo de entidade do gu1
  </Card>

  <Card title="Detecção Inteligente de Campos" icon="wand-magic-sparkles" href="/api-reference/data-ingestion/custom-schemas">
    Detecte automaticamente tipos de campos a partir de dados de amostra
  </Card>

  <Card title="Importar Entidades" icon="upload" href="/en/api-reference/bulk-imports/import-entities">
    Use seu schema para importar entidades em massa
  </Card>

  <Card title="Guia de Mapeamento de Dados" icon="book" href="/api-reference/data-ingestion/overview">
    Guia completo para fluxos de trabalho de mapeamento de dados
  </Card>
</CardGroup>