Pular para o conteúdo principal

​
1. Introdução

Esta documentação descreve como estruturar seus arquivos de dados — produtos, pedidos, devoluções e dados relacionados — no nosso ambiente SFTP, após a provisão do seu espaço dedicado. Se você opera múltiplas lojas, ou tem múltiplos ambientes (prod, preprod, etc.), crie uma subpasta separada para cada um (também pode ser para marcas diferentes, países diferentes, etc.).

​
Exemplo de Estrutura de Diretório

/root_space
    /shop_fr
    /shop_en
    /shop_it

​
2. Cronograma de Transmissão de Dados

Os arquivos de dados devem ser transmitidos idealmente diariamente entre:
  • 02:00
  • 05:00
Esse período garante processamento e ingestão de dados otimizados.

​
3. Padrões de Organização de Arquivos

Dentro de cada diretório de loja, crie as seguintes pastas:
  • products
  • orders
  • returns
  • return_reasons (opcional)
  • misc (opcional)
Observações:
  • A pasta return_reasons é usada para arquivos de exportação contendo dados adicionais de devolução, como motivos fornecidos pelos clientes. Essas exportações são opcionais.
  • A pasta misc pode conter arquivos diversos. Se desejar usar esta pasta, discuta a hierarquia e estrutura conosco antecipadamente para garantir compatibilidade.
Cada exportação deve ser colocada na pasta apropriada e nomeada com data usando um nome de arquivo com timestamp.

​
Exemplo de Formato de Nome de Arquivo

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

​
4. Requisitos de Conteúdo de Exportação

Uma especificação detalhada dos campos esperados, formatos e restrições para cada tipo de conjunto de dados está disponível na documentação Transferências de Dados: Modelo. Requisitos principais para exportações de catálogo de produtos:
  • Exporte todas as variantes de produtos, incluindo itens fora de estoque
  • Inclua um campo de data da última modificação para processamento incremental
  • Mantenha informações completas de variantes para permitir análise adequada de dimensionamento
  • Opcionalmente, adicione um sinalizador de desativação para controle de presença do Kleep
Consulte o modelo para definições e exemplos abrangentes de campos.

​
5. Tratamento de Dados Repetidos em Exportações

Registros podem aparecer legitimamente em múltiplas exportações diárias. Por exemplo, uma determinada devolução pode estar incluída em vários arquivos em datas diferentes. Nosso sistema de ingestão trata a deduplicação automaticamente e processa apenas a versão mais recente de cada registro.

​
6. Diretrizes de Formato de Dados

Todas as exportações devem ser fornecidas no formato CSV. Arquivos Excel (.xlsx) são desaconselhados, pois introduzem inconsistências de formatação e podem complicar fluxos de trabalho de ingestão automatizada.
  • Data/hora: Use o formato ISO 8601: YYYY-MM-DDTHH:MM:SSZ, exemplo: 2025-01-15T14:30:00Z
  • Codificação: UTF-8 para todos os campos de texto, escape adequado de caracteres especiais em CSV
  • Valores booleanos: Use true/false (minúsculas) ou True/False
  • Valores decimais: Use ponto (.) como separador decimal. Exemplo: 129.99 e não 129,99
  • Valores nulos: String vazia para campos de texto opcionais ausentes em CSV, use null em JSON

​
Convenção de Nomenclatura de Arquivos

Conforme especificado na Documentação da Estrutura de Dados SFTP, use 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 você precisar fornecer dados históricos (ou seja, dados que não fazem parte das exportações diárias), você pode exportar até um ano de registros históricos para todos os tipos de dados, incluindo:
  • Produtos
  • Pedidos
  • Devoluções
Conjuntos de dados históricos podem ser transmitidos pelo SFTP ou, se for mais conveniente, por outro meio acordado.

​
Exemplo de 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 conosco)

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

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