Este tutorial orienta o processo de instalação e configuração do Custom App da BonifiQ em uma loja Shopify, incluindo a criação do aplicativo, configuração das credenciais, execução do pacote de instalação, autorização da integração e ativação do bloco da BonifiQ no checkout. 

1. Criar o app no Shopify Dev Dashboard

A primeira etapa é criar um app no painel de desenvolvimento da Shopify.

Passo a passo  

1. Acesse o Shopify Dev Dashboard.
2. No menu lateral, vá em Apps.
3. Clique para criar um novo app.
4. Na tela Create an app, localize a opção Start from Dev Dashboard.
5. No campo App name, informe o nome do app.

No vídeo, foi usado um nome semelhante a: 

BonifiQ Teste


Recomendação de nome para uso real:

BonifiQ - Nome da Loja


Exemplo:

BonifiQ - Minha Loja


Clique em Create para criar o app.

2. Configurar a distribuição do app

Depois de criar o app, é necessário informar para qual loja Shopify esse app poderá ser instalado.

Passo a passo

1. No menu lateral do app Shopify, clique em Distribution.
2. Na área Custom distribution, localize o campo Store domain.
3. Preencha o domínio da loja Shopify.

Caso a loja seja Shopify Plus e o app precise ser instalado em múltiplas lojas da mesma organização, marque a opção:

Allow multi-store install for one Plus organization


Se for uma instalação comum em apenas uma loja, deixe essa opção desmarcada.

Depois de preencher o domínio corretamente, clique em Generate link.

Ao final, a Shopify deve exibir uma confirmação de que o link foi gerado com sucesso. Isso indica que o app já está pronto para ser instalado na loja informada.

3. Liberar acesso de rede para extensões de checkout

Para que o bloco da BonifiQ funcione no checkout, é necessário liberar o acesso de rede para extensões de checkout e conta.

Passo a passo

1. No menu lateral do app, clique em API access requests.
2. Role a página até encontrar a seção:

Read all orders scope


Essa permissão libera acesso ao histórico completo de pedidos da loja, e não apenas aos pedidos recentes.

1. Clique em:

Request access


1. A Shopify abrirá uma tela chamada Orders.
2. No campo de justificativa, informe o motivo pelo qual o app precisa acessar pedidos antigos.

Depois de solicitar o acesso a pedidos, volte para a tela principal de API access requests.

Você pode voltar pelo botão de voltar da própria Shopify ou pelo menu lateral, clicando novamente em:

API access request


Role a tela até localizar a seção:

Allow network access in checkout and account UI extensions


Essa permissão é necessária para que o bloco da BonifiQ no checkout consiga se comunicar com os serviços da integração.

1. Dentro dessa seção, clique em:

Request access


1. Aguarde a solicitação ser processada.
2. Após a conclusão, a Shopify deve exibir a mensagem:

Checkout and account UI extensions are enabled


Após a liberação, a tela deve exibir a confirmação:

Checkout and account UI extensions are enabled


Resultado esperado

O acesso de rede deve ficar habilitado para as extensões de checkout e conta.

Essa etapa é importante porque o bloco da BonifiQ precisa se comunicar com a integração para consultar saldo, pontos, cashback e aplicar resgates no checkout.

4. Acessar a BonifiQ e preencher os dados da Loja Virtual

Depois de configurar o app na Shopify, o cliente deve acessar a BonifiQ para cadastrar os dados do aplicativo na configuração da loja virtual.

Onde pegar os dados na Shopify

Antes de preencher a BonifiQ, volte no app criado na Shopify e copie as informações necessárias.

No Shopify Dev Dashboard:

1. Acesse o app criado para a BonifiQ.
2. No menu lateral, clique em:

Settings


1. Na seção Credentials, copie o:

• Client ID
• Client Secret

1. Para a URL da loja, utilize o domínio da loja Shopify usado na etapa de distribuição.

Exemplo:

bonifiq-plus.myshopify.com


