Cartões vinculados automaticamente

Contexto

Com o recurso de cartões vinculados automaticamente, é possível enviar outros cartões a um usuário que já tenha um cartão na Carteira do Google. Também é possível pré-vincular cartões a um cartão principal quando um usuário salva o cartão principal (principal). O cartão vinculado automaticamente é agrupado com o cartão principal com uma chamada acima do cartão principal informando ao usuário que um novo cartão foi vinculado. Os seguintes tipos de cartão são aceitos como cartões principais ou vinculados:

  • Ingressos de evento
  • Cartão de embarque
  • Cartão de transporte público
  • Oferta
  • Vale-presente
  • Cartão de fidelidade
  • Cartão genérico

Casos de uso

Você pode ter diferentes casos de uso para vincular cartões a um cartão atual. Veja alguns exemplos:

  • Vincular uma oferta a um cartão de fidelidade existente.
  • Vincule um vale-refeição a um cartão de embarque ou ingresso de evento.
  • Vincular um cartão de estacionamento a um ingresso de evento.

Algumas considerações ao usar cartões vinculados automaticamente

  • O objeto principal e o objeto vinculado precisam usar o mesmo emissorId.
  • Há um limite de 50 objetos vinculados por objeto principal.
  • O envio automático de cartões vinculados não é garantido e é considerado um melhor esforço. Os usuários podem desativar o recebimento de cartões vinculados automaticamente. Se o caso de uso for essencial e o usuário precisar receber o cartão vinculado, recomendamos a comunicação por outro canal para garantir que o usuário adicione o cartão.
  • As atualizações da AUP da Carteira do Google incluem orientações sobre o uso de cartões vinculados automaticamente que precisam ser seguidos.

Etapas de integração

Se você já tiver criado um objeto principal, pule a etapa 1.

  1. Crie um objeto de qualquer tipo de cartão listado com os parâmetros obrigatórios. Esse é o objeto principal.
  2. Crie outro objeto de qualquer tipo de cartão listado. Esse será o objeto linked.
  3. Antes ou depois de o objeto principal ser salvo, atualize o objeto principal com o ID do objeto vinculado no parâmetro linkedObjectIds.

Há um payload mínimo necessário para definir os linkedObjectIds em uma passagem principal. Os três parâmetros obrigatórios incluem:

  1. ISSUERID.PRIMARY_OBJECT_ID
  2. ISSUERID.PRIMARY_CLASS_ID
  3. ISSUERID.LINKED_OBJECT_ID

Exemplo de solicitação JSON para adicionar um objeto vinculado a um objeto de cartão

  …
  {
    "id": "ISSUERID.PASS_OBJECTID",
    "classId": "ISSUERID.PASS_CLASSID",
    "barcode": {
      "type": "qrCode",
      "value": "QR code"
    },
    "linkedObjectIds": {"ISSUERID.LINKED_PASS_OBJECTID"}
  }
  …

Exemplo de resposta JSON após vincular um objeto a um objeto de cartão

  …
  "state": "active",
  "linkedObjectIds": {
    "ISSUERID.LINKED_PASS_OBJECTID"
  }
  …

Comportamento esperado

Após receber uma resposta bem-sucedida, os dispositivos com o cartão atualizado vão receber o cartão vinculado. Este cartão vinculado será agrupado com o cartão principal. Para ver o cartão vinculado, os usuários podem deslizar para a direita.

Como processar exceções

Possíveis erros podem acontecer com o uso incorreto da API. Estes são alguns exemplos:

Mensagem Motivo
O objeto principal e o objeto vinculado não compartilham o mesmo ID do emissor. Não é possível anexar um objeto vinculado ao objeto de outro emissor.
O objeto principal e o objeto vinculado se referem ao mesmo objeto. Não é possível anexar o mesmo objeto que o linkedObject.
O objeto vinculado não existe. O objeto vinculado já precisa estar inserido na API Wallet.
O objeto vinculado já tem outro objeto vinculado. Não é possível adicionar objetos vinculados aninhados. Os objetos vinculados não podem ter outro objeto vinculado.
O objeto já está vinculado a outro objeto. Não é possível adicionar objetos vinculados aninhados. O objeto principal não pode ser vinculado sozinho.
Não é possível adicionar mais objetos vinculados. O limite foi excedido. O limite de 50 cartões vinculados foi atingido para o cartão principal.