Referência Operações

API, webhooks e integrações

Chaves de API para logins de funcionário, o que a API faz, webhooks e seus eventos, payload, assinatura e novas tentativas, e integrações prontas: Poster, Toast, SmartKasa, Make e Zapier.

Leitura rápida

Atualizado: 19 de novembro de 2026

API e integrações

Chaves de API em API e integrações

Configurações → API e integrações tem três abas: Chaves de API, Webhooks e Integrações.

A API e as chaves de API são gratuitas em todos os planos, inclusive no Free Forever; não existe add-on de API. Os selos dados pela API são Card Operations como quaisquer outros, então param quando as Card Operations do plano se esgotam. Os webhooks são a parte paga, veja abaixo.

A API tem custo adicional?

Não. A API e as chaves de API são gratuitas em todos os planos, inclusive no Free Forever. Os selos dados por ela são Card Operations como quaisquer outros.

Posso usar a API no Free Forever?

Sim. Quando as Card Operations do plano se esgotam, os selos pela API param como quaisquer outros.

Onde ficam as configurações da API?

Em Configurações → API e integrações, com três abas — Chaves de API, Webhooks e Integrações.

Chaves de API

Gerar chave de API para um login de funcionário

Uma chave de API é criada em Chaves de API → Adicionar chave de API para um login de funcionário. Um login de funcionário tem no máximo uma chave de API, e um login de funcionário desativado não pode ser escolhido. Sem nenhum login de funcionário para escolher, a janela Gerar chave de API oferece criar um ali mesmo; um novo login de funcionário precisa de um Staff Seat livre e, com o plano cheio, a janela oferece adicionar um assento ou escolher um plano.

Toda chamada feita com uma chave de API age como o login de funcionário dela: alcança apenas a empresa desse login de funcionário, dá selos no cartão de selos escolhido para ele em Selos automáticos, e os selos contam como Card Operations desse login de funcionário.

A chave pode ser vista e copiada novamente a qualquer momento na lista Chaves de API. Ela também pode ser mostrada como código QR, para lê-la em um terminal, e impressa com o nome do login de funcionário.

Como crio uma chave de API?

Em Configurações → API e integrações → Chaves de API, escolha Adicionar chave de API e selecione um login de funcionário. Cada login de funcionário tem no máximo uma chave de API.

Perdi a minha chave de API. Preciso de uma nova?

Não. A chave pode ser vista e copiada novamente a qualquer momento na lista Chaves de API, ou mostrada como código QR.

Em qual cartão de selos as chamadas da API dão selos?

No escolhido para o login de funcionário da chave em Selos automáticos. Os selos dela contam como Card Operations desse login de funcionário.

Por que não consigo escolher um login de funcionário para uma nova chave?

Um login de funcionário desativado não pode ser escolhido, e um login de funcionário que já tem uma chave não pode receber uma segunda. Sem nenhum para escolher, a janela oferece criar um login de funcionário.

Quando uma chave de API deixa de funcionar

Uma chave de API não expira. Ela só deixa de funcionar quando é gerada novamente ou excluída, ou quando o login de funcionário dela é desativado ou excluído. Uma nova senha ou um novo login para o login de funcionário não a afetam.

  • Gerar novamente dá ao login de funcionário uma nova chave de API; a antiga deixa de funcionar imediatamente.
  • Excluir interrompe a chave imediatamente. O próprio login de funcionário continua funcionando no 7Stamp Scanner e pode receber uma nova chave depois.
  • Desativar um login de funcionário mantém a chave dele: quando o login de funcionário é reativado, a mesma chave volta a funcionar.

Uma chave de API expira?

Não. Ela só deixa de funcionar quando é gerada novamente ou excluída, ou quando o login de funcionário dela é desativado ou excluído.

Mudei a senha do login de funcionário. Preciso de uma nova chave de API?

Não. Uma nova senha ou um novo login não afetam a chave de API.

Reativei um login de funcionário. A chave de API antiga dele funciona?

Sim. Desativar um login de funcionário mantém a chave dele, e a mesma chave volta a funcionar quando ele é reativado.

O que a API faz

