Envio de catálogo editorial

Este documento descreve como editoras enviam catálogo (ficha técnica, sinopse e capa de seus títulos) para a Publitik. O objetivo é enriquecer a base com metadados autorais — quando uma capa, sinopse ou atributo vem direto da editora, ele tem precedência sobre fontes secundárias.

Para quem é esta integração

• Editoras com catálogo ativo, especialmente as que mantêm título em catálogo paralelo (esgotado, fora de catálogo comercial, edições especiais) que não aparecem em Metabooks/MVB.
• Distribuidoras que centralizam catálogo de múltiplas editoras parceiras.
• Selos editoriais dentro de grupos maiores que querem garantir a representação correta de seus títulos.

1. Protocolo

Mesma infraestrutura usada na integração de rankings via FTP. Em ordem de preferência: SFTP (porta 22), FTPS explícito (porta 21 com AUTH TLS) ou FTP plain (apenas com whitelist de IP).

2. Autenticação

Idêntica à integração de rankings: chave SSH (preferencial), usuário+senha, e/ou whitelist de IP. Solicite o IP fixo da nossa VPS a help@publitik.com antes de aplicar regra de firewall.

3. Estrutura do diretório

• Diretório dedicado (sugestão: /publitik/catalogo/).
• Permissões: listar e ler. Não precisamos de escrita.
• Manter os 3 a 6 arquivos mais recentes (rolling window) é suficiente.

4. Formato do arquivo

CSV / XLSX

Formato preferido para editoras de pequeno e médio porte. Mais simples de gerar, mais simples de validar. Encoding UTF-8, separador ; ou , (CSV), primeira sheet (XLSX).

ONIX (XML)

Formato padrão da indústria, recomendado para editoras que já publicam catálogo nesse formato. Aceitamos ONIX 3.0 (preferido) e ONIX 2.1. A primeira mensagem deve ser completa; as seguintes podem ser incrementais (apenas títulos novos ou alterados).

5. Colunas (CSV/XLSX)

Campo	Obrigatório?	Cabeçalhos aceitos	Notas
isbn	Sim	isbn, isbn13, ean	13 dígitos. Chave única do registro.
título	Sim	título, titulo, title	Título principal do livro.
subtítulo	Sim quando existir	subtitulo, subtítulo, subtitle	Quando aplicável.
autor	Sim	autor, autores, author	Múltiplos autores separados por ;. Formato livre.
editora	Sim	editora, publisher, selo	Selo editorial responsável. Importante para grupos com múltiplos selos.
sinopse	Sim	sinopse, descricao, description, synopsis	Texto livre. Pode conter HTML básico (<p>, <em>, <strong>). Limite ~2000 caracteres.
capa_url	Sim	capa, capa_url, cover, cover_url, imagem	URL HTTPS pública da imagem da capa. Veja seção Capas.
data_publicacao	Sim	data_publicacao, data, publication_date, pub_date	Formato YYYY-MM-DD.
paginas	Opcional	paginas, pages	Número inteiro.
genero	Opcional	genero, genre, categoria, tema	Texto livre ou múltiplos separados por ;.
preco	Opcional	preco, price	Preço de capa em BRL. Formato 00.00 ou 0,00.

6. Capas e imagens

• URL HTTPS pública e estável (sem expiração ou assinatura temporária).
• Formato JPEG ou PNG. Largura mínima recomendada: 800px.
• Tamanho recomendado: até 1MB. Imagens muito pesadas são redimensionadas no nosso lado.
• Em alternativa à URL, é possível enviar as imagens junto com o arquivo de catálogo num subdiretório capas/ nomeadas pelo ISBN (9788535933000.jpg). Combinar com o responsável durante a configuração da integração.

7. Cadência

• Mensal é o padrão para catálogo completo.
• Sob mudança (semanal ou mais frequente) para editoras com lançamentos ativos. Aceitamos arquivos incrementais contendo apenas títulos novos ou alterados.
• Para ONIX, recomendamos um arquivo completo por trimestre + incrementais semanais.

8. Validação e erro

• Linhas com ISBN inválido ou faltando campo obrigatório são puladas e registradas em log interno. O resto do arquivo é processado normalmente.
• Em falha de parsing (encoding errado, XML mal formado), o arquivo inteiro é rejeitado e abrimos contato com o responsável técnico do parceiro.
• Ao final de cada processamento, podemos enviar (sob acordo prévio) um relatório resumido por email com contagem de registros aceitos, atualizados e rejeitados.

9. Segurança e privacidade

• Credenciais ficam em variáveis de ambiente do servidor de produção, acessíveis apenas ao processo da aplicação. Nunca em código nem em logs.
• Conteúdo do catálogo (ficha técnica, capa, sinopse) é tratado como dado público — é a informação que a editora já distribui ao mercado. Não há tratamento sob LGPD nesse fluxo.
• A Publitik não redistribui o catálogo bruto nem vende metadados a terceiros. O uso é limitado a enriquecimento da experiência dentro do produto.
• A editora pode pedir, a qualquer momento, desativação da integração e remoção dos metadados autorais — nesse caso voltamos a usar fontes secundárias para os títulos afetados.

10. Como começar

1. A editora envia para help@publitik.com: formato escolhido (CSV, XLSX ou ONIX), protocolo (SFTP recomendado), contato técnico do lado da editora, cadência prevista, e — quando possível — um arquivo de amostra com 10 a 50 títulos.
2. A Publitik valida o acesso, ajusta o parser ao layout exato e confirma o agendamento.
3. Após o primeiro arquivo bem-sucedido, os títulos da editora passam a aparecer enriquecidos no produto e em todas as visualizações derivadas.