API REST do Gift Card Hero¶

A API REST permite gerenciar cartões-presente de forma programática a partir de sistemas externos — CRMs, painéis de análise, plataformas de fidelidade, serviços de fulfillment e outros.

Configuração da API REST

URL base¶

Todas as requisições da API usam a seguinte URL base:

https://gifthero.syncu.be/api/external

Autenticação¶

Toda requisição deve incluir um token Bearer no cabeçalho Authorization:

Authorization: Bearer YOUR_API_TOKEN

Para obter seu token de API, acesse For developers no menu lateral, marque Enable REST API e salve. Clique em Send me access token — o token é enviado para o e-mail de contato da loja exibido na página.

O token não expira até que você o substitua ou revogue. Trate-o como uma senha: guarde-o nas configurações secretas da sua integração e não o cole em conversas, tickets ou documentos compartilhados.

Gerenciando seu token de API¶

Um token por vez. Sua loja tem um único token de API. Todos os sistemas que chamam a API — um POS, um CRM, o serviço de um parceiro — usam esse mesmo token.

Enviar um novo token substitui o antigo. Cada clique em Send me access token gera um novo token, e o anterior deixa de funcionar imediatamente. Atualize todas as integrações com o novo token logo em seguida. Se você só precisa consultar o token de novo, procure o e-mail anterior em vez de enviar um novo token.

Revogando um token. Se um token pode ter vazado, ou se um parceiro que o possuía não trabalha mais com você, clique em Revoke access token na página For developers e confirme. O token deixa de funcionar imediatamente, e nenhum novo token é emitido. Quando estiver pronto, clique em Send me access token para emitir um novo.

Desativando a API REST. Desmarcar Enable REST API e salvar também revoga o token. Depois de reativar a API, envie um novo token para você.

O que sua integração recebe. Uma requisição com um token substituído ou revogado recebe a resposta 401:

{
  "error": {
    "statusCode": 401,
    "name": "UnauthorizedError",
    "message": "Error verifying token : The token has been revoked or replaced."
  }
}

A solução é sempre a mesma: coloque o token atual no cabeçalho Authorization.

Tokens emitidos antes da introdução dos ids de token continuam funcionando até a primeira vez que você enviar um novo token ou revogar o token.

Outros erros de autenticação:

Status	Significado
`401`	O cabeçalho `Authorization` está ausente ou não é do tipo `Bearer`, ou o token não é válido
`402`	A loja não tem um plano ativo do Gift Card Hero

Endpoints¶

Listar cartões-presente¶

GET /gift-cards

Parâmetros:

Parâmetro	Tipo	Descrição
`status`	string	Filtra pelo status do cartão-presente
`limit`	integer	Número máximo de resultados (máximo 250)
`since_id`	string	Retorna resultados após este ID de cartão-presente
`fields`	string	Lista de campos a incluir, separados por vírgula

A requisição é repassada à lista de cartões-presente da Shopify, então valem os parâmetros próprios da Shopify para ela. Cada cartão na resposta traz um objeto recipient (id, email, name) ou null. O campo code é incluído quando o Gift Card Hero tem o código completo registrado (veja Observações importantes).

Uma requisição HEAD /gift-cards retorna 200 sem corpo. Alguns clientes HTTP a usam como verificação prévia.

Listar cartões-presente com transações¶

GET /gift-cards/transactions

Retorna os cartões-presente, do mais recente para o mais antigo, cada um com até suas 50 transações mais recentes. Oferece paginação por cursor.

Paginação:

Parâmetro	Tipo	Descrição
`limit`	integer	Cartões-presente por página (padrão 50)
`page_info`	string	Cursor para a próxima página de resultados

Filtros:

Filtro	Tipo	Descrição
`query`	string	Consulta de busca, na sintaxe de busca de cartões-presente da Shopify
`balance_status`	string	Um dos valores: `full`, `partial`, `empty`, `full_or_partial`
`created_at`	string	Filtra pela data de criação
`expires_on`	string	Filtra pela data de validade
`source`	string	Um dos valores: `manual`, `purchased`, `api_client`
`status`	string	Um dos valores: `disabled`, `enabled`, `expired`, `expiring`
`initial_value`	string	Filtra pelo valor inicial
`id`	string	Filtra pelo ID do cartão-presente

