Integrações

Esta página guarda as credenciais dos canais pelos quais suas notificações podem ser enviadas. Ela não decide o que vai para onde: cada notificação escolhe os próprios canais na sua própria página.

Vá em Settings no menu de navegação à esquerda e abra a aba Integrations. Ela tem três seções: Email senders, SMS provider e Klaviyo. As alterações são salvas com o botão Save na barra de salvamento.

Onde a escolha é feita

Adicione um servidor de e-mail ou conecte o Klaviyo aqui, depois escolha-o como o Delivery method em Unused Balance Reminders ou Redemption Notifications. Conecte um provedor de SMS aqui, depois marque SMS em Channels em Redemption Notifications. Enquanto um canal não estiver configurado aqui, ele não pode ser selecionado lá.

---

Remetentes de e-mail

Por padrão, o Gift Card Hero envia e-mails aos clientes pelo próprio servidor de e-mail. Adicione aqui o seu próprio servidor SMTP e seu domínio também fica disponível como remetente, o que é reconhecido pelos clientes e é respaldado pelo histórico de entregabilidade do seu próprio domínio.

Cada notificação, e o passo de e-mail de cada fluxo de fidelidade, escolhe seu remetente separadamente: esta página guarda apenas as credenciais. Você é responsável pelos registros SPF e DKIM do seu servidor de e-mail.

1. Obtenha os dados com seu provedor de e-mail

Você precisa do host, da porta, do nome de usuário e da senha que seu provedor emite para envio de e-mails. Google Workspace, Microsoft 365, Mailgun, SendGrid, Amazon SES e a maioria dos provedores de hospedagem publicam esses dados.

As portas suportadas são 587 e 2525 (STARTTLS), 465 (SSL/TLS) e 25. A porta 587 é a escolha usual. O servidor precisa ser um endereço de servidor de e-mail público: um host que aponta para uma rede privada é recusado.

2. Conecte no Gift Card Hero

1. Abra Settings → Integrations e preencha Your mail server (SMTP): Server, Port, Security (STARTTLS, SSL/TLS ou None), Username e Password.
2. Defina Sender name e Sender email, que é o que os clientes verão. O e-mail do remetente precisa ser um endereço que seu servidor tem permissão para usar como remetente.
3. Clique em Test connection. As configurações não podem ser salvas até que um teste seja bem-sucedido, então um erro de digitação nunca vira uma série de e-mails não entregues. O selo Status mostra Configured assim que o servidor, a porta e o e-mail do remetente estiverem preenchidos.
4. Clique em Send a test email para que uma mensagem real seja entregue: o pequeno formulário que se abre vem preenchido com o e-mail de contato da sua loja, e você pode enviá-lo para qualquer outra caixa de entrada para ver a chegada.
5. Clique em Save.

Sua senha é armazenada com segurança

A senha é armazenada criptografada e nunca é exibida novamente. Deixe o campo em branco ao editar outras configurações e a senha salva será mantida.

3. Use para uma notificação ou uma mensagem de fluxo

Em Reminders ou Redemption Notifications, defina Delivery method como Your mail server (SMTP). A linha mostra qual endereço e servidor serão usados para o envio, para que você confirme de relance.

A ação Send Message de um fluxo de fidelidade tem sua própria escolha Send from, no grupo Delivery do seu passo de e-mail: Gift Card Hero email ou Your mail server (SMTP), assim que estiver configurado aqui. Um passo salvo antes dessa escolha existir continua enviando do jeito que enviava, até que você escolha um remetente para ele. Se o servidor de e-mail que um passo está configurado para usar parar de funcionar, esse e-mail ainda é enviado, mas pelo e-mail do Gift Card Hero, e o histórico de execuções do passo informa isso; um fluxo não pode ser ativado enquanto o servidor de e-mail escolhido não estiver configurado.

Mantenha as credenciais atualizadas

Se você alterar a senha do seu servidor de e-mail, atualize-a aqui também. E-mails enviados com credenciais desatualizadas são rejeitados: aparecem como Failed no log de entregas de resgates, com o motivo informado pelo seu servidor.

---

Provedor de SMS

Redemption notifications podem chegar ao portador do cartão (e, se você escolher, ao comprador) por mensagem de texto, além do e-mail ou no lugar dele. Isso é útil quando o número de telefone é o que seus clientes realmente têm. As mensagens são enviadas pela sua própria conta com um provedor de SMS, cobradas de você pelo provedor por mensagem.

Provedor suportado: Onfon Media (Quênia).

1. Obtenha os dados com a Onfon

