Gerenciando cartões-presente com ações em massa¶

Visão geral¶

O recurso de ações em massa permite criar, enviar, atualizar ou importar um grande número de cartões-presente de uma vez, a partir de um único arquivo ou formulário. Isso economiza bastante tempo em comparação com a gestão de cartões um a um. Este guia mostra como usar as ferramentas em massa para gerenciar seus cartões-presente com eficiência.

Acessando a página de ações em massa¶

No menu do app, clique em Bulk actions. Você também pode clicar em Open bulk tools na página inicial.

Você verá uma página com quatro abas: Import from file, Generate, Bulk update e Mass send. Cada aba corresponde a uma ação em massa específica que você pode executar e lista os trabalhos anteriores dessa ação abaixo do formulário.

Página de ações em massa com as abas Import from file, Generate, Bulk update e Mass send

Preparando seu arquivo de dados¶

Import, Bulk update e Mass send (com Import file) funcionam por meio do upload de um arquivo CSV (Comma-Separated Values, valores separados por vírgula). Generate e Mass send com Configure manually usam um formulário. Você pode criar um arquivo CSV com qualquer software de planilhas, como Microsoft Excel ou Google Sheets.

Diretrizes principais:

A primeira linha do seu arquivo CSV deve ser uma linha de cabeçalho com os nomes exatos dos campos (por exemplo, code, initial_value, email). Maiúsculas ou minúsculas não fazem diferença.
Cada linha seguinte representa um cartão-presente a ser processado.
Salve o arquivo como CSV separado por vírgulas (ponto e vírgula também funciona), com até 5 MB.
Recomendamos baixar nosso arquivo modelo (o link template em cada aba) para garantir que seus dados estejam formatados corretamente.
Dica: antes de enviar um arquivo grande, teste com um arquivo pequeno de apenas 2 a 3 linhas para garantir que tudo funcione como esperado.

Usando sua própria imagem de cartão-presente¶

Toda ação em massa que usa um arquivo CSV pode dar a cada cartão-presente sua própria arte. Adicione uma coluna image ao seu CSV e coloque nela a URL da imagem — o cartão será exibido com essa imagem na página do cartão-presente e no e-mail do cartão.

Etapa 1 — Envie suas imagens para a Shopify¶

No seu admin da Shopify, acesse Content → Files.
Clique em Upload files e selecione as imagens que você quer usar.
Aguarde até que cada upload termine.

Etapa 2 — Copie a URL da imagem¶

Passe o cursor sobre o arquivo enviado na lista.
Clique no ícone de link (Copy link) no lado direito da linha. A URL completa agora está na sua área de transferência.
Cole-a na coluna image da linha correspondente no seu CSV.

Formato que a URL precisa ter¶

Um link copiado de Content → Files tem este formato:

https://cdn.shopify.com/s/files/1/0594/1241/4670/files/gift-card-birthday.png?v=1671206648

Requisitos:

Deve ser uma URL completa que comece com https://. Links que começam com http:// ou //cdn.shopify.com/... são recusados, e o mesmo vale para um nome de arquivo simples, como gift-card-birthday.png.
Mantenha o link inteiro, incluindo a parte ?v=... no final — é a versão do arquivo que a Shopify usa para cache.
A imagem precisa permanecer em Content → Files. Se você excluir ou substituir o arquivo depois, os cartões que apontam para ele perdem a imagem.
Imagens hospedadas fora da Shopify também funcionam, desde que o link seja uma URL pública https://.

Imagem recomendada¶

Propriedade	Recomendação
Proporção	5:3 (o mesmo formato dos designs integrados)
Tamanho	950 × 550 px recomendados (o mesmo dos designs de cartão)
Formato	PNG, JPG ou WebP
Tamanho do arquivo	mantenha pequeno (algumas centenas de KB) para que os e-mails fiquem leves

Como a imagem é escolhida¶

Um valor na coluna image substitui o design selecionado na página — isso permite que um único arquivo traga uma imagem diferente para cada linha.
Na aba Mass send, as linhas sem valor em image usam o design selecionado em Gift cards images.
Se uma linha contiver algo que não é uma URL https:// válida, essa linha é marcada como Failed na página Results do trabalho, com o motivo, e nenhum cartão-presente é criado para ela. Corrija a URL e envie novamente somente essas linhas.

Emitindo cartões em outras moedas¶

Se sua loja vende em várias moedas pelo Shopify Markets, um trabalho em massa pode emitir cartões em qualquer moeda ativada pelos seus mercados — não apenas na moeda da loja.