Quando combinados, todos os filtros usam lógica E.

Resposta:

Cada cartão-presente tem id, balance, currency, initial_value, created_at, updated_at, disabled_at, customer_id, recipient, note, expires_on, template_suffix, last_characters, order_id, transactions e issued_by. A resposta não inclui o código do cartão-presente. Cada transação tem id, amount (negativo para um débito), processed_at, note, pos_user e pos_order_name.

IDs de transação:

transactions[].id é o id numérico da transação do cartão-presente na Shopify — o número no final do seu GID gid://shopify/GiftCardDebitTransaction/… ou gid://shopify/GiftCardCreditTransaction/…. Versões anteriores da API retornavam null aqui.

Campos do POS:

Cartões-presente emitidos ou resgatados pelo POS do Gift Card Hero trazem o operador de caixa que fez a operação. Estes campos são adicionados à resposta padrão:

Campo	Tipo	Descrição
`transactions[].pos_user`	objeto ou null	`{ "username": "woodgrove", "name": "Woodgrove" }` para um débito feito no POS; `null` nos demais casos
`transactions[].pos_order_name`	string ou null	Nome do pedido informado no POS para esse débito, se houver; `null` nos demais casos
`issued_by`	objeto ou null	`{ "username", "name", "issued_at" }` para um cartão emitido no POS; `null` nos demais casos

O registro de atividade do POS não armazena os ids de transação da Shopify, então um débito é associado a um resgate no POS pelo cartão, valor e horário (o resgate precisa ser registrado de alguns segundos antes até um minuto depois da transação). Pagamentos online, alterações feitas no admin da Shopify e débitos sem registro correspondente no POS recebem null. name é null se o usuário do POS tiver sido excluído depois.

Obter um cartão-presente¶

GET /gift-cards/{gift_card_id}

Retorna os detalhes de um cartão-presente pelo seu ID, com o recipient e, quando o Gift Card Hero tiver, o code.

Criar um cartão-presente¶

POST /gift-cards

Corpo da requisição:

{
  "note": "Loyalty reward",
  "initial_value": "50.00",
  "code": "ABCD-EFGH-IJKL-MNOP",
  "template_suffix": "custom"
}

Campo	Tipo	Obrigatório	Descrição
`note`	string	Não	Observação interna do cartão-presente
`initial_value`	string	Sim	Saldo inicial
`code`	string	Não	Código personalizado do cartão-presente (deve ser único; gerado automaticamente se omitido)
`template_suffix`	string	Não	Sufixo de template da Shopify
`customer_id`	integer	Não	Cliente da Shopify dono do cartão
`email`	string	Não	E-mail do cliente, usado quando `customer_id` não é enviado. O Gift Card Hero encontra o cliente ou cria um com a tag `gifthero:import`

O corpo é repassado ao endpoint de cartões-presente da Shopify, que aceita outros campos, como expires_on. A resposta é o cartão-presente da Shopify, incluindo o code completo.

Importante: guarde o código completo da resposta de criação, se você precisar dele. Respostas posteriores incluem o code completo apenas para os cartões que o Gift Card Hero tem registrados; nos demais, só são retornados os últimos 4 caracteres (last_characters).

Atualizar o saldo do cartão-presente¶

PUT /gift-cards/{gift_card_id}/balance

Corpo da requisição:

{
  "balance": "100.00"
}

Define o saldo do cartão-presente para o valor informado. Um valor com sinal à frente, como "+25.00" ou "-10.00", é aplicado como um ajuste ao saldo atual. Se o saldo não mudar, o saldo atual é retornado e nada é registrado. Quando a loja tem Increase limit ativado, uma recarga pode ultrapassar o limite padrão de cartões-presente da Shopify.

Esta é uma correção de saldo: não envia notificação ao cliente e não registra filial. Quando um cliente gasta o cartão em um caixa, use Resgatar um cartão-presente.

Resgatar um cartão-presente¶