Pela API, um sistema pode:

  • distribuir um cartão de selos como link ou QR;
  • adicionar selos;
  • ler um cartão com os selos, as metas e os vales-presente;
  • emitir um vale-presente diretamente para um cartão;
  • resgatar um vale-presente pelo código do vale-presente;
  • enviar uma mensagem a um comprador.

A API encontra o cartão de um comprador pelo identificador próprio da empresa, como um ID do CRM, telefone ou e-mail, enviado como external_id. O identificador é armazenado no cartão e volta em todo webhook sobre ele. A API não tem uma chamada que liste os compradores de uma empresa: toda a base de compradores é extraída apenas pela exportação do admin.

Em vez de uma chave de API, um app pode entrar com o login e a senha de um login de funcionário — para um dispositivo em que um caixa faz login. Uma chave de API é adequada para um dispositivo que funciona sem operador. Os webhooks são adicionados apenas no admin; a API não tem chamada para assinar eventos nem para listá-los.

A API não define limite de requisições: as chamadas não são limitadas por número ou frequência, e o mesmo cartão pode ser lido de novo imediatamente. O que limita os selos por ela são as Card Operations do plano.

Podemos adicionar selos pelo nosso próprio CRM ou POS?

Sim, pela API. Ela distribui cartões de selos, adiciona selos, lê cartões e resgata vales-presente. Para que o seu sistema seja avisado sobre eventos, adicione um webhook — isso exige o add-on Webhooks & Events.

Podemos exportar os dados?

Pela API, você lê cartões pelo seu próprio identificador, e os webhooks enviam eventos à medida que acontecem. A API não tem uma lista de todos os compradores — toda a base de compradores é extraída pela exportação do admin.

Como a API encontra o cartão de um comprador?

Pelo seu próprio identificador — um ID do CRM, telefone ou e-mail — enviado como external_id. Ele é armazenado no cartão e volta em todo webhook sobre ele.

Posso assinar webhooks pela API?

Não. Os webhooks são adicionados apenas no admin.

A API tem limite de requisições?

Não. As chamadas não são limitadas por número ou frequência, e o mesmo cartão pode ser lido de novo imediatamente. Os selos são limitados apenas pelas Card Operations do plano.

Referência da API

A referência da API é pública e não exige login: Swagger em https://api.7loc.com/cards-api/docs, com o arquivo OpenAPI em https://api.7loc.com/cards-api/openapi.json. As chamadas vão para https://api.7loc.com/cards-api e exigem uma chave de API ou um login de funcionário.

Uma empresa White Label não vê link para a referência da API no admin. As chaves de API e os webhooks dela funcionam da mesma forma.

Onde está a documentação da API?

Swagger em https://api.7loc.com/cards-api/docs, público, sem necessidade de login. O arquivo OpenAPI está em https://api.7loc.com/cards-api/openapi.json.

Qual é o endereço base para as chamadas da API?

https://api.7loc.com/cards-api. As chamadas exigem uma chave de API ou um login de funcionário.

O nosso admin White Label não tem link para a documentação da API. A API funciona para nós?

Sim. Uma empresa White Label não vê link para a referência, mas as chaves de API e os webhooks dela funcionam da mesma forma.

Webhooks

Webhooks em API e integrações

Um webhook é adicionado em API e integrações → Webhooks → Adicionar webhook, com a URL que recebe os eventos. No 7Stamp, um webhook é criado para eventos de cartões de selos. Uma empresa pode adicionar vários webhooks, cada um com a sua URL.

Os webhooks exigem o add-on Webhooks & Events, $19 por mês, oferecido apenas em planos pagos. Adicionar o primeiro webhook oferece a compra; sem ele, um webhook não pode ser criado nem reativado. Um add-on mantém um webhook ativo: é possível adicionar mais, mas cada atualização de cobrança da assinatura desativa todos, menos o mais antigo.

Os webhooks enviam eventos à medida que acontecem, a partir do momento em que o webhook é adicionado. Eventos anteriores não são enviados.

Os webhooks são gratuitos?

Não. Eles exigem o add-on Webhooks & Events, $19 por mês, oferecido apenas em planos pagos. A API em si é gratuita.

Adicionei um segundo webhook e ele foi desativado. Por quê?

Um add-on Webhooks & Events mantém um webhook ativo. Cada atualização de cobrança da assinatura desativa todos, menos o mais antigo.