Generate e Mass send (Configure manually): um seletor de moeda aparece ao lado do campo de valor. Em uma loja com uma única moeda, ele permanece oculto.
Mass send (Import file) e Import from file: preencha a coluna currency_code, por exemplo EUR. Uma coluna vazia significa a moeda da sua loja.
Bulk update: a moeda de um cartão não pode ser alterada. A coluna serve apenas como verificação: uma linha que indique uma moeda diferente da do cartão falha, em vez de ajustar o saldo em um dinheiro que você não pretendia.

Uma linha com uma moeda que seus mercados não ativaram falha durante o upload, com a lista de moedas que você pode usar. Nenhum cartão é criado para essa linha; as demais linhas são processadas normalmente.

Onde o cartão pode ser gasto é controlado por Cross-currency redemption na página eGift/Physical cards → E-Gift cards (em Enable Shopify Markets support): deixe na opção padrão da Shopify, restrinja o cartão à sua própria moeda, ou converta pela taxa do seu mercado ou pela taxa à vista.

Na análise, os totais do painel permanecem na moeda da sua loja. Cartões em outras moedas são listados separadamente acima dos blocos, com seus próprios totais, porque valores em moedas diferentes não podem ser somados em um único número. Veja Painel e análise.

1. Gerando cartões-presente em massa¶

Use este recurso quando quiser criar um lote de novos cartões-presente sem enviá-los a ninguém ainda. Eles são criados na Shopify como cartões ativos, prontos para serem entregues.

Como gerar cartões-presente:

Acesse a aba Generate.
Preencha o formulário Gift card details:
- Value — informe o valor monetário de cada cartão-presente (por exemplo, 25.00).
- Currency — exibido ao lado do valor somente quando seus Shopify Markets ativam mais de uma moeda. Escolha a moeda em que os cartões são emitidos. Veja Emitindo cartões em outras moedas.
- Number of gift cards — informe quantos cartões você quer criar com essas configurações, até 100.000 por trabalho.
- Prefix (opcional) — informe até 4 caracteres para adicionar ao início de cada código gerado. Isso pode ajudar a identificar depois um lote específico de cartões.
- Code length — escolha o tamanho do código único que será gerado (entre 8 e 16 caracteres). Lotes com mais de 10.000 cartões usam pelo menos 14 caracteres, para que os códigos não colidam.
- Note (opcional) — adicione uma observação interna para este lote de cartões. Essa observação não fica visível para os clientes.
- Expiration date — selecione No expiration date se não quiser que os cartões expirem, ou Set expiration date para escolher a data em que os cartões deixarão de ser válidos.
Em Gift cards images, clique no design que você quer que os cartões gerados usem.
Clique no botão Start generation.

Em seguida, o sistema cria a quantidade especificada de cartões-presente com essas configurações. O trabalho aparece na lista Generate jobs abaixo do formulário. Clique na observação dele para abrir a página Results e clique em Download results (csv), ou selecione o trabalho na lista e clique em Download CSV ou Download PDF (um arquivo pronto para impressão, com um cartão por página, mostrando o código e seu QR code).

Opção especial: Generate without import

Marque a caixa Generate without import se você pretende usar esses códigos em cartões físicos impressos. Os códigos são gerados somente para impressão: nenhum cartão-presente da Shopify é criado, então nada pode ser gasto ainda. Value, Note e a data de validade ficam desativados nesse modo. Quando os cartões impressos chegarem, importe os códigos com Upload codes na aba Physical gift cards, ou registre cada cartão no momento da venda. Veja Cartões-presente físicos.

2. Enviando cartões-presente em massa¶

Use este recurso para criar e enviar por e-mail cartões-presente para uma lista de destinatários, imediatamente ou em uma data e hora que você escolher. É ideal para campanhas de marketing, presentes corporativos ou recompensas a clientes. Cada endereço de e-mail recebe seu próprio cartão.

Na aba Mass send, escolha Configure manually para digitar os endereços de e-mail em um formulário, ou Import file para enviar um CSV.

Configure manually:

Preencha Value (e a moeda, se seus mercados ativarem mais de uma), e opcionalmente Prefix, Code length, Message, From e Note.
Em Emails, informe os endereços de e-mail dos destinatários separados por vírgulas.
Escolha um design em Gift cards images e defina a data de validade.
Em Delivery, mantenha Send now ou escolha Schedule for later e selecione Send date e Send time (veja Agendando um envio em massa).
Clique em Start mass send, ou em Schedule mass send para um trabalho agendado.

Import file, campos obrigatórios e opcionais:

