Cartões vinculados automaticamente

Contexto

Com o recurso de cartões vinculados automaticamente, você pode enviar outros cartões para um usuário que já tem 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 balão acima dele informando ao usuário que um novo cartão foi vinculado. Os seguintes tipos de cartão são aceitos como 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

Cartão principal com a observação de que um novo cartão foi adicionado	Novo cartão vinculado ao cartão principal

Casos de uso

Você pode ter diferentes casos de uso para vincular um cartão a outro. Confira alguns exemplos:

• Vincule uma oferta a um cartão de fidelidade.
• 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 passes vinculados automaticamente

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

Etapas de integração

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

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

Há uma carga útil mínima necessária para definir os linkedObjectIds em um cartão 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

Depois de receber uma resposta positiva, os dispositivos com o cartão atualizado vão receber o cartão vinculado. O cartão vinculado será agrupado com o cartão principal. Os usuários podem ver o cartão vinculado deslizando para a direita.

Como processar exceções

Erros podem ocorrer com o uso incorreto da API, incluindo:

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 como linkedObject.
O objeto vinculado não existe.	O objeto vinculado já precisa estar inserido na API Carteira.
O objeto vinculado já tem outro objeto vinculado. Não é possível adicionar objetos vinculados aninhados.	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 um objeto vinculado por si só.
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.