Envio de rankings via FTP/SFTP

Este documento descreve como livrarias, marketplaces e distribuidoras podem enviar listas de mais vendidos para a Publitik usando um servidor FTP/SFTP. O modelo padrão é pull: a Publitik se conecta ao servidor do parceiro e baixa o arquivo mais recente do diretório combinado. O modelo push (parceiro envia para o nosso SFTP) também está disponível sob solicitação.

1. Protocolo

Em ordem de preferência:

1. SFTP (SSH File Transfer Protocol, porta 22) — recomendado.
2. FTPS explícito (FTP over TLS, porta 21 com AUTH TLS).
3. FTP plain (porta 21) — só aceitamos quando não há alternativa, e mesmo assim restrito por IP.

2. Autenticação

• Chave SSH — preferido para SFTP. Enviamos a chave pública da Publitik (ed25519) por canal seguro; o parceiro adiciona ao authorized_keys do usuário dedicado.
• Usuário e senha — aceito; senha enviada por canal seguro (não por email em texto plano).
• Whitelist de IP — opcional mas recomendada. Conectamos a partir do IP fixo da nossa VPS de produção. Solicite o IP a help@publitik.com antes de aplicar a regra de firewall.

3. Estrutura do diretório

• Diretório dedicado para a Publitik (sugestão: /publitik/ ou /exports/publitik/).
• Permissões: listar (ls) e ler (get).
• Sem necessidade de escrita, exclusão ou criação de subdiretórios pelo nosso usuário.
• Manter os 4 a 8 arquivos mais recentes em rolling window é suficiente — não precisamos de histórico longo no FTP.

4. Nomenclatura do arquivo

Aceitamos duas convenções:

• Datada: top50_AAAA-MM-DD.csv (ou .xlsx), onde a data é o dia em que o arquivo foi gerado. Exemplo: top50_2026-05-12.csv. Recomendada quando há histórico no diretório.
• Sobrescrita: nome fixo (ex. top50.csv), substituído a cada ciclo. Usamos o mtime do arquivo para identificar o drop mais recente.

5. Formato do arquivo

Aceitos

• CSV — encoding UTF-8 (sem BOM ou com BOM, ambos funcionam), separador ; ou ,, quoting padrão RFC 4180.
• XLSX — primeira sheet é lida; demais ignoradas.

Cabeçalho

A primeira linha deve conter os cabeçalhos das colunas. O parser é tolerante a maiúsculas/minúsculas e acentos; aceita sinônimos comuns para cada campo.

Importante: o link do produto na loja do parceiro é obrigatório, não opcional. Para parceiros com catálogo amplo de títulos antigos, esgotados ou de mercado paralelo (sebos, marketplaces de usados), o link é a única fonte confiável de capa, sinopse e atributos — esses títulos frequentemente não estão em Metabooks, ISBN-Brasil ou outras bases comerciais.

Colunas

Campo	Obrigatório?	Cabeçalhos aceitos	Notas
posição	Sim	posição, posicao, rank, ranking, #	Inteiro de 1 a N.
isbn	Sim	isbn, isbn13, isbn-13, ean	13 dígitos. Quando ausente, fazemos match por título + autor.
título	Sim	título, titulo, title, nome	Texto livre.
autor	Sim	autor, autores, author	Aceitamos um ou múltiplos separados por vírgula ou ponto-e-vírgula.
editora	Sim	editora, publisher	Ajuda no enriquecimento de metadados.
link	Sim	link, url, produto, product_url	URL do produto na loja do parceiro. Usamos para enriquecer capa, sinopse e atributos faltantes — especialmente importante para títulos antigos, esgotados ou de catálogo paralelo que não constam nas bases comerciais tradicionais (Metabooks, ISBN-Brasil). Sem o link, esses títulos ficam incompletos no nosso lado.

Exemplo (CSV)

posicao;isbn;titulo;autor;editora;link
1;9788535933000;Exemplo de Título;Sobrenome, Nome;Editora Exemplo;https://loja.exemplo.com.br/livro/exemplo
2;9786555870000;Outro Livro;Autor Único;Outra Editora;https://loja.exemplo.com.br/livro/outro

6. Cadência

• Semanal é o padrão. Aceitamos diária ou quinzenal sob acordo prévio.
• O parceiro define o dia da semana e a janela aproximada do drop (ex. "segunda entre 10h e 12h BRT"). Ajustamos nosso agendador a essa janela.
• Não é necessário enviar arquivo quando não há atualização — apenas mantenha o último válido no diretório.

7. Validação e erro

• Se um drop chegar com formato inválido (cabeçalho incompatível, linhas vazias, encoding incorreto), pulamos o ciclo e registramos um alerta interno.
• Em falha persistente (mais de 2 ciclos consecutivos), abrimos contato com o responsável técnico do parceiro pelo email previamente acordado.
• Não enviamos nenhum acknowledgement automático no FTP do parceiro.

8. Segurança e privacidade

• Credenciais ficam armazenadas apenas no servidor de produção, em variáveis de ambiente acessíveis somente ao processo da aplicação. Nunca são commitadas em código nem registradas em logs.
• Conteúdo dos arquivos (rankings) é considerado dado de mercado, não dado pessoal. Não há tratamento sob LGPD nesse fluxo.
• A Publitik pode citar o parceiro como fonte do dado nas visualizações públicas, salvo acordo em contrário.

9. Como começar

1. O parceiro envia para help@publitik.com: protocolo escolhido, host, porta, usuário, método de autenticação, caminho do diretório, dia e horário do drop, e — se possível — um arquivo de amostra.
2. A Publitik valida o acesso, ajusta o parser ao layout exato e confirma o agendamento.
3. Após o primeiro drop bem-sucedido, a fonte aparece no painel da plataforma e passa a alimentar os rankings, alertas e análises.

Contato técnico

help@publitik.com — atendido pelo time técnico da Publitik. Responde em até um dia útil.