No portal da Onfon, em Settings → API settings, você encontrará seu Client ID, sua API key e sua Access key. Você também precisa de um Sender ID, o nome do qual o texto chega. A Onfon registra Sender IDs por cliente, então use um que tenha sido aprovado para você; um Sender ID não registrado é rejeitado no momento do envio.

2. Conecte no Gift Card Hero

1. Abra Settings → Integrations e preencha SMS provider: Provider, Sender ID, Client ID, API key e, se seu provedor deu uma Access key separadamente, preencha-a também.
2. Clique em Test connection. Isso verifica as credenciais no provedor sem enviar nada: ele lê o saldo da sua conta, que é exibido para você ver que a conta tem fundos. As configurações não podem ser salvas até que um teste seja bem-sucedido.
3. Clique em Save. O selo Status muda para Connected.

Suas chaves são armazenadas com segurança

A API key e a access key são armazenadas criptografadas e nunca são exibidas novamente. Deixe-as em branco ao editar outras configurações e as chaves salvas serão mantidas. Disconnect as exclui.

3. Use para uma notificação

Em Redemption Notifications, marque SMS em Channels. O modelo de SMS e o Send test SMS ficam no editor dessa página: Integrations apenas comprova as credenciais, nunca envia um texto.

A ação Send Message de um fluxo de fidelidade também pode enviar SMS, assim que um provedor estiver conectado aqui; um fluxo com um passo de SMS não pode ser ativado até que isso aconteça.

Formato do número de telefone

O provedor precisa de números no formato internacional. Os números que a Shopify já guarda estão nesse formato; um número local digitado em outro lugar ("0712 345 678") é lido como sendo do país do provedor. Um número que não pode ser lido dessa forma é ignorado e o resgate é registrado como Not sent com o motivo.

---

Klaviyo

O Klaviyo é uma plataforma de marketing baseada em eventos. Em vez de o Gift Card Hero enviar o e-mail de lembrete, o Gift Card Hero envia um evento para a sua conta do Klaviyo, e um Flow que você cria no Klaviyo envia o e-mail de fato. Isso permite usar sua própria identidade visual, segmentação e testes A/B.

1. Obtenha uma Private API Key

No Klaviyo, vá em Settings → API keys → Private API Keys → Create Private API Key.

Dê um nome à chave (por exemplo, Gift Card Hero) e conceda estes escopos, ou simplesmente escolha Full Access:

• Events: Write: para enviar o evento de lembrete
• Profiles: Write: o evento cria ou atualiza o perfil do cliente
• Accounts: Read: usado pelo teste de conexão

Copie a chave (ela começa com pk_). O Klaviyo a mostra apenas uma vez.

2. Conecte no Gift Card Hero

1. Abra Settings → Integrations e vá até a seção Klaviyo.
2. Cole a chave em Private API key.
3. Clique em Test connection. Em caso de sucesso, um banner mostra o nome da sua conta do Klaviyo.
4. Marque Enable Klaviyo integration e clique em Save.

Sua chave é armazenada com segurança

A API key é armazenada criptografada e nunca é exibida novamente. Você só precisa digitá-la de novo se quiser substituí-la.

3. Use o Klaviyo para uma notificação

Em Reminders ou Redemption Notifications, defina Delivery method como Klaviyo. A partir daí, essa notificação envia um evento para o Klaviyo em vez de um e-mail do Gift Card Hero: lembretes enviam Gift Card Reminder, e resgates enviam Gift Card Redeemed. Cada notificação é configurada separadamente: uma pode usar o Klaviyo enquanto a outra continua enviando e-mail.

A ação Send Message de um fluxo de fidelidade também pode enviar seu próprio evento do Klaviyo, com nome definido por ação, por padrão Loyalty: <workflow name>, assim que o Klaviyo estiver conectado aqui. Um fluxo com um passo do Klaviyo não pode ser ativado até que isso aconteça.

4. Crie o Flow no Klaviyo

Crie um Flow para cada métrica que você ativou. Uma métrica sem um Flow por trás significa que os clientes não recebem nada: o evento é entregue e nada acontece em seguida.

O bloco do Klaviyo em Settings → Integrations lista os dois eventos em Events your Flows can trigger on. Event properties expande as mesmas tabelas abaixo, e How to build the Flow leva a esta seção.

O evento Gift Card Reminder contém:

Propriedade	Descrição
gift_card_id	ID do cartão-presente no Shopify
card_masked	Código mascarado, por exemplo ••••1234
card_last4	Últimos 4 caracteres do código do cartão-presente
balance	Saldo restante
amount_used	Valor já gasto
cards	O mesmo cartão como lista: id, last_characters, balance, amount_used
shop	Domínio da loja
reminder_id	ID interno (usado para evitar eventos duplicados)
is_test	true em um evento enviado pelo botão Send test event, false em um evento real