Um novo webhook envia eventos passados?

Não. Os eventos são enviados a partir do momento em que o webhook é adicionado.

Eventos de webhook

Um webhook recebe quinze eventos de cartões de selos, indicados em event_type: SCAN, DELIVERY_INSERT, RECEIPT_SCAN, CARD_JOINED, REWARD_EARNED, VOUCHER_ISSUED, VOUCHER_PACK, ADMIN_VOUCHER_ISSUE, VOUCHER_REDEEMED, LOTTERY_WIN, CARD_CAMPAIGN, BIRTHDAY_GREETING, AUTO_MESSAGE_VOUCHER, CARD_ADDED_TO_WALLET e CARD_REMOVED_FROM_WALLET. Os dois últimos chegam quando o passe é adicionado a uma carteira ou removido dela, com a carteira, Apple ou Google.

Uma leitura que não adiciona selo, como uma compra abaixo do preço do selo, ainda envia SCAN com zero selos adicionados. Um prêmio ganho em uma roleta é anunciado por um LOTTERY_WIN quando a roleta é girada, não por REWARD_EARNED nem por VOUCHER_ISSUED; uma roleta esperando para ser girada ainda não envia nada.

As avaliações dos compradores não são eventos de cartões de selos. Cada nova avaliação envia um evento com entity review e action created para os webhooks que têm Avaliações marcado entre os objetos na página do webhook. Um webhook adicionado aqui é configurado apenas para eventos de cartões de selos, então recebe avaliações quando Avaliações é marcado.

Um webhook é enviado quando uma leitura não adiciona selo?

Sim. Uma leitura que não adiciona selo, como uma compra abaixo do preço do selo, ainda envia SCAN com zero selos adicionados.

Qual evento me informa que um comprador ganhou na roleta?

LOTTERY_WIN, enviado uma vez quando a roleta é girada. Uma roleta esperando para ser girada ainda não envia nada.

Consigo saber quando um comprador remove o cartão da carteira?

Sim. Adicionar o passe a uma carteira e removê-lo enviam CARD_ADDED_TO_WALLET e CARD_REMOVED_FROM_WALLET, com a carteira, Apple ou Google.

Como recebo novas avaliações dos compradores por um webhook?

Abra a página do webhook e marque Avaliações entre os objetos dele. Cada nova avaliação chega então com entity review e action created; um webhook adicionado em API e integrações recebe apenas eventos de cartões de selos até lá.

Quando cada evento é enviado

EventoEnviado quando
SCANUm login de funcionário lê o cartão: no 7Stamp Scanner, pela API ou a partir de um POS como o Toast. Selos removidos no 7Stamp Scanner são um SCAN com stamps_added negativo
DELIVERY_INSERTUm comprador abre um código de selo que dá selos — um QR, um link, o próprio código ou um convite criado pela API
RECEIPT_SCANUm comprador lê um recibo fiscal no chatbot da empresa e recebe selos; amount é o total do recibo
CARD_JOINEDUm comprador recebe um novo cartão de selos, seja qual for a forma, com o external_id que você enviou
REWARD_EARNEDUma leitura alcança uma meta de Award
VOUCHER_ISSUEDUma leitura alcança uma meta de vale-presente
LOTTERY_WINUma roleta da Lottery é girada e dá um prêmio
VOUCHER_PACKUm novo cartão recebe o pacote de vales-presente do cartão de selos, todos os vales-presente em um único evento
ADMIN_VOUCHER_ISSUEUm vale-presente é emitido diretamente para um cartão, no admin ou pela API
VOUCHER_REDEEMEDUm vale-presente em um cartão é resgatado: no 7Stamp Scanner, pela API, em um POS do Toast ou pelo comprador
CARD_CAMPAIGNUma campanha alcança o cartão, uma vez por cartão, com o vale-presente da campanha, se houver
BIRTHDAY_GREETINGA mensagem de aniversário é enviada para o cartão, com o vale-presente de aniversário, se um foi emitido
AUTO_MESSAGE_VOUCHERUm gatilho de mensagem automática coloca um vale-presente no cartão, quer um canal alcance o comprador depois, quer não
CARD_ADDED_TO_WALLETO passe é adicionado ao Apple Wallet ou ao Google Wallet
CARD_REMOVED_FROM_WALLETO passe é removido de uma carteira

