logo
QR Codes•

Um passe de carteira para cada membro, pela API

Crie um QR Code por membro pela API da CodeQR, defina o que cada passe de carteira mostra, monte o link de adicionar à carteira de cada pessoa e atualize os passes depois.

Avatar for undefined
CodeQR Team
Equipe de Conteúdo

Se você tem uma lista de associados, clientes ou portadores de ingresso, cada um pode ter o próprio passe de carteira: um QR Code por registro, com o número do associado escrito abaixo do código, e um link que adiciona o passe à Apple Wallet ou à Google Wallet. Você cria os códigos pela API e manda a cada pessoa o link dela. Para colocar um código só na carteira pelo painel, leia antes Adicionar QR Code à Apple Wallet e à Google Wallet. Para chaves de API e ferramentas de automação, veja QR Codes pela API, MCP e automações.

O que você precisa

  • Plano: Business ou superior, fora do período de teste. Em qualquer outro plano a API recusa o walletPass com 403 forbidden e nenhum código é criado. Os planos estão na página de preços.
  • Uma chave de API do seu workspace, enviada como Authorization: Bearer <chave> para https://api.codeqr.io.
  • Um QR Code dinâmico por membro. O passe carrega o link curto do código, então você pode mudar o destino depois que o passe foi salvo. O código estático grava o conteúdo dentro do passe, e esse conteúdo não muda. Leia QR Code dinâmico ou estático antes de escolher.

Criar um código por membro

O POST /qrcodes aceita um objeto walletPass junto dos campos de sempre:

  • barcodeText: a linha de texto abaixo do QR Code no passe, até 40 caracteres. Use o nome ou o número do membro.
  • name: troca o nome do seu workspace no topo do passe, até 64 caracteres.
  • logo: troca o logo do seu workspace. Envie a URL de uma imagem enviada por POST /qrcodes/logo, ou uma URL https que sirva uma imagem PNG, JPEG ou WebP sem redirecionamento. A CodeQR copia a imagem externa para o armazenamento dela e devolve a URL da cópia.

Os três são opcionais. O que você deixar de fora mostra o nome e o logo do workspace.

curl -X POST https://api.codeqr.io/qrcodes \
  -H "Authorization: Bearer $CODEQR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "go.example.com",
    "type": "url",
    "url": "https://example.com/members/0042",
    "title": "Plano de associado da Padaria Central",
    "walletPass": { "name": "Padaria Central", "barcodeText": "Associado 0042" }
  }'

A resposta é o QR Code completo. Estes são os campos de que você precisa (o resto fica de fora aqui):

{
  "id": "qr_123",
  "domain": "go.example.com",
  "key": "Opf4TLRtxp8s-qr",
  "shortLink": "https://go.example.com/Opf4TLRtxp8s-qr",
  "walletPass": { "name": "Padaria Central", "barcodeText": "Associado 0042" }
}

Dê um title claro ao código. Sem ele, a Apple Wallet mostra o tipo do código e a Google Wallet mostra "QR Code" como título do passe.

Para uma lista longa, o POST /qrcodes/bulk recebe uma lista de até 100 códigos numa só requisição, cada um com o próprio walletPass. A resposta é uma lista na mesma ordem, e cada item traz o seu walletPass:

[
  {
    "id": "qr_124",
    "domain": "go.example.com",
    "key": "42MlNp1OEmTV-qr",
    "shortLink": "https://go.example.com/42MlNp1OEmTV-qr",
    "walletPass": { "barcodeText": "Associado 0043" }
  },
  {
    "id": "qr_125",
    "domain": "go.example.com",
    "key": "C2dFxpj4YZhs-qr",
    "shortLink": "https://go.example.com/C2dFxpj4YZhs-qr",
    "walletPass": { "barcodeText": "Associado 0044" }
  }
]

Guarde o id ao lado do membro no seu sistema. Você vai precisar dele para atualizar o código depois.

Montar o link de cada membro

Pegue domain e key da resposta e monte:

https://<domain>/pass/<key>/add

Para o primeiro código acima, o link é https://go.example.com/pass/Opf4TLRtxp8s-qr/add. O link decide pelo aparelho: iPhone, iPad e Safari no Mac vão direto para a Apple Wallet, o Android vai direto para a Google Wallet e todo o resto cai na página do passe do código, onde a pessoa escolhe a carteira. Os navegadores internos do Instagram, do LinkedIn e de apps parecidos não conseguem entregar um passe para a carteira, então também caem na página do passe. O artigo do passe de carteira tem os detalhes, inclusive /apple e /google para fixar a carteira.

Depois, mande o link para onde o membro vai abri-lo no celular: o e-mail de confirmação do cadastro ou do pedido, ou um botão na área de associados. Aberto no computador, o link mostra a página do passe.

Mudar um passe depois

Atualize um código com PUT /qrcodes/<id>. Para o walletPass, valem três regras:

  • Se você não enviar walletPass, o valor guardado continua.
  • Se enviar null, ele é apagado.
  • Se enviar um objeto, ele substitui o guardado por inteiro. Os campos que ficaram de fora do objeto são apagados, não mesclados.

Por causa da terceira regra, esta atualização, que envia só o barcodeText, apaga o nome definido na criação:

{ "walletPass": { "barcodeText": "Associado 0042 (Ouro)" } }

A resposta passa a trazer só esse campo:

"walletPass": { "barcodeText": "Associado 0042 (Ouro)" }

Para mudar um campo só, envie o objeto inteiro de novo com aquele campo alterado.

O que chega a um passe que alguém já salvou depende do que você muda:

  • O destino de um código dinâmico: todo passe salvo abre o novo. Ninguém precisa salvar o passe de novo.
  • Texto, nome e logo: a mudança só chega a quem salvar o passe depois dela. Quem salvou antes fica com a versão antiga até salvar de novo.
  • Código estático: para mudar o conteúdo, crie outro código e mande ao membro o novo link.

Arquivar um código marca como expirados os passes salvos na Google Wallet.

Solução de problemas

A mensagem diz que a personalização do passe de carteira exige um plano que a inclua e não vale durante o período de teste. O workspace está abaixo do Business ou ainda no teste. Nada é criado. Enviar walletPass: null é sempre aceito.