Nome do campo	Obrigatório	Descrição
`initial_value`	Sim	O saldo inicial do cartão-presente.
`currency_code`	Não	Código de moeda de três letras em que o cartão é emitido, por exemplo `EUR`. Deixe vazio para a moeda da sua loja. Veja Emitindo cartões em outras moedas.
`email`	Sim	O endereço de e-mail da pessoa que recebe o cartão-presente.
`message`	Não	Uma mensagem pessoal a incluir no e-mail do cartão-presente.
`from`	Não	O nome do remetente exibido com o cartão-presente.
`note`	Não	Observação interna salva no cartão. Não visível para os clientes.
`expires_on`	Não	A data de validade do cartão-presente, no formato `YYYY-MM-DD`.
`image`	Não	Link `https://` para a arte deste cartão. Substitui o design selecionado na página. Veja Usando sua própria imagem de cartão-presente.

Observação: todo cartão de um trabalho Mass send é enviado por e-mail automaticamente. Você não precisa de colunas de notificação.

Como enviar cartões-presente a partir de um arquivo:

Abra a aba Mass send e selecione Import file.
Baixe o modelo e prepare seu arquivo CSV com as colunas obrigatórias. Confira se todos os endereços de e-mail estão corretos.
Envie seu arquivo CSV e, opcionalmente, adicione uma Mass send note.
Escolha o design padrão em Gift cards images.
Em Delivery, mantenha Send now ou escolha Schedule for later e selecione a data e a hora.
Clique em Start mass send (ou Schedule mass send) para iniciar o processo.

Agendando um envio em massa¶

Um envio em massa pode aguardar uma data e hora que você escolher, por exemplo para que todos os cartões cheguem na manhã de um feriado. Funciona da mesma forma para Configure manually e Import file.

O horário está no fuso horário do seu dispositivo, exibido abaixo dos campos. Deve estar no futuro e no máximo 365 dias à frente.
O trabalho aparece imediatamente em Mass send jobs, com Scheduled for e a data e hora abaixo da observação, e suas linhas na coluna Scheduled. Nenhum cartão-presente existe ainda.
No horário escolhido, os cartões são criados e enviados por e-mail, geralmente em até um minuto.
Até lá, você pode clicar em Cancel ao lado de Scheduled for e confirmar. Nenhum cartão é criado e ninguém recebe e-mail, e o trabalho mostra Canceled before it was sent. Quando o trabalho começa a enviar, não pode mais ser cancelado.
Para mudar o horário ou os destinatários, cancele o trabalho e agende-o novamente.

Somente um envio em massa pode ser agendado. Trabalhos Generate, Bulk update e Import sempre começam imediatamente.

3. Atualizando cartões-presente em massa¶

Use este recurso para fazer alterações em cartões-presente existentes no seu sistema. Você pode alterar o saldo, a data de validade, a observação, o cliente, o destinatário ou a imagem, ou desativá-los.

Campos obrigatórios e opcionais:

Nome do campo	Obrigatório	Descrição
`id`	`id` ou `code`	O ID do cartão-presente na Shopify.
`code`	`id` ou `code`	O código completo do cartão-presente que você quer atualizar. Espaços e traços são ignorados.
`balance`	Não	Define um novo saldo para o cartão-presente. Use o prefixo `+` ou `-` para aumentar ou diminuir o saldo (por exemplo `+10` ou `-10`).
`currency_code`	Não	Uma verificação, não uma alteração. A moeda de um cartão-presente nunca pode ser alterada, então uma linha com moeda diferente da do cartão falha, em vez de ajustar o saldo.
`expires_on`	Não	Altera a data de validade. Use o formato `YYYY-MM-DD`.
`note`	Não	Substitui a observação interna. Se a coluna estiver vazia ou ausente, a observação existente do cartão é apagada, então repita a observação antiga se quiser mantê-la.
`disabled`	Não	Defina como `1` para desativar o cartão. Atenção: esta ação não pode ser revertida. Deixe vazio para manter o cartão ativo.
`recipient_email`	Não	O endereço de e-mail da pessoa que recebe o cartão-presente.
`customer_email`	Não	O endereço de e-mail do cliente a quem o cartão pertence.
`notify_customer`	Não	Defina como `true` (ou `1`, `yes`) para enviar o cartão por e-mail ao cliente em `customer_email`.
`notify_recipient`	Não	Defina como `true` (ou `1`, `yes`) para enviar o cartão por e-mail ao destinatário em `recipient_email`.
`image`	Não	Link `https://` para a nova arte do cartão. Substitui a imagem com que o cartão foi emitido. Veja Usando sua própria imagem de cartão-presente.

Observação: atualizar o image muda o visual de um cartão já existente — o cliente vê a nova imagem na próxima vez que abrir a página do cartão-presente ou receber um e-mail sobre ele.

Como atualizar cartões-presente:

Abra a aba Bulk update.
Baixe o modelo e prepare um arquivo CSV com o code (ou id) de cada cartão-presente que você quer modificar, junto com os campos que quer atualizar.
Envie o arquivo e clique em Start import.

4. Importando cartões-presente existentes¶