Cada meta que uma leitura alcança envia o seu próprio evento depois do evento da leitura, e uma meta alcançada duas vezes por uma única leitura, em duas rodadas do cartão, envia dois. Um cartão cheio que começa uma nova rodada é o mesmo cartão e não envia CARD_JOINED; um cartão emitido de novo depois que um administrador excluiu o antigo envia. Quando uma adesão traz um pacote de vales-presente e selos, CARD_JOINED vem primeiro, depois VOUCHER_PACK e depois DELIVERY_INSERT.

Um código de selo sem selos não envia DELIVERY_INSERT, um vale-presente gerado no admin sem cartão não envia ADMIN_VOUCHER_ISSUE, e uma chamada repetida da API para um vale-presente que ela já resgatou não envia um segundo VOUCHER_REDEEMED.

Qual evento me informa que um comprador alcançou uma meta?

REWARD_EARNED para uma meta de Award, VOUCHER_ISSUED para uma meta de vale-presente e LOTTERY_WIN para uma Lottery, cada um enviado depois do evento da própria leitura.

Um webhook é enviado quando selos são removidos?

Sim. Selos removidos no 7Stamp Scanner chegam como SCAN com stamps_added negativo.

Qual é a diferença entre VOUCHER_ISSUED e ADMIN_VOUCHER_ISSUE?

VOUCHER_ISSUED chega quando uma leitura alcança uma meta de vale-presente. ADMIN_VOUCHER_ISSUE chega quando um vale-presente é emitido diretamente para um cartão, manualmente no admin ou pela API.

Um comprador que entra com um código de selo envia um evento ou vários?

Vários. CARD_JOINED vem primeiro, depois VOUCHER_PACK, se o cartão de selos tiver um pacote de vales-presente, e depois DELIVERY_INSERT com os selos.

Recebo um evento para cada mensagem de campanha?

CARD_CAMPAIGN é enviado uma vez para cada cartão que a campanha alcança, com o vale-presente da campanha quando ela traz um.

O que um webhook recebe

Todo evento tem o mesmo corpo JSON: o ID do evento, a empresa e o evento com o seu tipo, o cartão de selos, os selos antes e depois, o valor da compra, o ID do pedido e o external_id que a integração enviou, o login de funcionário que fez o atendimento, os vales-presente e recompensas que ele deu, e o nome, o e-mail, o Telegram, o telefone do WhatsApp e a data de nascimento do comprador.

amount é o valor da compra em unidades menores (centavos): um valor de 12.50 enviado com a leitura chega como 1250. Fica vazio quando o evento não teve valor.

O ID do evento está no corpo e no cabeçalho X-Webhook-Event-Id. Uma nova tentativa do mesmo evento mantém o ID, então o receptor pode descartar repetições. Para uma URL do Make ou do Zapier, o evento fica na chave card_event em vez de data.

Que dados um webhook traz sobre o comprador?

Nome, e-mail, Telegram, telefone do WhatsApp e data de nascimento, junto com o cartão de selos, os selos antes e depois e os vales-presente e recompensas dados.

Em que unidade está amount?

Em unidades menores (centavos). Um valor de 12.50 enviado com a leitura chega como 1250; fica vazio quando o evento não teve valor.

Como evito processar o mesmo evento duas vezes?

Use o ID do evento, no corpo e no cabeçalho X-Webhook-Event-Id. Uma nova tentativa mantém o mesmo ID.

Por que o evento fica em card_event no Make?

Para uma URL do Make ou do Zapier, o evento fica na chave card_event em vez de data, para que os apps deles possam distingui-lo.

Assinatura

Toda entrega é assinada. O cabeçalho X-Webhook-Signature contém um timestamp e um HMAC-SHA256 desse timestamp e do corpo bruto, com a chave secreta do webhook. A chave secreta é mostrada e gerada novamente na página do webhook. Um login e uma senha de Basic auth também podem ser adicionados.

Como verifico se um webhook realmente vem do 7Stamp?

Calcule o HMAC-SHA256 do timestamp e do corpo bruto com a chave secreta do webhook e compare-o com o cabeçalho X-Webhook-Signature.

Onde encontro a chave secreta do webhook?

