Saltar para o conteúdo principal

​
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