跳转到主要内容

​
1. 简介

本文档描述了在您的专用空间配置完成后，如何在我们的 SFTP 环境中组织您的数据文件——商品、订单、退货及相关数据。 如果您运营多个商店或拥有多个环境（生产、预生产等），请为每个环境创建单独的子文件夹（也可以是不同品牌、不同国家等）。

​
目录结构示例

/root_space
    /shop_fr
    /shop_en
    /shop_it

​
2. 数据传输时间表

数据文件理想情况下应在以下时间段内每日传输：
  • 凌晨 02:00
  • 凌晨 05:00
此时间段可确保最佳的处理和数据摄入效果。

​
3. 文件组织标准

在每个商店目录中，请创建以下文件夹：
  • products
  • orders
  • returns
  • return_reasons（可选）
  • misc（可选）
说明：
  • return_reasons 文件夹用于存放包含额外退货数据（如顾客提供的退货原因）的导出文件。这些导出为可选项。
  • misc 文件夹可存放杂项文件。如需使用此文件夹，请事先与我们讨论层级结构，以确保兼容性。
每个导出文件应放置在对应文件夹中，并使用带时间戳的文件名进行零日期标记。

​
文件名格式示例

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

​
4. 导出内容要求

每种数据集类型的预期字段、格式和约束的详细规范，请参阅 数据传输：模板 文档。 商品目录导出的关键要求：
  • 导出所有商品变体，包括缺货商品
  • 包含最后修改日期字段，用于增量处理
  • 维护完整的变体信息，以支持正确的尺码分析
  • 可选择添加停用标志，以控制 Kleep 的显示
请参阅模板以获取全面的字段定义和示例。

​
5. 处理跨导出文件的重复数据

记录合理地出现在多个每日导出文件中是正常的。例如，某个退货记录可能在不同文件中多次出现。 我们的摄入系统会自动处理去重，并仅处理每条记录的最新版本。

​
6. 数据格式规范

所有导出文件应以 CSV 格式提供。 不建议使用 Excel 文件（.xlsx），因为它们会引入格式不一致问题，并可能使自动化摄入工作流程变得复杂。
  • 日期时间： 使用 ISO 8601 格式：YYYY-MM-DDTHH:MM:SSZ，示例：2025-01-15T14:30:00Z
  • 编码： 所有文本字段使用 UTF-8 编码，在 CSV 中正确转义特殊字符
  • 布尔值： 使用 true/false（小写）或 True/False
  • 小数值： 使用句点（.）作为小数分隔符。示例：129.99 而非 129,99
  • 空值： CSV 中缺失的可选文本字段使用空字符串，JSON 中使用 null

​
文件命名规范

如 SFTP 数据结构文档中所述，请使用以下格式： 
{data_type}_{timestamp}.csv
示例：
  • products_2025-01-15T02-00-00.csv
  • orders_2025-01-15T02-00-00.csv
  • returns_2025-01-15T02-00-00.csv

​
7. 导出历史数据

如果您需要提供历史数据（即不属于每日导出的数据），您可以导出所有数据类型最多一年的历史记录，包括：
  • 商品
  • 订单
  • 退货
历史数据集可以通过 SFTP 传输，或者如果更方便，也可以通过另一种商定的方式传输。

​
完整 SFTP 结构示例

/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  (optional)
        /misc
            (optional, please discuss hierarchy with us)

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

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