Na página do webhook, onde ela também pode ser gerada novamente.

Posso proteger o meu endpoint com uma senha?

Sim. Um login e uma senha de Basic auth podem ser adicionados ao webhook, além da assinatura.

Entregas com falha

Uma entrega que não recebe resposta 2xx em trinta segundos é repetida até dez vezes, cada espera quatro segundos mais longa que a anterior, então as novas tentativas terminam em cerca de quatro minutos. Uma resposta 429 com Retry-After é repetida depois desse tempo. A primeira falha de um evento gera uma notificação no admin.

Após cem entregas com falha seguidas, o webhook é bloqueado pelo sistema e não recebe mais eventos. A página dele avisa antes disso e tem um botão Desbloquear; uma entrega bem-sucedida zera a contagem.

A página de cada webhook tem um diário das entregas, com a requisição enviada e a resposta recebida. Reenviar envia o mesmo evento de novo, apenas para este webhook.

O meu servidor ficou fora do ar. Os eventos se perderam?

Cada entrega é repetida até dez vezes em cerca de quatro minutos. Depois disso, abra o diário do webhook e use Reenviar para os eventos de que precisa.

Por que o meu webhook parou de receber eventos?

Após cem entregas com falha seguidas, ele é bloqueado pelo sistema. Corrija o endpoint e toque em Desbloquear na página do webhook.

Posso ver o que foi enviado ao meu webhook?

Sim. A página de cada webhook tem um diário de entregas com a requisição enviada e a resposta recebida.

Aba Integrações

A aba Integrações

A aba Integrações lista as formas prontas por grupo:

  • Selos no seu caixa — Poster, Toast, Seu próprio POS ou CRM e Não encontrou seu POS?;
  • Recibos fiscais — SmartKasa;
  • Automação — Make, Zapier e Public Swagger.

Cada bloco informa se precisa de uma chave de API. A aba oferece os mesmos blocos em todos os países; apenas os recibos fiscais são limitados por país.

Seu próprio POS ou CRM

Uma empresa White Label não vê os blocos Make, Zapier nem Public Swagger e não recebe a oferta do Poster nem dos guias de configuração em 7stamp.com.

Quais sistemas de POS estão prontos para conectar?

Poster, e Toast quando for ativado para a plataforma — até lá, mostra Em breve. Outros sistemas se conectam pela API, com Seu próprio POS ou CRM.

As integrações são limitadas por país?

Não. A aba oferece os mesmos blocos em todos os países. Apenas os recibos fiscais são limitados por país.

Por que não vejo Make e Zapier?

Eles não são mostrados a uma empresa White Label. As chaves de API e os webhooks dela funcionam da mesma forma.

Poster

O Poster é o nosso app no marketplace do Poster. Instalar no Poster abre a página dele, e o app é configurado com a chave de API de um login de funcionário. Os selos dele contam como Card Operations desse login de funcionário.

Como conecto o Poster?

Abra Integrações → Poster e escolha Instalar no Poster. O app é configurado com a chave de API de um login de funcionário.

De quem são as Card Operations que os selos do Poster usam?

Do login de funcionário cuja chave de API o app usa.

Preciso de uma chave de API para o Poster?

Sim, a chave de API de um login de funcionário.

Toast

O Toast mostra Em breve para todas as empresas até que o acesso ao Toast seja configurado na plataforma. É um único interruptor para toda a plataforma, não uma configuração da empresa; depois de ligado, o bloco do Toast contém a própria configuração.

Cada local do Toast é conectado pelo GUID dele a um login de funcionário, sem chave de API: a empresa, o cartão de selos e o plano desse login de funcionário valem para todas as requisições do Toast vindas do local. Um local só pode ser conectado a um login de funcionário, e um login de funcionário tem um local. As requisições de um local são recusadas depois que ele é desconectado ou enquanto o login de funcionário dele está desativado ou excluído.

Cada vale-presente pode receber um produto do cardápio do Toast: no POS do Toast, ele então vira um desconto nesse produto. Um vale-presente sem produto é aplicado como desconto zero na conta, e o caixa entrega o presente manualmente. Os vales-presente são resgatados no POS do Toast, e uma roleta alcançada por uma conta paga é girada na hora. Quando o Toast desfaz uma transação, os selos dela são retirados ou os vales-presente resgatados são restaurados.

