O que é a integração por arquivos compartilhados?

A integração por arquivos compartilhados (ShareFileFTP Serverless) é um sistema automatizado que sincroniza seu estoque, pedidos e configurações do Marketplace entre seu sistema interno e o Yuju (plataforma de comércio eletrônico) por meio de arquivos FTP/SFTP.

Principais características:

Sincronização automatizada: processa arquivos 24 horas por dia, 7 dias por semana, de acordo com horários configurados
Multicliente: Suporta diferentes configurações por cliente
Escalabilidade: Gerencia arquivos com milhares de produtos sem tempo limite
Formatos flexíveis: suporte para XML e texto delimitado
Integração com Marketplace: Configuração específica por canal de venda

O que isso faz por você?

Cria novos produtos no Yuju automaticamente
Atualiza estoque e preços em tempo real
Sincroniza pedidos do Yuju com o seu sistema
Configura produtos especificamente para cada marketplace
Gerencia variações de produtos (cor, tamanho, etc.)

Escopo da integração

Criação de produtos.

Atualização de produtos: estoque, preço, campos gerais, campos por marketplace, incluindo descontos.

Mapeamento de produtos.

Envio de pedidos de venda (pedidos): novos e atualizações.

Configuração inicial (informações necessárias)

Fornecimento da pasta FTP/SFTP

É de responsabilidade do cliente fornecer a pasta de conexão.

O cliente deve fornecer:

URL do servidor
Nome de usuário e senha
Tipo de conexão (FTP ou SFTP)
A conexão pode ser feita através de:
- IP fixo
- IP dinâmico
- DNS

Observação: Por padrão, o Yuju opera em serviços da AWS, região US West 2 (Oregon, EUA), utilizando IP dinâmico.

Solicitações especiais

Caso o cliente solicite:

Uma pasta fornecida diretamente pela Yuju e/ou
Um IP fixo para as conexões,

será necessário solicitá-lo explicitamente.

Essas condições estão sujeitas a um custo adicional, para cobrir os custos dos fornecedores e de gestão.

Protocolos Disponíveis

A Yuju se adapta ao protocolo definido pelo cliente:
- FTP
- SFTP

Não é necessário modificar a infraestrutura atual do cliente: o Yuju ajusta a integração ao protocolo indicado.

Organização e Estrutura de Pastas

O Yuju fornecerá ao cliente uma estrutura de pastas recomendada, projetada para:
- Otimizar o fluxo de integração.
- Manter a organização no gerenciamento de arquivos.
- Facilitar os processos de controle e gestão.

O documento com a estrutura sugerida será compartilhado ainda esta semana pela nossa equipe.

Para configurar o sistema, precisamos de:

1. Acesso FTP/SFTP

URL do servidor FTP
Porta (21 para FTP, 22 para SFTP)
Nome de usuário e senha
Estrutura de pastas preferida

2. Credenciais Yuju

Token da API do Yuju
ID da loja (shop_id)

3. Configuração de e-mail

Servidor SMTP e credenciais
Endereço de e-mail para notificações

Configuração realizada pelo Cliente

Cada cliente possui uma configuração personalizada que inclui:

Cliente: Sua Empresa

Formato dos arquivos: XML/TXT

Cabeçalhos nos arquivos: Sim/Não

Conexão: FTP/SFTP

Pastas:

Produtos: "products/"
Processados: "products/processed/"
Falhas: "products/failed/"
Pedidos: "Orders/"

Tarefas habilitadas:

- Criar produtos: ✔️

- Atualizar produtos: ✔️

- Atualizar estoque: ✔️

- Campos do canal: ✔️

- Pedidos: ✔️

Gerenciamento de produtos

Tipos de operações

1. Criação de produtos

Quando: Diariamente às 2h45 UTC
Arquivos: Prefixo configurado (ex.: “products”)
Função: Cria novos produtos que não existem no Yuju.

2. Atualização de produtos

Quando: Diariamente às 4h00 UTC
Arquivos: Prefixo configurado (ex.: “update products _”)
Função: Atualiza todas as informações dos produtos existentes

3. Atualização de estoque/preços

Quando: A cada 15 minutos
Arquivos: Prefixos configurados (ex.: “stock_”, “price _”)
Função: Atualiza apenas o estoque e os preços

4. Mapeamento do catálogo

Quando: Diariamente à 1h00 UTC
Função: Sincroniza produtos entre os SKUs listados no arquivo e os produtos já criados no Yuju.

Processamento em lotes

Para arquivos grandes (>500 produtos), o sistema automaticamente:

Divide o arquivo em lotes de 1.000 produtos
Processa cada lote de forma independente
Evita timeouts e erros de memória
Relata o progresso em tempo real