Na BonifiQ, normalmente deve ser preenchido apenas o identificador da loja, sem .myshopify.com.

Exemplo:

bonifiq-plus


Preencher os dados na BonifiQ

1. Acesse o painel da BonifiQ.
2. Faça login com o usuário administrador da conta.
3. Confirme se está acessando a conta/tenant correto da loja Shopify.
4. No menu lateral, clique em:

Integrações


1. Em seguida, clique em:

Loja virtual


1. Na tela de Loja Virtual, localize a área de conexão da loja com a BonifiQ.
2. Preencha os campos:

• URL da loja: identificador da loja Shopify.
• Client ID: copiado em Shopify > App > Settings > Credentials.
• Client Secret: copiado em Shopify > App > Settings > Credentials.

1. Após preencher os campos, clique em:

Salvar dados do app


5. Baixar o pacote de instalação

Com os dados salvos, baixe o pacote de instalação disponibilizado pela BonifiQ.

Passo a passo

1. Na tela Loja virtual, clique em:

Baixar pacote de instalação


1. Aguarde o download do arquivo.
2. Extraia o arquivo baixado.
3. Abra a pasta extraída.

No vídeo, a pasta extraída aparece com o nome semelhante a:

bonifiq-shopify-app


Dentro da pasta aparecem arquivos como:

instalar-windows
instalar-mac.command
package.json
package-lock.json
shopify.app
extensions
scripts
README



Executar o instalador

Depois de abrir a pasta do pacote, execute o instalador correspondente ao seu sistema operacional.

Windows

No Windows, execute o arquivo:

instalar-windows


Mac

No Mac, execute o arquivo:

instalar-mac.command


O que acontece ao executar

Ao executar o instalador, será aberto um terminal.

No vídeo, o terminal exibe:

=== BonifiQ - Instalador do app Shopify ===


Em seguida, ele valida se o Node.js está instalado.

Exemplo exibido no vídeo:

Node.js encontrado na máquina


Depois disso, o instalador começa a instalar as dependências do projeto.

Durante a instalação, podem aparecer mensagens do NPM, como avisos de deprecated packages ou warnings.Fazer login na Shopify pelo Shopify CLI

Durante a execução do instalador, o navegador pode abrir automaticamente uma tela da Shopify solicitando login.

Essa tela aparece porque o instalador precisa autenticar a Shopify CLI na conta correta.

Passo a passo

1. Aguarde o navegador abrir a página de login da Shopify.
2. A tela exibirá algo como:

Fazer login
Continuar para Shopify CLI


1. Informe o e-mail da conta Shopify.
2. Clique em continuar.
3. Informe a senha.
4. Se solicitado, informe o código de autenticação.
5. Conclua o loginConfirmar se a versão do app foi criada/publicada

Depois da autenticação pelo Shopify CLI, o app deve criar ou atualizar uma versão no Shopify Dev Dashboard.

Como validar

1. Volte para o Shopify Dev Dashboard.
2. Acesse a área Versions.
3. Verifique se existe uma versão recente marcada como Active.

6. Instalar o app

Após revisar as permissões, role a tela até o final, se necessário.

Clique em:

Install app


7. Adicionar o bloco da BonifiQ no checkout

Com o app instalado, é necessário adicionar manualmente o bloco da BonifiQ no checkout da Shopify.

Passos

1. Acesse o admin da Shopify.
2. Vá em:

APPs > BonifiQ App


1.Localize Extensions

2.Clique nos três pontinhos

3.Selecione View Extensions

4.Selecione o BonifiQ - BonifiQ Plus do Checkout 

5.Vá até a seção de Order Summary > Add Block > BonifiQ

6.Salve

7.Volte em Apps > Volte até a tela de Extensions > Seleciona o BonifiQ Script

8.Após feito isso vá em Header > Add Section > BonifiQ Script e salve 

Feito esses passos o seu resgate no checkout e widget estão instalados.