POST /gift-cards/{gift_card_id}/redeem

Debita (resgata) um cartão-presente a partir de um app de POS ou caixa de terceiros, fora do checkout da Shopify. O portador do cartão recebe a notificação de resgate da sua loja (e-mail ou SMS) com o nome da filial — ou o comprador, no lugar dele, ou ambos, se Who gets notified nas suas configurações de notificações de resgate assim indicar — e o resgate aparece com sua filial nos relatórios do Gift Card Hero. Use este método em vez de chamar giftCardDebit da Shopify diretamente — um débito direto não envia filial nem notificação.

Resgatar x atualizar saldo: use Update gift card balance para definir o saldo sem notificar ninguém. Use Redeem quando um cliente gastar o cartão e você quiser registrar a notificação e a filial.

Corpo da requisição:

{
  "amount": "1500.00",
  "branch": "Westgate",
  "reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
  "note": "Table 12"
}

Campo	Tipo	Obrigatório	Descrição
`amount`	string	Sim	Valor a resgatar. Deve ser maior que 0 e não maior que o saldo do cartão, na moeda do cartão, com até 2 casas decimais
`branch`	string	Sim	Nome da filial ou local. Exibido no e-mail e no SMS de resgate (quando Include the store location está ativo nas notificações de resgate) e nos relatórios
`reference`	string	Sim	Seu ID único para este resgate, com até 255 caracteres. Veja Tentativas e duplicatas
`note`	string	Não	Gravado na transação do cartão-presente na Shopify. O Gift Card Hero acrescenta `[ref:<reference>]` à observação, para que você associe cada resgate da API à sua referência no admin da Shopify

Resposta (200):

{
  "id": 661944893757,
  "last_characters": "7nsf",
  "amount": "1500.00",
  "currency": "KES",
  "balance_before": "5090.00",
  "balance": "3590.00",
  "branch": "Westgate",
  "reference": "pos-app:7f3c2b9e-0d1a-4c55-9b7e-2f8a6c1d3e4f",
  "processed_at": "2026-10-12T10:30:00Z",
  "notification": "queued",
  "duplicate": false
}

Campo	Descrição
`notification`	`queued` — a notificação de resgate foi entregue às configurações de notificações de resgate da sua loja, que decidem se ela será enviada (a cada resgate, ou somente quando o cartão for usado por completo). `disabled` — as notificações de resgate estão desativadas na sua loja
`duplicate`	`true` quando este `reference` já foi processado e a resposta é o resultado original

Erros:

Os erros seguem o formato habitual: {"error": {"statusCode": 422, "name": "...", "message": "..."}}.

Status	Significado	O que fazer
`400`	`amount`, `branch` ou `reference` está ausente ou é inválido	Corrija o corpo da requisição
`401`	O token está ausente, é inválido, foi revogado ou substituído por um mais novo	Confira o cabeçalho `Authorization`. Se o token foi revogado ou substituído, solicite um novo
`403`	O app não tem uma permissão de acesso na sua loja	O proprietário da loja deve aprovar as permissões atualizadas do app no admin da Shopify
`404`	Cartão-presente não encontrado	Confira o ID do cartão-presente
`409`	O `reference` já foi usado para outro cartão ou valor, ou uma requisição com este `reference` ainda está sendo processada	Para um novo resgate, use um novo `reference`. Se uma requisição ainda estiver em processamento, aguarde alguns segundos e tente novamente com o mesmo `reference`
`422`	O cartão está desativado ou expirado, ou o valor é maior que o saldo. A `message` indica qual. O saldo não foi alterado	Corrija a causa. O `reference` não foi consumido, então tente novamente com o mesmo
`429`	A Shopify está limitando as requisições da sua loja	Aguarde e tente novamente com o mesmo `reference`
`500`	Não foi possível confirmar o resultado com a Shopify	Tente novamente com o mesmo `reference`: o cartão não é debitado duas vezes

Uma requisição com falha (404 ou 422) não consome o reference.

Tentativas e duplicatas¶