Exemplo: Um arquivo com 5.000 produtos é dividido em 5 lotes que são processados simultaneamente.

📁 Estrutura de pastas

Raiz do FTP/

├── orders/ # Pedidos de saída

└── products/ # Arquivos de entrada

├── processed/ # Arquivos processados com sucesso

└── failed/ # Arquivos com erros

Gerenciamento de Pedidos

Fluxo de Pedidos

Horários de processamento

Pedidos em tempo real: Processamento imediato ao receber o webhook, em qualquer um dos dois eventos: criação e atualização.
Pedidos pendentes: processamento diário às 12h
Pedidos Anteriores: Limpeza diária às 00:00 (meia-noite)

📁 Estrutura dos arquivos de pedidos

Os pedidos são gerados na pasta orders/ com a seguinte nomenclatura:

orders/

├── orders_AAAAAMMDD_HHMMSS_[ORDER_ID].txt

├── orders_AAAAMMDD_HHMMSS_[ORDER_ID].json

└── processed/

└── order_AAAAMMDD_HHMMSS_[ORDER_ID]_processed.txt

Formato do Pedido

Informações do Cliente:

Nome completo
Documento de identidade
Endereço de entrega (rua, cidade, CEP)
Telefone e e-mail de contato

Informações sobre os produtos:

SKU do produto
Nome do produto
Quantidade solicitada
Preço unitário
Preço total

Informações de pagamento:

Forma de pagamento (dinheiro, cartão, transferência)
Status do pagamento (pendente, pago, falha)
Valor total do pedido

Metadados do Marketplace:

ID do pedido no Yuju
Canal de venda (Amazon, MercadoLibre, etc.)
Data e hora do pedido
Tipo de atendimento (envio direto, retirada, etc.)

Exemplo de arquivo de pedido

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"
  }
}

Configurações especiais

Por cliente:

Campos personalizados: Campos específicos exigidos pelo seu sistema
Formato de saída: TXT delimitado, JSON, XML, conforme preferência
Formato de pagamento: Códigos numéricos vs. texto descritivo
Agrupamento: Pedidos separados ou agrupados por cliente
Pastas dinâmicas: Organização por marketplace, data ou tipo de atendimento

Filtros de pedidos:

Por status: Apenas pedidos pagos, pendentes, etc.
Por marketplace: Amazon, MercadoLibre, loja própria

Estados dos pedidos

Pending (Pendente): Pedido recebido, aguardando processamento
Processando: Pedido sendo convertido para o formato do cliente
Success (Bem-sucedida): Arquivo gerado e enviado para o FTP
Falha: Erro no processamento, requer revisão
Retry (Repetir): Pedido na fila para reprocessamento

Solução de problemas com pedidos

Problemas comuns:

A ordem não gera arquivo:

Verifique se a tarefa de ordens está habilitada
Confirmar a conectividade FTP
Verifique o formato do webhook recebido

Produtos não encontrados:

Sincronize o catálogo de produtos primeiro
Verificar SKUs no Yuju em comparação com o sistema interno
Entrar em contato com o KAM para mapeamento de produtos

Informações do cliente incompletas:

Validar campos obrigatórios no Yuju
Configurar campos obrigatórios por marketplace
Implementar validações prévias

Processo de escalonamento para pedidos:

Verificação imediata: Verificar a pasta orders/ no FTP
Contato com o KAM: Relatar pedidos ausentes ou incorretos

Campos do canal (campos por marketplace)

Os campos por marketplace (Channel Fields) permitem configurar informações específicas para cada canal (Amazon, MercadoLibre, Shopify, etc.) sem afetar as informações básicas do produto.

Processamento

Quando: Diariamente às 6h
Arquivos: Prefixos “channel_fields_xml_” ou “channel_fields_txt_”

Estrutura dos campos

Geral (aplicável a todos os canais):

price: Preço específico do canal
stock: Estoque disponível para o canal

Personalizado (específico por marketplace):

discount: Descontos especiais
title: Títulos otimizados por Marketplace

description: Descrições personalizadas
search_terms: Termos de pesquisa (Amazon)
bullet_points: Pontos-chave (Amazon)

Exemplo de configuração

