Central de Ajuda › Conectar sua loja
Escolher o método de integração
Conector nativo (Shopify, WooCommerce, Nuvemshop, Loja Integrada, Bling) ou um dos métodos genéricos. Qual serve para a sua loja e o que muda entre eles.
Integrar é ensinar sua loja a avisar o Folhear quando uma venda é confirmada. Todos os caminhos terminam no mesmo lugar — o livro na biblioteca do comprador — e se dividem em dois grupos: conectores nativos, em que o Folhear já conhece a sua plataforma, e os métodos genéricos, que servem a qualquer sistema.
Conectores nativos: o caminho curto
Se a sua loja é uma destas, não há nada a programar — você conecta pelo portal e pronto.
| Plataforma | Como conectar |
|---|---|
| Shopify | App criado dentro da sua loja, com duas permissões de leitura |
| WooCommerce | Chave de API gerada na sua loja WordPress, com permissão de Leitura |
| Loja Integrada | Chave da API e chave da aplicação, copiadas do painel da loja |
| Bling | Credenciais do app que você autoriza no painel do Bling |
| Nuvemshop | Um clique no portal e você autoriza na sua própria loja |
Métodos genéricos: para o resto
| Método | Quem avisa quem | Quando usar |
|---|---|---|
| Webhook | Sua loja chama o Folhear | Plataformas que disparam aviso de venda — o mais rápido dos genéricos |
| API Push | Seu sistema envia a venda | ERP próprio ou integração sob medida |
| API Pull | O Folhear consulta sua loja | Plataformas que não disparam webhook |
| Sincronização agendada | O Folhear consulta de tempos em tempos | Volume baixo, sem urgência de segundos |
Qual escolher
Se existe conector nativo para a sua plataforma, é ele — não porque seja mais moderno, mas porque tira o trabalho de você: o Folhear já sabe onde procurar o pedido, o comprador e o código do produto. Se não existe, e sua loja oferece webhook, use webhook: é o único genérico em que a entrega acontece em segundos sem ninguém fazer nada. Sem webhook, a API Pull e a sincronização agendada cobrem o mesmo terreno pedindo só um endpoint de consulta.
Se a sua loja é Shopify
A conexão é feita por um app criado dentro da sua própria loja. São cinco minutos, uma vez só, e o passo a passo abaixo é o caminho inteiro. Fale com a gente antes de começar: acompanhamos a primeira conexão de cada editora.
Abra a área de apps da sua loja
No admin da Shopify: Configurações › Apps e canais de venda › Desenvolver apps. Se for a primeira vez, a loja pede para permitir o desenvolvimento de apps — pode permitir, é o que libera a criação.
Crie o app e escolha duas permissões
Dê um nome (“Folhear”, por exemplo) e, em escopos da Admin API, marque apenas
read_orderseread_customers. O Folhear não pede mais nada — nem alterar produto, nem preço, nem estoque.As duas, sempre. O Folhear lê o e-mail do comprador de dentro do pedido, numa consulta só. Faltando
read_customers, não é o nome que vem vazio: a consulta inteira é recusada e nenhum pedido chega.Instale o app e revele o token
Instale o app na loja e copie o token de acesso da Admin API. Ele aparece uma única vez — se fechar a tela sem copiar, é preciso gerar outro.
Cole no Folhear
Em Integrações › Conexões, crie a conexão da Shopify e preencha o endereço da loja e o token. Depois use “Testar conexão” — ele diz o nome da sua loja quando dá certo.
Use o endereço, não o nome da loja. São coisas diferentes: a loja pode se chamar “Minha Editora” e atender em
minha-editora-a1b2c3d4.myshopify.com— a Shopify acrescenta um sufixo quando o nome já está em uso. Copie o endereço de Configurações › Domínios; com o endereço errado a conexão é salva e depois recusa o acesso, sem dizer que o problema era esse.
A leitura de e-mail e nome do comprador depende do plano da sua loja. Na Shopify, esses dados são protegidos e não são liberados pela API no plano de entrada. Sem o e-mail, a venda chega e o Folhear não tem a quem entregar o livro — se a sincronização acusar isso, é o plano da loja, não a conexão.
Existe também um botão “Conectar pela Shopify” na tela de conexão, que dispensa o token. Ele depende de o app do Folhear estar publicado na App Store da Shopify, o que ainda não aconteceu — enquanto isso, o caminho acima é o que funciona.
Se a sua loja é WooCommerce
A chave é gerada dentro da sua própria loja WordPress — sem app externo, sem aprovação de ninguém. São três minutos, uma vez só.
Gere a chave na sua loja
No painel do WordPress: WooCommerce › Configurações › Avançado › REST API › Adicionar chave. Dê uma descrição (“Folhear”), escolha permissão de Leitura — o Folhear só lê pedidos, não altera nada — e clique em Gerar chave da API.
Copie as duas na hora. A consumer key e o consumer secret aparecem uma única vez, nessa tela. Se fechar sem copiar, é preciso gerar um par novo.
Cole no Folhear
Em Integrações › Conexões, crie a conexão do WooCommerce e preencha o endereço da loja e as duas chaves. Depois use “Testar conexão” — ele diz o nome do seu site quando dá certo.
O endereço precisa começar com https://. Não é exigência nossa: o próprio WooCommerce só aceita as chaves de API em loja com HTTPS. E se a loja mora num subdiretório (
minhaeditora.com.br/loja), inclua o subdiretório no endereço.
Particularidades de hospedagem — links permanentes no modo “Simples”, servidor que não repassa a autenticação — o Folhear contorna sozinho ao conectar; você não precisa mudar nada no WordPress. O que ele não contorna é plugin de segurança que bloqueie a API por completo: se o teste de conexão disser que o endereço respondeu com uma página, é por aí que se procura.
Se a sua loja é Nuvemshop
Aqui não há token para copiar: você autoriza o Folhear dentro da sua própria loja, num clique. É o caminho mais curto de todos os conectores.
Clique em “Conectar Nuvemshop”
Em Integrações › Conexões, crie a conexão da Nuvemshop e abra “Ver detalhes”. O botão leva você para a Nuvemshop, você aprova o acesso na sua loja e volta para o portal já conectado.
Confira o que estamos pedindo
A tela de autorização mostra a que o Folhear terá acesso: ler pedidos, clientes e produtos. Só isso — nada de alterar produto, preço, estoque ou qualquer coisa na sua loja.
Preencha o SKU dos seus produtos antes de mapear. Na Nuvemshop o SKU é opcional, e sem ele o código que aparece em Integrações › Mapeamento de produtos é algo como variant:123 ou product:123 — um número que não diz nada sobre qual livro é. Preenchendo o SKU no produto, o mapeamento passa a mostrar o código que você mesmo escolheu, e fica muito mais fácil de conferir.
Se preferir colar a credencial à mão, também dá: são o ID da loja (só números) e um token de acesso gerado na área de aplicativos da sua loja, em “aplicativos sob medida” — o próprio campo do Folhear traz o caminho exato. Esse recurso depende do seu plano na Nuvemshop: hoje ele está disponível nos planos Escala e Next. Pelo botão acima não há essa exigência.
Credenciais
Cada editora tem as suas: uma chave de API e um segredo de webhook, gerados no portal. É a credencial que identifica você — não é preciso enviar nome nem CNPJ em cada venda. A chave completa aparece uma única vez, no momento em que é criada; depois disso o Folhear guarda apenas o resumo criptográfico dela.
Dá para testar antes de valer. Na tela de Integrações, o botão de testar conexão faz uma chamada real e mostra o resultado — você confirma que está tudo certo antes da primeira venda de verdade passar por ali.