Integração Metabooks

Os metadados dos seus livros — título, autores, sinopse, preço, medidas, capa — entrando no sistema direto da Metabooks, por ISBN ou por catálogo inteiro, sem digitação.

Visão geral

A Metabooks é a plataforma brasileira de metadados do mercado editorial (da MVB): é nela que editoras cadastram seus títulos no padrão ONIX, e é dela que livrarias e distribuidores leem esses dados. Este módulo conecta o sistema à Metabooks em duas direções:

• Importação (madura, o dia a dia): busca os dados de um livro pelo ISBN, ou o catálogo completo de uma editora, e cria/atualiza os produtos correspondentes — ficha editorial, ficha técnica, capa e tudo.
• Envio: o caminho de volta — editar um livro aqui e mandar a alteração para a Metabooks por planilha, com conferência humana no meio e o envio por FTP a um clique.

Cada livro importado vira um produto comum do sistema, com o ISBN como código interno e código de barras. É esse mesmo ISBN que casa o livro com os itens das notas fiscais importadas e com o resto da casa: a Metabooks alimenta o catálogo, e o catálogo alimenta a consignação, a bonificação e as vendas.

Tudo mora no aplicativo Metabooks do menu principal: Livros (os produtos importados), Importações, Envios, Catálogo (autores, códigos BISAC, disponibilidades, editoras) e Configuração.

Configuração

1. Abra Metabooks‣Configuração‣Configurações (a mesma página existe em Definições‣Metabooks).
2. Preencha Usuário do Metabooks e Senha do Metabooks — as credenciais da sua conta no portal Metabooks.
3. Clique em Testar conexão. Se as credenciais estiverem certas, o sistema confirma e o campo Autorização do Metabooks passa a guardar o código de acesso, renovado sozinho daí em diante — você não precisa mexer nele.
4. O campo Ids do Metabooks é informativo, preenchido pela própria integração.

Ainda nessa página, o bloco Custom Product's Fields permite escolher, em Product Fields, quais campos do produto aparecem na página pública do livro no site.

Acesso. Os botões de sincronização no formulário do produto pedem o grupo Acesso ao Metabooks (em Definições‣Usuários e empresas‣Usuários, seção Metabooks Access). Os menus de configuração são de administrador.

Importar livros por ISBN

O caminho para poucos títulos — um lançamento, uma lista que chegou por e-mail:

1. Abra Metabooks‣Importações‣Importar por ISBN.
2. Cole os ISBNs no campo ISBNs — um por linha, ou separados por vírgula ou espaço. Com ou sem hífens, tanto faz.
3. Clique em Importar.

Ao final, o sistema abre a lista dos livros trazidos e resume o resultado: quantos são novos, quantos foram atualizados e quantos não foram encontrados na Metabooks. A importação é segura de repetir: um livro que já existe (mesmo ISBN) é atualizado, nunca duplicado.

A importação por ISBN traz o registro completo: ficha editorial, autores com seus papéis, sinopse, preço de capa, capa e a ficha técnica inteira (medidas, peso, páginas, acabamento, NCM, idiomas).

Importar o catálogo de uma editora

Para trazer (ou ressincronizar) tudo de uma vez:

1. Abra Metabooks‣Importações‣Importar por ID da editora.
2. Informe o ID da editora (MVB) — o identificador da editora na Metabooks, por exemplo BR0089701.
3. Opcionalmente, use Limite para um teste pequeno (0 importa o catálogo inteiro), e escolha se quer Baixar capas e Baixar fichas técnicas.
4. Clique em Importar. O sistema cria uma importação de catálogo e a processa em segundo plano, página a página.

Acompanhe em Metabooks‣Importações‣Importações de catálogo: cada registro mostra o tamanho do catálogo, quantos livros já entraram e a barra de progresso. O processamento salva o avanço a cada página — se for interrompido, retoma sozinho de onde parou. Os botões Executar agora, Atualizar e Reexecutar fazem o que dizem.

Também dá para disparar do cadastro da editora: no contato, o grupo Product lista os IDs Metabooks da editora, cada um com o botão Import Catalogue.

O que é importado

No formulário do livro

Todo produto importado ganha duas abas — Metabooks (dados editoriais e comerciais) e Ficha técnica (a especificação física, a mesma de que uma gráfica orça) — e dois botões no topo, para quem tem o grupo de acesso:

• Metabooks — reimporta o registro completo deste livro, atualizando tudo;
• Atualizar ficha técnica — busca só a parte física, sem tocar no resto.

A busca de produtos também aprende com a integração: dá para procurar por autor, editora, selo e tipo de livro, e agrupar por qualquer um deles.

Envio para a Metabooks (o caminho de volta)

A lógica: quando alguém edita, em um livro, um campo que a Metabooks conhece (título, sinopse, preço, medidas, autores…), o livro entra numa fila de pendências. De tempos em tempos, alguém junta as pendências num envio, confere o antes/depois de cada alteração e gera a planilha no formato que a Metabooks aceita.

1. Veja o que está esperando em Metabooks‣Envios‣Alterações pendentes — são os livros editados desde a última conversa com a Metabooks.
2. Abra Metabooks‣Envios‣Envios para a Metabooks e crie um envio. Escolha a Tarefa: Alteração (V) para atualizar títulos que a Metabooks já tem, Cadastro novo (Z) para títulos inéditos lá.
3. Na lista de Envios, clique em Buscar alterações. O sistema traz a fila de pendências e a separa por selo: cada selo tem o seu envio, já com o MB ID Editor preenchido, porque o arquivo é assinado por uma editora só. O botão fica na lista, e não dentro do envio, porque ele olha a fila inteira; clicar de novo reenche os mesmos envios com o que mudou desde então, sem criar cópias.
4. Desmarque o que não deve ir — um livro inteiro, ou um campo isolado de um livro. Campo desmarcado simplesmente não é escrito, e coluna que a Metabooks não recebe é coluna que ela não mexe.
5. Clique em Verificar. O sistema barra tudo o que a Metabooks recusaria: livro sem ISBN, ISBN que não tem 13 dígitos, dois livros com o mesmo ISBN, cadastro novo sem os campos obrigatórios, e campo que foi apagado aqui (apagar um dado lá exige uma marca especial que este envio ainda não escreve — a verificação explica o que fazer).
6. Clique em Gerar planilha. O arquivo .xlsx sai com o nome que a Metabooks espera (por exemplo V_BR5108985_20260720_Alteracoes.xlsx) e com as células alteradas em vermelho — a própria planilha é o documento de conferência: o que está vermelho é o que estamos pedindo para mudar.
7. Clique em Enviar por FTP. Ele gera a planilha, sobe para a Metabooks e, se o servidor a aceitou, marca o envio e tira os livros da fila. Se falhar, a tela mostra o motivo e nada muda. A planilha fica arquivada no histórico do envio de qualquer jeito — nada é baixado para o seu computador sem você pedir. Nas bases de teste (dev e staging) o envio é recusado de propósito: elas carregam o dado e a senha da produção, e um clique ali chegaria à Metabooks de verdade.
8. Se preferir conferir antes, clique em Gerar planilha e depois em Baixar. Entregando à mão, use Marcar como enviada só depois que o upload der certo: é esse passo, e não a geração do arquivo, que tira os livros da fila.
9. Depois da meia-noite a Metabooks manda por e-mail uma planilha dizendo o que entrou e o que recusou. Suba esse arquivo em Envios‣Ler retorno da Metabooks (ou pelo botão dentro do envio): os livros recusados voltam para a fila com o motivo registrado, e aparecem em vermelho na aba Livros. A recusa deles é do registro inteiro — um livro barrado por uma coluna perde também as outras que iam na mesma linha.

O histórico fica: Metabooks‣Envios‣Histórico lista, campo a campo, tudo o que já foi pedido à Metabooks, em qual envio e com qual antes/depois.

Regras e guardas

Solução de problemas

"Set the Metabooks username and password…" ao importar. As credenciais não estão salvas. Volte a Configuração, preencha usuário e senha e use Testar conexão.

ISBN não encontrado. O resumo da importação lista os ISBNs que a Metabooks não conhece. Confira a digitação; se o número estiver certo, o título ainda não foi cadastrado lá pela editora responsável.

A importação de catálogo parou em "Falhou". Abra o registro em Importações de catálogo: o campo Mensagem traz o motivo (credencial expirada, ID de editora errado, instabilidade da API). Resolvida a causa, Reexecutar recomeça do zero com segurança — o que já entrou será apenas atualizado.

Livros do catálogo vieram sem medidas ou sem autores. É a limitação do feed: ele não carrega ficha técnica, e traz menos dados editoriais que o registro individual. Rode a importação com Baixar fichas técnicas marcado, ou reimporte os títulos por ISBN.

"Verificar" reclamou de um campo apagado. Apagar um dado na Metabooks exige uma marca de exclusão que o envio ainda não escreve. Ou devolva o valor ao campo, ou deixe esse livro fora do envio e faça a exclusão diretamente no painel deles.