{
  "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 arquivos

Formato TXT (Texto Delimitado)

Com cabeçalho:

SKU001|Produto 1|29,99|100|Eletrônicos|Descrição do produto

SKU002|Produto 2|45,00|50|Casa|Outro produto

Sem cabeçalho:

SKU001|Produto 1|29,99|100|Eletrônicos|Descrição do produto

SKU002|Produto 2|45,00|50|Casa|Outro produto

Campos do canal 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

Produtos:

<products>
  <product>
    <sku>SKU001</sku>
    <nombre>Producto 1</nombre>
    <precio>29.99</precio>
    <stock>100</stock>
    <categoria>Electronics</categoria>
  </producto>
</productos>

Campos do canal 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>

Produtos com variações

TXT:

SKU001-RED-M|SKU001|Camiseta|29,99|50|Vermelho|M

SKU001-RED-L|SKU001|Camiseta|29,99|75|Vermelho|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>

Monitoramento do sistema

Como verificar o status?

O sistema processa arquivos automaticamente e fornece indicadores claros do status:

Arquivos processados com sucesso:

São movidos para a pasta processed/
O timestamp indica quando foram processados
Os produtos aparecem no Yuju de acordo com a configuração

Arquivos com problemas:

São movidos para a pasta failed/
Requerem revisão e correção
Seu KAM receberá uma notificação automática

Indicadores de desempenho

Arquivos processados: Sucesso x falhas por dia
Produtos sincronizados: Contagens de criação/atualização
Tempo de processamento: Duração típica por operação
Disponibilidade do sistema: Tempo de atividade e conectividade

Notificações automáticas

O sistema enviará notificações automáticas ao seu KAM quando: - Arquivos grandes forem processados em lotes - Ocorrerem erros que exijam atenção - O processamento de arquivos importantes for concluído - Houver problemas de conectividade ou configuração.

Resolução de problemas

Problemas comuns

1. Arquivos não são processados

Sintomas: Os arquivos permanecem na pasta de origem após o horário de processamento

Possíveis causas: - Prefixo incorreto no nome do arquivo - Formato de arquivo inválido - Problemas de conectividade FTP

Passos a seguir:

2. Produtos não aparecem no Yuju

Sintomas: O arquivo é processado, mas os produtos não são criados/atualizados

Possíveis causas: - Dados obrigatórios ausentes no arquivo - Categorias ou campos inválidos - Problemas com a API do Yuju

Passos a seguir:

3. Variações não são detectadas

Sintomas: Produtos com variações são criados como produtos individuais

Possíveis causas: - Campo sku_simple ausente ou incorreto - Formato das variações não está em conformidade com o padrão

Passos a seguir:

Processo de escalonamento

Etapa 1: Verificação interna

Verificar o formato do arquivo em relação aos exemplos
Confirmar nomenclatura e prefixos
Verificar a estrutura de pastas FTP

Etapa 2: Contato com o KAM

Fornecer detalhes específicos do problema
Incluir arquivos de amostra (sem dados confidenciais)
Indicar a data e hora em que o problema ocorreu

Passo 3: Suporte Técnico

Seu KAM encaminhará a equipe técnica, se necessário
Revisão detalhada da configuração
Ajustes e correções conforme necessário

Melhores práticas

Recomendações de arquivos

Nomenclatura:

Usar prefixos configurados de forma consistente
Incluir data e hora: produtos_20250116_143000.txt
Evitar caracteres especiais nos nomes
Usar o formato de data ISO: AAAAMMDD

Conteúdo:

Validar dados antes de gerar arquivos
Usar sempre a codificação UTF-8
Incluir apenas produtos com dados completos
Evitar caracteres especiais no conteúdo

Tamanho:

Não há limite técnico (o sistema gerencia lotes automaticamente)
Recomendado: arquivos com 1.000 a 10.000 produtos para um equilíbrio ideal
Arquivos muito grandes (>50.000 produtos): consulte o KAM

Otimização de desempenho

Horários:

Evite enviar arquivos durante os horários de processamento automático:
- 01h00 – 01h30 UTC (Mapeamento do catálogo)
- 2h45 - 3h30 UTC (Criação de produtos)
- 4h00 - 5h00 UTC (Atualização de produtos)
- 6h00 - 7h00 UTC (Campos do canal)
Distribua arquivos grandes ao longo do dia
Coordenar uploads em massa com seu KAM

Validação prévia:

Implemente validações em seu sistema antes de gerar arquivos
Usar arquivos de teste para validar novos formatos
Manter backups de arquivos bem-sucedidos como referência

Organização:

Manter a estrutura de pastas organizada
Remover arquivos antigos das pastas processed/failed periodicamente
Documentar alterações nos formatos com seu KAM

Lista de verificação de implementação

☐ Configuração FTP/SFTP validada e testada

☐ Estrutura de pastas criada de acordo com as especificações

☐ Formatos de arquivo definidos e exemplos testados

☐ Prefixos de arquivo configurados corretamente

☐ Horários de processamento coordenados com as operações

☐ Processos internos de geração de arquivos implementados

☐ Contato com o KAM estabelecido e verificado

☐ Arquivos de teste processados com sucesso

☐ Integração com o sistema interno concluída

☐ Treinamento da equipe operacional realizado

Recomendações operacionais

Monitoramento diário:

Verificar quais arquivos são movidos para a pasta processed/
Verificar a pasta failed/ em busca de arquivos com problemas
Confirmar a sincronização no Yuju após o processamento

Manutenção semanal:

Limpar pastas de arquivos antigos
Verificar o desempenho e os tempos de processamento
Verificar se não há acúmulo de arquivos não processados

Revisão mensal:

Avaliar métricas de desempenho com o KAM
Revisar e otimizar formatos de arquivo, se necessário
Planejar melhorias ou novas funcionalidades

Suporte e contato

Seu KAM é seu principal ponto de contato para relatar qualquer problema.

Ao entrar em contato com seu KAM, inclua sempre:

Informações do cliente: nome da sua empresa e contato
Registro de dataehora: Data e hora exatas em que o problema ocorreu
Arquivo(s) afetado(s): nomes exatos dos arquivos com problemas
Descrição detalhada:
1. O que você esperava que acontecesse
2. O que realmente aconteceu
3. Passos já tentados para resolver
Arquivos de amostra: Se possível, forneça uma amostra do arquivo (sem dados confidenciais)

Canais de comunicação

Seu KAM fornecerá:

- E-mail direto para suporte.

- Canal de comunicação pelo WhatsApp.

Glossário de termos

Termos técnicos

SKU: Código único do produto (Stock Keeping Unit)
Campos do canal: Campos específicos por marketplace
Variações: Versões do mesmo produto (cor, tamanho, etc.)
Processamento em lote: Processamento em lote para arquivos grandes
FTP/SFTP: Protocolos de transferência de arquivos
Webhook: Notificação automática entre sistemas
API: Interface de programação de aplicativos

Termos do Marketplace

Yuju: Principal plataforma de comércio eletrônico
Marketplace: Canal de vendas (Amazon, Mercado Livre, etc.)
ID do canal: Identificador numérico do marketplace
Stock: Estoque disponível
Mapeamento: Sincronização do catálogo

Termos operacionais

KAM: Key Account Manager - Seu gerente de conta
SLA: Acordo de Nível de Serviço
Uptime: Tempo de funcionamento do sistema
Throughput: Quantidade de arquivos processados por período

Integração por meio de arquivos compartilhados

O que é a integração por arquivos compartilhados?

Principais características:

O que isso faz por você?

Escopo da integração

Configuração inicial (informações necessárias)

Fornecimento da pasta FTP/SFTP

Solicitações especiais

Protocolos Disponíveis

Organização e Estrutura de Pastas

1. Acesso FTP/SFTP

2. Credenciais Yuju

3. Configuração de e-mail

Configuração realizada pelo Cliente

Gerenciamento de produtos

Tipos de operações

1. Criação de produtos

2. Atualização de produtos

3. Atualização de estoque/preços

4. Mapeamento do catálogo

Processamento em lotes

📁 Estrutura de pastas

Gerenciamento de Pedidos

Fluxo de Pedidos

Horários de processamento

📁 Estrutura dos arquivos de pedidos

Formato do Pedido

Informações do Cliente:

Informações sobre os produtos:

Informações de pagamento:

Metadados do Marketplace:

Exemplo de arquivo de pedido

Formato JSON:

Configurações especiais

Por cliente:

Filtros de pedidos:

Estados dos pedidos

Solução de problemas com pedidos

Problemas comuns:

Processo de escalonamento para pedidos:

Campos do canal (campos por marketplace)

Processamento

Estrutura dos campos

Geral (aplicável a todos os canais):

Personalizado (específico por marketplace):

Exemplo de configuração

Formatos de arquivos

Formato TXT (Texto Delimitado)

Com cabeçalho:

Sem cabeçalho:

Campos do canal TXT:

Formato XML

Produtos com variações

TXT:

XML:

Monitoramento do sistema

Como verificar o status?

Arquivos processados com sucesso:

Arquivos com problemas:

Indicadores de desempenho

Notificações automáticas

Resolução de problemas

Problemas comuns

1. Arquivos não são processados

Passos a seguir:

2. Produtos não aparecem no Yuju

Sintomas: O arquivo é processado, mas os produtos não são criados/atualizados

Possíveis causas: - Dados obrigatórios ausentes no arquivo - Categorias ou campos inválidos - Problemas com a API do Yuju

Passos a seguir:

3. Variações não são detectadas

Passos a seguir:

Processo de escalonamento

Etapa 1: Verificação interna

Etapa 2: Contato com o KAM

Passo 3: Suporte Técnico

Melhores práticas

Recomendações de arquivos

Nomenclatura:

Conteúdo:

Tamanho: