¿Qué es la integración por archivos compartidos?
La integración por archivos compartidos (ShareFileFTP Serverless) es un sistema automatizado que sincroniza su inventario, órdenes y configuraciones de Marketplace entre su sistema interno y Yuju (plataforma de e-commerce) mediante archivos FTP/SFTP.
Características Principales:
Sincronización Automatizada: Procesa archivos 24/7 según horarios configurados
Multi-Cliente: Soporta diferentes configuraciones por cliente
Escalabilidad: Maneja archivos con miles de productos sin timeouts
Formatos Flexibles: Soporte para XML y texto delimitado
Marketplace Integration: Configuración específica por canal de venta
¿Qué Hace por Usted?
Crea productos nuevos en Yuju automáticamente
Actualiza inventario y precios en tiempo real
Sincroniza órdenes desde Yuju a su sistema
Configura productos específicamente para cada Marketplace
Maneja variaciones de productos (color, talla, etc.)
Alcance de la integración
Creación de productos.
Actualización de productos: stock, precio, campos generales, campos por marketplace incluyendo descuentos.
Mapeo de productos.
Envío de órdenes de venta (pedidos): nuevas y actualizaciones.
Configuración Inicial (Información Requerida)
Provisión de Carpeta FTP/SFTP
Es responsabilidad del cliente proveer la carpeta de conexión.
El cliente debe entregar:
URL del servidor
Usuario y contraseña
Tipo de conexión (FTP o SFTP)
La conexión puede realizarse a través de:
IP fija
IP dinámica
DNS
Nota: Por defecto, Yuju opera sobre servicios de AWS, región US West 2 (Oregón, EE.UU.), utilizando IP dinámica.
Solicitudes Especiales
En caso de que el cliente requiera:
Una carpeta provista directamente por Yuju, y/o
Una IP fija para las conexiones,
Será necesario solicitarlo explícitamente.
Estas condiciones están sujetas a cotización adicional, para cubrir los costos de proveedores y de gestión.
Protocolos Disponibles
Yuju se adapta al protocolo que defina el cliente:
FTP
SFTP
No es necesario modificar la infraestructura actual del cliente: Yuju ajusta la integración al protocolo indicado.
Organización y Estructura de Carpetas
Yuju entregará al cliente una estructura de carpetas recomendada, diseñada para:
Optimizar el flujo de integración.
Mantener orden en el manejo de archivos.
Facilitar procesos de control y gestión.
El documento con la estructura sugerida será compartido dentro de esta semana por nuestro equipo.
Para configurar el sistema, necesitamos:
1. Acceso FTP/SFTP
URL del servidor FTP
Puerto (21 para FTP, 22 para SFTP)
Usuario y contraseña
Estructura de carpetas preferida
2. Credenciales Yuju
Token de API de Yuju
ID de la tienda (shop_id)
3. Configuración de Email
Servidor SMTP y credenciales
Dirección de email para notificaciones
Configuración realizada por el Cliente
Cada cliente tiene una configuración personalizada que incluye:
Cliente: Su Empresa
Formato de Archivos: XML/TXT
Headers en Archivos: Sí/No
Conexión: FTP/SFTP
Carpetas:
Productos: "products/"
Procesados: "products/processed/"
Fallidos: "products/failed/"
Ordenes: "Orders/"
Tareas Habilitadas:
- Crear Productos:✔️
- Actualizar Productos:✔️
- Actualizar Stock:✔️
- Channel Fields:✔️
- Orders:✔️
Gestión de Productos
Tipos de operaciones
1. Creación de productos
Cuando: Diariamente a las 2:45 AM UTC
Archivos: Prefijo configurado (ej.: “products”)
Función: Crea productos nuevos que no existen en Yuju.
2. Actualización de productos
Cuando: Diariamente a las 4:00 AM UTC
Archivos: Prefijo configurado (ej.: “update products _”)
Función: Actualiza información completa de productos existentes
3. Actualización de Stock/Precios
Cuando: Cada 15 minutos
Archivos: Prefijos configurados (ej.: “stock_”, “price _”)
Función: Actualiza solo inventario y precios
4. Mapeo de catálogo
Cuando: Diariamente a la 1:00 AM UTC
Función: Sincroniza productos entre los SKUs colocados en el archivo y los productos ya creados en Yuju.
Procesamiento en lotes
Para archivos grandes (>500 productos), el sistema automáticamente:
Divide el archivo en lotes de 1000 productos
Procesa cada lote de forma independiente
Evita timeouts y errores de memoria
Reporta progreso en tiempo real
Ejemplo: Un archivo con 5,000 productos se divide en 5 lotes que se procesan simultáneamente.
📁 Estructura de carpetas
FTP Root/
├── orders/ # Órdenes de salida
└── products/ # Archivos de entrada
├── processed/ # Archivos procesados exitosamente
└── failed/ # Archivos con errores
Gestión de Órdenes
Flujo de Órdenes
Horarios de procesamiento
Órdenes en Tiempo Real: Procesamiento inmediato al recibir webhook, en cualquiera de los 2 eventos, creación y actualización.
Órdenes Pendientes: Procesamiento diario a las 12:00 PM
Órdenes Anteriores: Limpieza diaria a las 00:00 (medianoche)
📁 Estructura de Archivos de Órdenes
Las órdenes se generan en la carpeta orders/ con la siguiente nomenclatura:
orders/
├── orders_YYYYMMDD_HHMMSS_[ORDER_ID].txt
├── orders_YYYYMMDD_HHMMSS_[ORDER_ID].json
└── processed/
└── order_YYYYMMDD_HHMMSS_[ORDER_ID]_processed.txt
Formato de Orden
Información del Cliente:
Nombre completo
Documento de identidad
Dirección de entrega (calle, ciudad, código postal)
Teléfono y email de contacto
Información de Productos:
SKU del producto
Nombre del producto
Cantidad solicitada
Precio unitario
Precio total
Información de Pago:
Método de pago (efectivo, tarjeta, transferencia)
Estado del pago (pendiente, pagado, fallido)
Monto total de la orden
Metadatos del Marketplace:
ID de la orden en Yuju
Canal de venta (Amazon, MercadoLibre, etc.)
Fecha y hora de la orden
Tipo de fulfillment (envío directo, pickup, etc.)
Ejemplo de Archivo de Orden
Formato JSON:
{
"order_id": "12345",
"order_date": "2025-01-16T10:30:00Z",
"customer": {
"name": "Juan Pérez",
"email": "juan@email.com",
"phone": "+1234567890",
"address": {
"street": "Calle Principal 123",
"city": "Ciudad",
"postal_code": "12345"
}
},
"items":[
{
"sku": "SKU001",
"name": "Producto 1",
"quantity":2,
"unit_price":29.99,
"total_price":59.98
}
],
"payment": {
"method": "credit_card",
"status": "paid",
"total":104.98
},
"marketplace": {
"channel": "amazon",
"fulfillment_type": "standard"
}
}
Configuraciones Especiales
Por Cliente:
Campos personalizados: Campos específicos requeridos por su sistema
Formato de salida: TXT delimitado, JSON, XML según preferencia
Formato de pago: Códigos numéricos vs texto descriptivo
Agrupación: Órdenes por separado o agrupadas por cliente
Carpetas dinámicas: Organización por Marketplace, fecha o tipo de fulfillment
Filtros de Órdenes:
Por estado: Solo órdenes pagadas, pendientes, etc.
Por marketplace: Amazon, MercadoLibre, tienda propia
Estados de Órdenes
Pending (Pendiente): Orden recibida, esperando procesamiento
Processing (Procesando): Orden siendo convertida a formato del cliente
Success (Exitosa): Archivo generado y subido al FTP
Failed (Fallida): Error en procesamiento, requiere revisión
Retry (Reintento): Orden en cola para reprocesamiento
Troubleshooting de Órdenes
Problemas Comunes:
Orden no genera archivo:
Verificar que la tarea de órdenes esté habilitada
Confirmar conectividad FTP
Revisar formato de webhook recibido
Productos no encontrados:
Sincronizar catálogo de productos primero
Verificar SKUs en Yuju vs sistema interno
Contactar KAM para mapeo de productos
Información de cliente incompleta:
Validar campos requeridos en Yuju
Configurar campos obligatorios por Marketplace
Implementar validaciones previas
Proceso de Escalación para Órdenes:
Verificación inmediata: Revisar carpeta orders/ en FTP
Contacto con KAM: Reportar órdenes faltantes o incorrectas
Channel Fields (campos por marketplace)
Los campos por marketplace (Channel Fields) permiten configurar información específica para cada canal (Amazon, MercadoLibre, Shopify, etc.) sin afectar la información base del producto.
Procesamiento
Cuando: Diariamente a las 6:00 AM
Archivos: Prefijos “channel_fields_xml_” o “channel_fields_txt_”
Estructura de campos
General (aplicable a todos los canales):
price: Precio específico del canal
stock: Stock disponible para el canal
Custom (específico por Marketplace):
discount: Descuentos especiales
title: Títulos optimizados por Marketplace
description: Descripciones personalizadas
search_terms: Términos de búsqueda (Amazon)
bullet_points: Puntos clave (Amazon)
Ejemplo de Configuración
{
"channel_fields": {
"1901": {
"general": {
"price":299.99,
"stock":100
},
"custom": {
"discount":15,
"title": "Título Optimizado para Amazon",
"search_terms": "palabras clave relevantes"
}
}
}
}
Formatos de Archivos
Formato TXT (Texto Delimitado)
Con Header:
sku|nombre|precio|stock|categoria|descripción
SKU001|Producto 1|29.99|100|Electronics|Descripción del producto
SKU002|Producto 2|45.00|50|Home|Otro producto
Sin Header:
SKU001|Producto 1|29.99|100|Electronics|Descripción del producto
SKU002|Producto 2|45.00|50|Home|Otro producto
Channel Fields TXT:
sku|channel_1901_general_price|channel_1901_general_stock|channel_1901_custom_discount
SKU001|299.99|100|15
SKU002|450.00|50|10
Formato XML
Productos:
<products>
<product>
<sku>SKU001</sku>
<nombre>Producto 1</nombre>
<precio>29.99</precio>
<stock>100</stock>
<categoria>Electronics</categoria>
</producto>
</productos>
Channel Fields XML:
<products>
<product>
<sku>SKU001</sku>
<channels>
<channel id="1901">
<general>
<price>299.99</price>
<stock>100</stock>
</general>
<custom>
<discount>15</discount>
<title>Título Amazon</title>
</custom>
</channel>
</channels>
</product>
</products>
Productos con Variaciones
TXT:
sku sku|sku_simple|nombre|precio|stock|color|talla
SKU001-RED-M|SKU001|Camiseta|29.99|50|Rojo|M
SKU001-RED-L|SKU001|Camiseta|29.99|75|Rojo|L
SKU001-BLUE-M|SKU001|Camiseta|32.99|30|Azul|M
XML:
<productos>
<producto>
<sku>SKU001-RED-M</sku>
<sku_simple>SKU001</sku_simple>
<nombre>Camiseta</nombre>
<precio>29.99</precio>
<color>Rojo</color>
<talla>M</talla>
</producto>
</productos>
Monitoreo del Sistema
¿Cómo verificar el Estado?
El sistema procesa archivos automáticamente y proporciona indicadores claros del estado:
Archivos Procesados Exitosamente:
Se mueven a la carpeta processed/
Timestamp indica cuándo se procesaron
Los productos aparecen en Yuju según configuración
Archivos con Problemas:
Se mueven a la carpeta failed/
Requieren revisión y corrección
Su KAM recibirá notificación automática
Indicadores de Rendimiento
Archivos procesados: Éxito vs fallos por día
Productos sincronizados: Conteos de creación/actualización
Tiempo de procesamiento: Duración típica por operación
Disponibilidad del sistema: Uptime y conectividad
Notificaciones Automáticas
El sistema enviará notificaciones automáticas a su KAM cuando: - Archivos grandes se procesen en lotes - Ocurran errores que requieran atención - Se completen procesamiento de archivos importantes - Haya problemas de conectividad o configuración.
Solución de Problemas
Problemas Comunes
1. Archivos no se Procesan
Síntomas: Archivos permanecen en carpeta de origen después del horario de procesamiento
Posibles Causas: - Prefijo incorrecto en nombre de archivo - Formato de archivo inválido - Problemas de conectividad FTP
Pasos a Seguir:
2. Productos no Aparecen en Yuju
Síntomas: Archivo se procesa, pero productos no se crean/actualizan
Posibles Causas: - Datos requeridos faltantes en archivo - Categorías o campos inválidos - Problemas con API de Yuju
Pasos a Seguir:
3. Variaciones no se Detectan
Síntomas: Productos con variaciones se crean como productos individuales
Posibles Causas: - Campo sku_simple faltante o incorrecto - Formato de variaciones no cumple estándar
Pasos a Seguir:
Proceso de Escalación
Paso 1: Verificación Interna
Revisar formato de archivo contraejemplos
Confirmar nomenclatura y prefijos
Verificar estructura de carpetas FTP
Paso 2: Contacto con KAM
Proporcionar detalles específicos del problema
Incluir archivos de muestra (sin datos sensibles)
Indicar timestamp de cuando ocurrió el problema
Paso 3: Soporte Técnico
Su KAM escalará a equipo técnico si necesario
Revisión detallada de configuración
Ajustes y correcciones según sea requerido
Mejores Prácticas
Recomendaciones de Archivos
Nomenclatura:
Usar prefijos configurados consistentemente
Incluir timestamp: productos_20250116_143000.txt
Evitar caracteres especiales en nombres
Usar formato de fecha ISO: YYYYMMDD
Contenido:
Validar datos antes de generar archivos
Usar encoding UTF-8 siempre
Incluir solo productos con datos completos
Evitar caracteres especiales en contenido
Tamaño:
No hay límite técnico (sistema maneja lotes automáticamente)
Recomendado: archivos de 1,000-10,000 productos para balance óptimo
Archivos muy grandes (>50,000 productos) consultar con KAM
Optimización de Performance
Horarios:
Evitar subir archivos durante horarios de procesamiento automático:
1:00 AM - 1:30 AM UTC (Mapeo de catálogo)
2:45 AM - 3:30 AM UTC (Creación de productos)
4:00 AM - 5:00 AM UTC (Actualización de productos)
6:00 AM - 7:00 AM UTC (Channel fields)
Distribuir archivos grandes a lo largo del día
Coordinar cargas masivas con su KAM
Validación Previa:
Implementar validaciones en su sistema antes de generar archivos
Usar archivos de prueba para validar nuevos formatos
Mantener respaldos de archivos exitosos como referencia
Organización:
Mantener estructura de carpetas limpia
Remover archivos antiguos de carpetas processed/failed periódicamente
Documentar cambios en formatos con su KAM
Checklist de Implementación
☐ Configuración FTP/SFTP validada y probada
☐ Estructura de carpetas creada según especificación
☐ Formatos de archivo definidos y ejemplos probados
☐ Prefijos de archivo configurados correctamente
☐ Horarios de procesamiento coordinados con operaciones
☐ Procesos internos de generación de archivos implementados
☐ Contacto con KAM establecido y verificado
☐ Archivos de prueba procesados exitosamente
☐ Integración con sistema interno completada
☐ Capacitación del equipo operativo realizada
Recomendaciones Operativas
Monitoreo Diario:
Verificar que archivos se mueven a carpeta processed/
Revisar carpeta failed/ para archivos problemáticos
Confirmar sincronización en Yuju después de procesamiento
Mantenimiento Semanal:
Limpiar carpetas de archivos antiguos
Revisar performance y tiempos de procesamiento
Validar que no hay acumulación de archivos no procesados
Revisión Mensual:
Evaluar métricas de rendimiento con KAM
Revisar y optimizar formatos de archivo si necesario
Planificar mejoras o nuevas funcionalidades
Soporte y Contacto
Su KAM es su punto de contacto principal para reportar algún problema.
Cuando contacte a su KAM, incluya siempre:
Información del Cliente: Nombre de su empresa y contacto
Timestamp: Fecha y hora exacta cuando ocurrió el problema
Archivo(s) Afectado(s): Nombres exactos de archivos con problemas
Descripción Detallada:
Qué esperaba que ocurriera
Qué ocurrió realmente
Pasos que ya intentó para resolver
Archivos de Muestra: Si es posible, proporcione muestra del archivo (sin datos sensibles)
Canales de Comunicación
Su KAM le proporcionará:
- Email directo para soporte.
- Canal de comunicación por whatsapp.
Glosario de Términos
Términos Técnicos
SKU: Código único de producto (Stock Keeping Unit)
Channel Fields: Campos específicos por marketplace
Variaciones: Versiones del mismo producto (color, talla, etc.)
Batch Processing: Procesamiento en lotes para archivos grandes
FTP/SFTP: Protocolos de transferencia de archivos
Webhook: Notificación automática entre sistemas
API: Interfaz de programación de aplicaciones
Términos de Marketplace
Yuju: Plataforma de e-commerce principal
Marketplace: Canal de venta (Amazon, Mercado Libre, etc.)
Channel ID: Identificador numérico del marketplace
Stock: Inventario disponible
Mapping: Sincronización de catálogo
Términos Operativos
KAM: Key Account Manager - Su gestor de cuenta
SLA: Acuerdo de nivel de servicio
Uptime: Tiempo de funcionamiento del sistema
Throughput: Cantidad de archivos procesados por período