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

# Visão Geral da Ingestão de Dados

> Aprenda como mapear e importar seus dados para o gu1 usando esquemas personalizados e mapeamentos de campos. Consulte o esquema do request, códigos de resposta.

## O que é Ingestão de Dados?

O sistema de Ingestão de Dados do gu1 permite que você importe dados de qualquer fonte (arquivos CSV, APIs, bancos de dados ou formatos personalizados) de forma transparente, definindo esquemas personalizados e mapeamentos de campos. Este sistema inteligente de mapeamento garante que seus dados sejam estruturados adequadamente para análise de risco.

## Como Funciona

<Steps>
  <Step title="Defina Seu Esquema">
    Crie um esquema personalizado que descreva a estrutura dos seus dados com definições de campos, tipos e regras de validação.
  </Step>

  <Step title="Mapeie Campos">
    Crie mapeamentos de campos que traduzam os campos dos seus dados para o modelo unificado de entidades do gu1.
  </Step>

  <Step title="Transforme Dados">
    Aplique transformações (formatação, cálculos, condicionais) conforme os dados fluem pelo mapeamento.
  </Step>

  <Step title="Importe Entidades">
    Use o esquema mapeado para criar entidades via API ou upload em massa.
  </Step>
</Steps>

## Recursos Principais

<CardGroup cols={2}>
  <Card title="Esquemas Personalizados" icon="table" href="/api-reference/data-ingestion/custom-schemas">
    Defina a estrutura dos seus dados com tipos de campos flexíveis e validação
  </Card>

  <Card title="Mapeamentos de Campos" icon="arrows-left-right" href="/api-reference/data-ingestion/field-mappings">
    Mapeie seus campos para o modelo unificado do gu1 com transformações
  </Card>

  <Card title="Detecção Inteligente" icon="wand-magic-sparkles" href="/api-reference/data-ingestion/custom-schemas">
    Detecte automaticamente tipos de campos, padrões e mapeamentos sugeridos
  </Card>

  <Card title="Processamento em Massa" icon="layer-group" href="/en/api-reference/bulk-imports/overview">
    Importe milhares de registros de forma eficiente com processamento em lote
  </Card>
</CardGroup>

## Tipos de Esquema

O gu1 suporta múltiplos tipos de esquema para diferentes fontes de dados:

| Tipo         | Descrição                             | Caso de Uso                          |
| ------------ | ------------------------------------- | ------------------------------------ |
| **database** | Esquemas de banco de dados relacional | Integração direta com banco de dados |
| **api**      | Estruturas de resposta de API         | Integração com APIs de terceiros     |
| **file**     | Formatos de arquivo (CSV, JSON, XML)  | Importações baseadas em arquivos     |
| **custom**   | Estruturas de dados personalizadas    | Formatos proprietários               |

## Categorias de Esquema

Organize esquemas por domínio de negócio:

<AccordionGroup>
  <Accordion icon="chart-line" title="Financial">
    Contas bancárias, transações, demonstrações financeiras, dados de pagamento
  </Accordion>

  <Accordion icon="id-card" title="Identity">
    Informações pessoais, documentos de identidade, dados KYC
  </Accordion>

  <Accordion icon="shield-check" title="Compliance">
    Listas de sanções, PEPs, mídia adversa, dados regulatórios
  </Accordion>

  <Accordion icon="money-bill-transfer" title="Transaction">
    Transações de pagamento, transferências bancárias, histórico de transações
  </Accordion>

  <Accordion icon="folder" title="General">
    Qualquer outro tipo de dado estruturado
  </Accordion>
</AccordionGroup>

## Tipos de Campo

Tipos de campo suportados para definição de esquema:

| Tipo        | Descrição          | Exemplo                                                    |
| ----------- | ------------------ | ---------------------------------------------------------- |
| **string**  | Dados de texto     | "Acme Corp", "[john@example.com](mailto:john@example.com)" |
| **number**  | Valores numéricos  | 1000, 99.99, -50                                           |
| **boolean** | Verdadeiro/falso   | true, false                                                |
| **date**    | Data/timestamp     | "2025-10-03T12:00:00Z"                                     |
| **array**   | Lista de valores   | \["tag1", "tag2"]                                          |
| **object**  | Estrutura aninhada | `{"city": "NYC", "country": "US"}`                         |

## Tipos de Transformação

Aplique transformações durante o mapeamento de campos:

<CardGroup cols={3}>
  <Card title="Direct" icon="arrow-right">
    Copie o campo como está sem alterações
  </Card>

  <Card title="Calculate" icon="calculator">
    Execute cálculos matemáticos
  </Card>

  <Card title="Format" icon="text">
    Formate strings, datas, números
  </Card>

  <Card title="Conditional" icon="code-branch">
    Aplique lógica se/então baseada em condições
  </Card>

  <Card title="Lookup" icon="magnifying-glass">
    Consulte valores de tabelas de referência
  </Card>

  <Card title="Custom" icon="code">
    Expressões JavaScript personalizadas
  </Card>
</CardGroup>

## Regras de Validação

Garanta a qualidade dos dados com validações integradas:

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

**Restrições Disponíveis:**