Use este recurso para migrar cartões-presente de outro sistema para a nossa plataforma. Isso permite que os clientes usem os cartões que já têm com seu fornecedor anterior.

Campos obrigatórios e opcionais:

Nome do campo	Obrigatório	Descrição
`initial_value`	Sim	O saldo atual do cartão-presente no momento da importação.
`currency_code`	Não	Código de moeda de três letras em que o cartão é emitido, por exemplo `EUR`. Deixe vazio para a moeda da sua loja. Veja Emitindo cartões em outras moedas.
`code`	Não	Você pode informar um código existente: de 8 a 20 letras e números; espaços e traços são ignorados. Se não for informado, o app gera um código de presente durante a importação.
`expires_on`	Não	A data de validade do cartão importado, no formato `YYYY-MM-DD`.
`note`	Não	Observação interna salva no cartão.
`email`	Não	O cliente a quem o cartão pertence. O cliente é encontrado ou criado na Shopify por este e-mail. Nenhum e-mail é enviado a menos que `notify_customer` esteja definido.
`customer_email`	Não	Igual a `email`. Usado no lugar dele quando os dois estiverem preenchidos.
`recipient_email`	Não	O endereço de e-mail da pessoa que recebe o cartão-presente.
`notify_customer`	Não	Defina como `true` (ou `1`, `yes`) para enviar o cartão por e-mail ao cliente.
`notify_recipient`	Não	Defina como `true` (ou `1`, `yes`) para enviar o cartão por e-mail ao destinatário.
`image`	Não	Link `https://` para a arte deste cartão. Veja Usando sua própria imagem de cartão-presente.

Como importar cartões-presente:

Abra a aba Import from file.
Baixe o modelo e prepare seu arquivo CSV. Somente a coluna initial_value é obrigatória.
Envie seu arquivo, opcionalmente adicione uma Import note e clique em Start import.

Acompanhando seus trabalhos em massa¶

Depois de iniciar uma ação em massa, o trabalho aparece na lista abaixo do formulário, na mesma aba (Import jobs, Generate jobs, Update jobs ou Mass send jobs). O trabalho é processado em segundo plano, então você pode sair da página sem problemas.

A lista de trabalhos mostra, para cada trabalho:

Done — linhas processadas com sucesso.
Scheduled (somente Mass send): linhas de um trabalho agendado, aguardando sua data e hora.
In progress — linhas aguardando ou sendo processadas.
Failed — linhas que não puderam ser processadas.

Clique na observação de um trabalho para abrir a página Results. Ela mostra cada linha com seu status (Scheduled, Success, In progress, Retrying, Failed ou Canceled) e, para as linhas com falha, a mensagem de erro, para que você corrija o arquivo e envie novamente somente essas linhas. Marque Autorefresh import jobs para manter a página atualizada, e clique em Download results (csv) para obter todas as linhas com seus status e errors.

Erros comuns e solução de problemas¶

"Incorrect format of CSV file" — o arquivo não pôde ser lido como CSV. Verifique se ele foi salvo como CSV (e não como Excel) e se a linha de cabeçalho está presente. Use nosso modelo.
"Missing mandatory fields" — o upload foi recusado porque falta uma coluna obrigatória: initial_value para Import, initial_value e email para Mass send, id ou code para Bulk update. A verificação lê a sua primeira linha, então confira também se essa linha tem valor na coluna obrigatória.
"Invalid code format" — um code dessa linha é curto ou longo demais, ou contém caracteres que não são letras ou números. Use de 8 a 20 letras e números; espaços e traços são ignorados.
"An identical job ... is still running" — você iniciou o mesmo trabalho de novo (mesmo arquivo ou mesmas configurações) enquanto o primeiro ainda está sendo processado. Aguarde a conclusão em vez de iniciá-lo duas vezes.
"An identical send job is already scheduled for ...": o mesmo envio em massa já está agendado para esse horário. Se quiser agendá-lo novamente, cancele antes o trabalho agendado na lista de trabalhos. O mesmo envio em outro horário é um trabalho separado.
"This time has already passed" ou "The delivery time is in the past": a data e hora escolhidas para um envio em massa agendado já passaram, por exemplo porque o formulário ficou aberto além desse horário. Escolha um horário posterior ou selecione Send now.
"A mass send can be scheduled at most 365 days ahead": escolha uma data dentro do próximo ano.
"This mass send has already started sending" ao clicar em Cancel: o horário agendado chegou e os cartões estão sendo criados e enviados por e-mail. Um trabalho só pode ser cancelado antes disso.
Linhas marcadas como "Retrying" — a linha encontrou um erro, por exemplo o limite de requisições da Shopify, e será tentada novamente automaticamente. Nenhuma ação é necessária. Uma linha só é marcada como Failed depois que as tentativas se esgotam.