O evento Gift Card Redeemed contém:

Propriedade	Descrição
gift_card_id	ID do cartão-presente no Shopify
card_last4	Últimos 4 caracteres do código do cartão-presente
amount	Valor debitado do cartão, no formato monetário da sua loja
balance	Saldo restante após este resgate
currency	Moeda dos valores
depleted	true quando este resgate zerou o cartão
branch	Local da loja (POS), ou a filial que seu app de caixa enviou pela API REST; ausente em pedidos online
order_id, order_name	O pedido pago com o cartão
audience	Para quem a mensagem é destinada: holder ou purchaser (veja Quem é notificado)
holder_first_name, holder_last_name, holder_email	O portador do cartão, quando conhecido; preenchido em todos os eventos, inclusive os do comprador
shop	Domínio da loja
is_test	true em um evento enviado pelo botão Send test event, false em um evento real

Use depleted para criar uma bifurcação dentro de um único Flow, em vez de construir dois. Da mesma forma, um Flow pode filtrar por audience para redigir o e-mail do comprador de forma diferente do e-mail do portador do cartão; um Flow sem nenhuma condição nele é executado para ambos.

O perfil do cliente (e-mail, nome e sobrenome) é anexado ao evento automaticamente, então seu Flow pode associar o cliente e personalizar a mensagem.

5. Envie um evento de teste

Um Flow é mais fácil de criar com um evento que já está na sua conta. Send a test event envia um exemplo com todas as propriedades preenchidas (valores realistas e o domínio da sua loja) para um perfil que você escolher, para que você veja os nomes exatos das variáveis no Klaviyo e visualize a mensagem com valores de aparência real.

É um link que abre um pequeno formulário, em dois lugares:

• Settings → Integrations, na seção Klaviyo, ao lado dos nomes dos eventos, com a escolha de qual evento enviar. Também funciona com uma chave que você digitou mas ainda não salvou.
• Em Reminders e Redemption Notifications, logo abaixo da opção de entrega Klaviyo depois que ela estiver selecionada: o evento dessa notificação.

O endereço ao qual o evento será associado vem preenchido com o e-mail de contato da sua loja; use o seu próprio endereço e o e-mail do Flow chegará à sua caixa de entrada. Depois do envio, abra Profiles no Klaviyo, encontre esse perfil e veja o feed de atividades: o evento está lá, com todas as propriedades listadas, as mesmas que Event properties mostra.

Distinguindo um teste

O exemplo traz is_test: true; eventos reais trazem false. Se seu Flow fizer algo que você não gostaria que um teste disparasse, como um código de desconto ou uma tag, adicione uma condição sobre isso. Apenas o e-mail é anexado ao perfil, sem o nome do exemplo, então o seu próprio perfil do Klaviyo não é renomeado.

O modelo integrado não é usado

Quando Delivery method é Klaviyo, o modelo do Gift Card Hero para essa notificação não é enviado: o conteúdo do e-mail é totalmente controlado pelo seu Flow do Klaviyo.

---

Observações

Consentimento

Os lembretes respeitam Only customers who accepted marketing at checkout nas configurações de lembrete, independentemente do método de entrega. Mantenha essa opção ativada para cumprir GDPR/CAN-SPAM e para evitar que o Klaviyo sinalize suas mensagens.

Consentimento e notificações de resgate

As notificações de resgate são transacionais: elas informam ao cliente o que aconteceu com o próprio cartão, então o filtro de consentimento de marketing não se aplica a elas.

Alternativa

Se um canal de e-mail estiver selecionado, mas não puder ser usado (nenhuma chave do Klaviyo salva, integração desativada, chave salva inutilizável ou configurações do servidor de e-mail incompletas), o Gift Card Hero envia pelo próprio e-mail, para que os clientes ainda recebam a mensagem.

Não há alternativa para SMS: o Gift Card Hero não tem provedor de SMS próprio. Se o canal de SMS estiver ativado e o provedor tiver sido removido desde então, o texto é registrado como Not sent com esse motivo; o e-mail, se estiver ativado, ainda é enviado.

O que não é enviado

O código completo e resgatável do cartão-presente não é incluído no evento (a Shopify não o expõe depois que o cartão é criado). Use card_masked / card_last4 para exibição e direcione os clientes para a página da sua loja ou da conta deles para que visualizem e usem o cartão.