* `minLength` / `maxLength` - Limites de comprimento de string
* `min` / `max` - Intervalos de valores numéricos
* `pattern` - Validação por expressão regular
* `enum` - Lista de valores permitidos
* `required` - Campo é obrigatório

## Exemplo: Esquema de Dados Bancários

Aqui está um exemplo completo de definição de um esquema para dados de clientes bancários:

```json theme={null}
{
  "name": "Banking Customer Data",
  "version": "1.0.0",
  "type": "database",
  "category": "financial",
  "schemaData": {
    "fields": [
      {
        "name": "customer_id",
        "type": "string",
        "required": true,
        "description": "Unique customer identifier",
        "constraints": {
          "pattern": "^CUST[0-9]{8}$"
        }
      },
      {
        "name": "full_name",
        "type": "string",
        "required": true,
        "description": "Customer full legal name",
        "constraints": {
          "minLength": 2,
          "maxLength": 200
        }
      },
      {
        "name": "account_balance",
        "type": "number",
        "required": false,
        "description": "Current account balance in USD",
        "constraints": {
          "min": 0
        }
      },
      {
        "name": "risk_level",
        "type": "string",
        "required": true,
        "description": "Risk classification",
        "constraints": {
          "enum": ["low", "medium", "high", "critical"]
        }
      },
      {
        "name": "onboarding_date",
        "type": "date",
        "required": true,
        "description": "Date customer was onboarded"
      },
      {
        "name": "kyc_verified",
        "type": "boolean",
        "required": true,
        "description": "Whether KYC verification is complete"
      }
    ],
    "metadata": {
      "sourceFormat": "database",
      "encoding": "UTF-8"
    }
  }
}
```

## Melhores Práticas

<AccordionGroup>
  <Accordion icon="lightbulb" title="Design de Esquema">
    * Use nomes de campos descritivos que correspondam aos seus dados de origem
    * Inclua descrições detalhadas para campos complexos
    * Defina restrições de validação apropriadas
    * Versione seus esquemas (1.0.0, 1.1.0, etc.)
  </Accordion>

  <Accordion icon="arrows-spin" title="Mapeamento de Campos">
    * Comece com mapeamentos diretos, adicione transformações conforme necessário
    * Teste mapeamentos com dados de amostra antes da importação em massa
    * Documente a lógica de transformação personalizada
    * Trate valores nulos/ausentes com elegância
  </Accordion>

  <Accordion icon="shield" title="Qualidade de Dados">
    * Valide dados na origem antes de importar
    * Use modo estrito para ambientes de produção
    * Monitore importações com falha e erros de validação
    * Implemente limpeza de dados para problemas conhecidos
  </Accordion>

  <Accordion icon="gauge-high" title="Performance">
    * Use processamento em massa para grandes conjuntos de dados (>1000 registros)
    * Defina tamanhos de lote apropriados (100-1000 registros)
    * Agende importações durante horários de menor movimento
    * Monitore tempos de processamento e ajuste tamanhos de lote
  </Accordion>
</AccordionGroup>

## Casos de Uso Comuns

<CardGroup cols={2}>
  <Card title="Importação de Arquivo CSV" icon="file-csv" href="/csv-import-guide">
    Importe dados de clientes de arquivos CSV com detecção automática de campos
  </Card>

  <Card title="Integração com API" icon="plug" href="/api-reference/data-ingestion/overview">
    Conecte APIs de terceiros e sincronize dados em tempo real
  </Card>

  <Card title="Sincronização de Banco de Dados" icon="database" href="/DATABASE_SYNC_GUIDE">
    Sincronize dados dos seus bancos de dados existentes
  </Card>

  <Card title="Onboarding Bancário" icon="building-columns" href="/use-cases/kyb/example">
    Fluxo de trabalho KYB completo com exemplo de mapeamento de dados
  </Card>
</CardGroup>

## Endpoints da API

<CardGroup cols={2}>
  <Card title="Criar Esquema" icon="plus" href="/api-reference/data-ingestion/custom-schemas#create-schema">
    POST /custom-schemas
  </Card>

  <Card title="Listar Esquemas" icon="list" href="/api-reference/data-ingestion/custom-schemas#list-schemas">
    GET /custom-schemas
  </Card>

  <Card title="Criar Mapeamento" icon="plus" href="/api-reference/data-ingestion/field-mappings#create-mapping">
    POST /custom-schemas/mappings
  </Card>

  <Card title="Detecção Inteligente" icon="wand-magic-sparkles" href="/api-reference/data-ingestion/custom-schemas">
    POST /custom-schemas/detect-fields
  </Card>
</CardGroup>

## Próximos Passos

<Steps>
  <Step title="Crie Seu Primeiro Esquema">
    Siga o [guia de Esquemas Personalizados](/api-reference/data-ingestion/custom-schemas) para definir a estrutura dos seus dados
  </Step>

  <Step title="Mapeie Seus Campos">
    Aprenda como mapear campos para o modelo do gu1 no [guia de Mapeamentos de Campos](/api-reference/data-ingestion/field-mappings)
  </Step>

  <Step title="Importe Dados">
    Comece a importar entidades usando a [API de Entidades](/api-reference/entities/create)
  </Step>
</Steps>