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

# Estrutura de Dados SFTP

## 1. Introdução

Esta documentação descreve como estruturar os seus ficheiros de dados — **produtos**, **encomendas**, **devoluções** e dados relacionados — no nosso ambiente SFTP, após o aprovisionamento do seu espaço dedicado.

Se operar várias lojas, ou tiver vários ambientes (prod, preprod, etc.), crie uma subpasta separada para cada um (pode também corresponder a marcas diferentes, países diferentes, etc.).

### Exemplo de Estrutura de Diretórios

```
/root_space
    /shop_fr
    /shop_en
    /shop_it
```

***

## 2. Calendário de Transmissão de Dados

Os ficheiros de dados devem ser transmitidos idealmente **diariamente** entre:

* **02:00**
* **05:00**

Este intervalo de tempo garante um processamento e ingestão de dados otimizados.

***

## 3. Normas de Organização de Ficheiros

Em cada diretório de loja, crie as seguintes pastas:

* `products`
* `orders`
* `returns`
* `return_reasons` (opcional)
* `misc` (opcional)

**Notas:**

* A pasta `return_reasons` é utilizada para ficheiros de exportação que contêm dados adicionais de devolução, como os motivos fornecidos pelos clientes. Estas exportações são opcionais.
* A pasta `misc` pode conter ficheiros variados. Se pretender utilizar esta pasta, discuta previamente a hierarquia e estrutura connosco para garantir compatibilidade.

Cada exportação deve ser colocada na pasta apropriada e **datada com zero** utilizando um nome de ficheiro com timestamp.

### Exemplo de Formato de Nome de Ficheiro

```
products_2025-01-15T02-00-00.csv
```

***

## 4. Requisitos de Conteúdo das Exportações

Uma especificação detalhada dos campos esperados, formatos e restrições para cada tipo de conjunto de dados está disponível na documentação **Data Transfers: Template**.

**Requisitos principais para exportações do catálogo de produtos:**

* Exporte **todas as variantes de produto**, incluindo artigos sem stock
* Inclua um campo de **data da última modificação** para processamento incremental
* Mantenha informações completas de variante para permitir uma análise de dimensionamento adequada
* Opcionalmente, adicione um flag de desativação para controlo da presença do Kleep

Consulte o modelo para definições de campo e exemplos abrangentes.

***

## 5. Gestão de Dados Repetidos entre Exportações

Os registos podem legitimamente aparecer em múltiplas exportações diárias. Por exemplo, uma determinada devolução pode estar incluída várias vezes em diferentes ficheiros.

O nosso sistema de ingestão gere automaticamente a deduplicação e processa apenas a **versão mais recente** de cada registo.

***

## 6. Diretrizes de Formato de Dados

Todas as exportações devem ser fornecidas em formato **CSV**.

Os ficheiros Excel (`.xlsx`) são desaconselhados, pois introduzem inconsistências de formatação e podem complicar os fluxos de trabalho de ingestão automatizada.

* **Data e hora:** Utilize o formato ISO 8601: `YYYY-MM-DDTHH:MM:SSZ`, exemplo: `2025-01-15T14:30:00Z`
* **Codificação:** Codificação UTF-8 para todos os campos de texto, com escape correto de caracteres especiais em CSV
* **Valores booleanos:** Utilize `true`/`false` (minúsculas) ou `True`/`False`
* **Valores decimais:** Utilize ponto (`.`) como separador decimal. Exemplo: `129.99` e não `129,99`
* **Valores nulos:** String vazia para campos de texto opcionais em falta nos CSV, utilize null nos JSON

### Convenção de Nomenclatura de Ficheiros

***

Conforme especificado na Documentação da Estrutura de Dados SFTP, utilize o seguinte formato:

```
{data_type}_{timestamp}.csv
```

Exemplos:

* `products_2025-01-15T02-00-00.csv`
* `orders_2025-01-15T02-00-00.csv`
* `returns_2025-01-15T02-00-00.csv`

***

## 7. Exportação de Dados Históricos

Se necessitar de fornecer **dados históricos** (isto é, dados que não fazem parte das exportações diárias), pode exportar até **um ano de registos históricos** para todos os tipos de dados, incluindo:

* **Produtos**
* **Encomendas**
* **Devoluções**

Os conjuntos de dados históricos podem ser transmitidos **via SFTP** ou, se for mais conveniente, **através de outro meio acordado**.

# Exemplo de uma Estrutura SFTP Completa

```
/root_space
    /shop_fr
        /products
            products_2025-01-15T02-00-00.csv
            products_2025-01-16T02-00-00.csv
        /orders
            orders_2025-01-15T02-00-00.csv
            orders_2025-01-16T02-00-00.csv
        /returns
            returns_2025-01-15T02-00-00.csv
            returns_2025-01-16T02-00-00.csv
        /return_reasons
            return_reasons_2025-01-15T02-00-00.csv  (opcional)
        /misc
            (opcional, por favor discuta a hierarquia connosco)

    /shop_en
        /products
        /orders
        /returns
        /return_reasons
        /misc

    /shop_it
        /products
        /orders
        /returns
        /return_reasons
        /misc

```

***