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.
- Crie um objeto de qualquer tipo de cartão listado com os parâmetros obrigatórios. Esse é o objeto principal.
- Crie outro objeto de qualquer tipo de cartão listado. Esse será o objeto linked.
- 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:
- ISSUERID.PRIMARY_OBJECT_ID
- ISSUERID.PRIMARY_CLASS_ID
- 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. |