Gere um reference para cada resgate e reutilize-o somente ao tentar novamente o mesmo resgate. Se uma requisição expirar ou falhar na rede, tente novamente com o mesmo reference. Isso é sempre seguro: o cartão nunca é debitado duas vezes, e você recebe de volta o resultado original com "duplicate": true.

Atualizar um cartão-presente¶

PUT /gift-cards/{gift_card_id}

Somente os campos a seguir podem ser atualizados:

Campo	Tipo	Descrição
`expires_on`	string	Data de validade
`note`	string	Observação interna
`template_suffix`	string	Sufixo de template da Shopify
`customer_id`	integer	Cliente da Shopify dono do cartão. Você pode enviar `email` no lugar, como ao criar um cartão

A resposta inclui o code quando o Gift Card Hero o tiver registrado.

Desativar um cartão-presente¶

POST /gift-cards/{gift_card_id}/disable

Desativa o cartão-presente permanentemente. Esta ação não pode ser desfeita. Retorna o cartão desativado.

Pesquisar cartões-presente¶

GET /gift-cards/search

Parâmetros:

Parâmetro	Tipo	Descrição
`order`	string	Ordem de classificação
`query`	string	Consulta de busca, por exemplo `last_characters:mnop`. Use `recipient:name@example.com` para encontrar cartões enviados a um destinatário
`limit`	integer	Número máximo de resultados
`fields`	string	Lista de campos a incluir, separados por vírgula

Campos indexados (disponíveis para consultas de busca):

created_at, updated_at, disabled_at, balance, initial_value, amount_spent, last_characters

Associar códigos de cartão-presente a um pedido¶

POST /gift-cards/assign-to-order

Associa seus próprios códigos de cartão-presente a um pedido da Shopify, para lojas que geram códigos fora do app. Funciona apenas quando Skip gift codes generation está ativado nas configurações de Regular products as gift cards; caso contrário, retorna 400. Também retorna 400 se orderId não for numérico ou se um código já existir na sua loja, e 404 se o pedido não for encontrado.

Oferece suporte à associação de um único código ou de vários códigos.

Código único:

{
  "orderId": "1234567890",
  "giftCode": "ABCD-EFGH-IJKL-MNOP"
}

Vários códigos:

{
  "orderId": "1234567890",
  "giftCodes": [
    { "lineItemId": "111", "code": "ABCD-EFGH-IJKL-MNOP" },
    { "lineItemId": "222", "code": "QRST-UVWX-YZ12-3456" }
  ]
}

Resposta:

{
  "scheduled": true
}

scheduled é false quando o pedido não tem cartões-presente a processar.

Paginação¶

O endpoint de transações usa paginação por cursor. A resposta inclui um cabeçalho Link com o cursor da próxima página:

Link: <https://gifthero.syncu.be/api/external/gift-cards/transactions?page_info=CURSOR>; rel="next"

O cabeçalho não aparece na última página. Extraia o valor de page_info do cabeçalho Link e envie-o como parâmetro de consulta na sua próxima requisição, com os mesmos filtros. A URL da próxima página já os contém.

Observações importantes¶

Unicidade do código — ao criar cartões-presente com códigos personalizados, cada código deve ser único. A API retorna um erro se um código duplicado for enviado.
Visibilidade do código — a resposta de criação inclui o código completo. Em respostas posteriores, o campo code aparece apenas para os cartões cujo código completo o Gift Card Hero tem registrado (os cartões que ele gerou e os códigos que você associou). Nos demais, só os últimos 4 caracteres (last_characters) são retornados. O endpoint de transações nunca retorna códigos.
Novas tentativas de resgate — envie sempre um reference único ao resgatar um cartão-presente e tente novamente com o mesmo reference após um timeout. Veja Tentativas e duplicatas.
Limites de requisições — as requisições são repassadas à Shopify, então valem os limites da Shopify para sua loja. Se receber uma resposta 429, aguarde e tente novamente.
Coleção do Postman — cobre os endpoints de cartões-presente, exceto /gift-cards/transactions e /gift-cards/assign-to-order.

Coleção do Postman¶

Baixe a coleção do Postman para explorar a API rapidamente:

Baixar a coleção do Postman