Saltar al contenido principal

​
1. Introducción

Esta documentación describe cómo estructurar tus archivos de datos — productos, pedidos, devoluciones y datos relacionados — dentro de nuestro entorno SFTP una vez que tu espacio dedicado haya sido aprovisionado. Si gestionas varias tiendas o tienes múltiples entornos (prod, preprod, etc.), crea una subcarpeta separada para cada uno (también puede ser diferentes marcas, diferentes países, etc.).

​
Ejemplo de estructura de directorios

/root_space
    /shop_fr
    /shop_en
    /shop_it

​
2. Calendario de transmisión de datos

Los archivos de datos deben transmitirse idealmente diariamente entre:
  • 02:00
  • 05:00
Este intervalo de tiempo garantiza un procesamiento y una ingestión de datos óptimos.

​
3. Estándares de organización de archivos

Dentro de cada directorio de tienda, crea las siguientes carpetas:
  • products
  • orders
  • returns
  • return_reasons (opcional)
  • misc (opcional)
Notas:
  • La carpeta return_reasons se usa para archivos de exportación que contienen datos adicionales de devoluciones, como los motivos proporcionados por los clientes. Estas exportaciones son opcionales.
  • La carpeta misc puede contener archivos varios. Si deseas usar esta carpeta, habla previamente con nosotros sobre la jerarquía y la estructura para garantizar la compatibilidad.
Cada exportación debe colocarse en la carpeta correspondiente y con fecha cero usando un nombre de archivo con marca de tiempo.

​
Formato de nombre de archivo de ejemplo

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

​
4. Requisitos del contenido de exportación

En la documentación de Transferencias de datos: Plantilla encontrarás una especificación detallada de los campos esperados, formatos y restricciones para cada tipo de conjunto de datos. Requisitos clave para las exportaciones del catálogo de productos:
  • Exporta todas las variantes de producto, incluidos los artículos sin stock
  • Incluye un campo de fecha de última modificación para el procesamiento incremental
  • Mantén la información completa de las variantes para permitir un análisis de tallas adecuado
  • Opcionalmente añade un indicador de desactivación para el control de presencia de Kleep
Consulta la plantilla para obtener definiciones completas de campos y ejemplos.

​
5. Gestión de datos repetidos en las exportaciones

Los registros pueden aparecer legítimamente en múltiples exportaciones diarias. Por ejemplo, una devolución concreta puede incluirse varias veces en diferentes archivos. Nuestro sistema de ingestión gestiona automáticamente la deduplicación y procesa únicamente la versión más reciente de cada registro.

​
6. Directrices de formato de datos

Todas las exportaciones deben proporcionarse en formato CSV. Los archivos de Excel (.xlsx) no son recomendables, ya que introducen inconsistencias de formato y pueden complicar los flujos de trabajo de ingestión automatizada.
  • Fecha y hora: Usa el formato ISO 8601: YYYY-MM-DDTHH:MM:SSZ, ejemplo: 2025-01-15T14:30:00Z
  • Codificación: Codificación UTF-8 para todos los campos de texto; escapa correctamente los caracteres especiales en CSV
  • Valores booleanos: Usa true/false (minúsculas) o True/False
  • Valores decimales: Usa punto (.) como separador decimal. Ejemplo: 129.99 no 129,99
  • Valores nulos: Cadena vacía para campos de texto opcionales faltantes en CSV, usa null en JSON

​
Convención de nombres de archivo

Como se especifica en la documentación de estructura de datos SFTP, usa el siguiente formato: 
{data_type}_{timestamp}.csv
Ejemplos:
  • products_2025-01-15T02-00-00.csv
  • orders_2025-01-15T02-00-00.csv
  • returns_2025-01-15T02-00-00.csv

​
7. Exportación de datos históricos

Si necesitas proporcionar datos históricos (es decir, datos que no forman parte de las exportaciones diarias), puedes exportar hasta un año de registros históricos para todos los tipos de datos, incluyendo:
  • Productos
  • Pedidos
  • Devoluciones
Los conjuntos de datos históricos pueden transmitirse a través del SFTP o, si es más conveniente, mediante otro medio acordado.

​
Ejemplo de una estructura 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  (optional)
        /misc
            (optional, please discuss hierarchy with us)

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

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