Cartões vinculados automaticamente

Contexto

Com o recurso de cartões vinculados automaticamente, você pode enviar outros cartões a um usuário que já tem um cartão na Carteira do Google. Também é possível vincular cartões com antecedência a um cartão principal quando um usuário salva o cartão principal. O cartão vinculado automaticamente é agrupado com o principal, com uma chamada 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 o aviso de que um novo cartão foi adicionado	Novo cartão vinculado ao principal

Casos de uso

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

• Vincular uma oferta a um cartão de fidelidade.
• Vincular 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.

Considerações sobre o uso de cartões vinculados automaticamente

• O objeto principal e o 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 o 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 se comunicar 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 necessários. Esse é 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á um payload mínimo necessário 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, os dispositivos com o cartão atualizado vão receber o cartão vinculado. Esse cartão vinculado será agrupado com o cartão principal. Os usuários podem conferir o cartão vinculado deslizando para a direita.

Como processar exceções

Erros potenciais podem acontecer com o uso incorreto da API, que pode incluir:

Mensagem	Motivo
O objeto principal e o vinculado não compartilham o mesmo ID de emissor.	Não é possível anexar um objeto vinculado ao objeto de outro emissor.
O objeto principal e o 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 da Carteira.
O objeto vinculado já tem outro objeto vinculado. Não é possível adicionar objetos vinculados anexados.	Os objetos vinculados não podem ter outro objeto vinculado.
O objeto já está vinculado a outro. 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.