Um comprador pode aderir em um quiosque do Toast ou em uma tela voltada ao público com um número de telefone ou um e-mail. O cartão de selos é emitido na hora; o comprador não recebe nada do 7Stamp até abri-lo com o mesmo telefone ou e-mail.

Por que o Toast diz Em breve?

O acesso ao Toast é um único interruptor para toda a plataforma, não uma configuração da sua empresa. Até ele ser ligado, não há nada para conectar.

Como um local do Toast é conectado?

Pelo GUID dele a um login de funcionário, sem chave de API. O cartão de selos e o plano desse login de funcionário valem para todas as requisições do local.

O que acontece com os selos quando o Toast anula uma conta?

Quando o Toast desfaz uma transação, os selos dela são retirados ou os vales-presente resgatados são restaurados.

SmartKasa

SmartKasa na aba Integrações

O SmartKasa não precisa de chave de API. Ele é uma fonte de recibos em Leitura de recibos, adicionada por um ID de loja do SmartKasa ou pelo código da empresa, para abranger todas as lojas. Os compradores leem o recibo do SmartKasa no chatbot da empresa, e os selos vão para o login de funcionário dessa fonte de recibos.

O SmartKasa é ucraniano, e os recibos fiscais só funcionam na Ucrânia, na Eslováquia, no Cazaquistão e no Uzbequistão.

Preciso de uma chave de API para o SmartKasa?

Não. O SmartKasa é uma fonte de recibos em Leitura de recibos, adicionada por um ID de loja ou pelo código da empresa.

Onde os compradores leem um recibo do SmartKasa?

No chatbot da sua empresa. Os selos vão para o login de funcionário dessa fonte de recibos.

Em quais países os recibos fiscais funcionam?

Na Ucrânia, na Eslováquia, no Cazaquistão e no Uzbequistão.

Make e Zapier

Make na aba Integrações

O app do 7Stamp para o Make está na biblioteca pública de apps do Make: pesquise 7Stamp em qualquer cenário do Make ou use Abrir no Make na aba Integrações. O nosso app do Zapier não está no diretório público do Zapier: Abrir no Zapier é um convite que adiciona o app à conta do Zapier da própria empresa. Os dois apps funcionam com a chave de API de um login de funcionário.

Os cenários do Make e os Zaps são iniciados por webhooks do 7Stamp, então os gatilhos exigem o add-on Webhooks & Events. Ações como adicionar selos ou emitir um vale-presente precisam apenas de uma chave de API. Make e Zapier não são oferecidos a uma empresa White Label.

Onde encontro o app do 7Stamp no Make e no Zapier?

No Make, pesquise 7Stamp em qualquer cenário — o app está na biblioteca pública de apps do Make. No Zapier ele ainda não é público, então use Abrir no Zapier na aba Integrações — o convite adiciona o app à sua própria conta.

Make e Zapier precisam do add-on Webhooks & Events?

Os gatilhos precisam, porque cenários e Zaps são iniciados por webhooks do 7Stamp. Ações como adicionar selos ou emitir um vale-presente precisam apenas de uma chave de API.

Preciso de uma chave de API para o Make ou o Zapier?

Sim. Os apps funcionam com a chave de API de um login de funcionário.

Referência
Operações 28 de outubro de 2026

Planos e cobrança

Os três planos, o que é uma Card Operation, o que é contado e o que é gratuito, complementos, Packages de um Access Code e o que acontece quando um pagamento falha.

Atualizado: 28 de outubro de 2026

Abrir artigo
Referência
Operações 28 de outubro de 2026

Acesso da equipe

O que é um login da equipe, como criar, alterar, desativar e excluir um, como a equipe entra no 7Stamp Scanner, o que ela pode fazer lá e quem usa o painel de administração.

Atualizado: 28 de outubro de 2026

Abrir artigo
Referência
Operações 28 de outubro de 2026

Compradores e histórico

A lista de cartões de selos dos compradores, a página do cartão de um comprador, a exclusão de um cartão, o Registro de eventos, o que o 7Stamp guarda sobre um comprador e como os dados dele são apagados.

Atualizado: 28 de outubro de 2026

Abrir artigo