Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Contexto
O recurso de cartões vinculados automaticamente permite enviar outros cartões a um
usuário que já tem seu 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 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 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 cartão 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.
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 os 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.
Crie um objeto de qualquer tipo de cartão listado
com os parâmetros necessários. Esse é o objeto principal.
Crie outro objeto de qualquer tipo de cartão listado. Esse será o objeto
vinculado.
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:
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
Depois de receber uma resposta, os dispositivos com o cartão que você atualizou
receberão o cartão vinculado. Este 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 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 da Carteira.
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 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.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-09-04 UTC."],[[["\u003cp\u003eAuto Linked Passes enable sending additional Google Wallet passes to users, pre-linking them to an existing primary pass for a grouped experience.\u003c/p\u003e\n"],["\u003cp\u003eSupported pass types include Event tickets, Boarding passes, Transit passes, Offers, Gift cards, Loyalty passes, and Generic passes.\u003c/p\u003e\n"],["\u003cp\u003eUse cases range from linking offers to loyalty cards to attaching meal vouchers to travel documents or parking passes to event tickets.\u003c/p\u003e\n"],["\u003cp\u003eConsiderations involve shared issuer IDs, a 50-linked-pass limit, best-effort automatic pushing, and adherence to Google Wallet AUP guidelines.\u003c/p\u003e\n"],["\u003cp\u003eIntegration involves creating primary and linked objects, updating the primary object with the linked object ID, adhering to payload requirements, and understanding expected behavior and exception handling.\u003c/p\u003e\n"]]],["Auto Linked Passes enable sending additional passes to users with an existing pass in Google Wallet. Link a new pass to a primary pass by updating the primary pass object with the linked pass's ID via the `linkedObjectIds` parameter. Both passes must share the same issuer ID, with a 50-pass limit per primary object. Linked pass delivery is best-effort, not guaranteed. Common use cases include linking offers to loyalty cards or meal vouchers to boarding passes. Verify linked object existence and ensure primary objects are not themselves linked.\n"],null,["# Auto Linked Passes\n\n#### Background\n\nThe Auto Linked Passes feature lets you send additional passes to a\nuser who already has your existing pass in their Google Wallet. You can also\npre-link passes to a primary pass when a user saves the **primary**\n(main) pass. The Auto Linked Pass is grouped with the primary pass with a\ncallout above the primary pass informing the user that a new pass has been\nlinked. The following pass types are supported as primary or linked passes;\n\n- Event ticket\n- Boarding pass\n- Transit pass\n- Offer\n- Gift card\n- Loyalty pass\n- Generic pass\n\n|--------------------------------------------------------------|-------------------------------------|\n| | |\n| Primary pass with the callout that a new pass has been added | New pass linked to the primary pass |\n\n#### Use Cases\n\nYou may have different use cases for linking passes to an existing pass. Some\nexamples include:\n\n- Link an offer to an existing loyalty card.\n- Link a meal voucher to a boarding pass or event ticket.\n- Link a parking pass to an event ticket.\n\n#### Some considerations when using Auto Linked Passes\n\n- The primary object and linked object must use the same issuerId.\n- There is a limit of 50 linked objects per primary object.\n- Pushing linked passes automatically is not guaranteed and considered best-effort. Users can opt out of receiving Auto Linked Passes. If the use case is critical and the user must receive the linked pass, we recommend communicating through another channel to ensure the user adds the pass.\n- Updates to the [Google Wallet AUP](https://payments.developers.google.com/terms/aup) include guidance on the use of Auto Linked Passes which must be adhered to.\n\n#### Integration Steps\n\nIf you have already created a **primary** object you can skip step 1.\n\n1. Create an [object](/wallet/retail/loyalty-cards/use-cases/create) of any pass type listed with the required parameters. This is the **primary** object.\n2. Create another object of any pass type listed. This is going to be the **linked** object.\n3. Either before or after the primary object is saved, [update](/wallet/retail/loyalty-cards/use-cases/update) the primary object with the ID of the linked object in the linkedObjectIds parameter.\n\nThere is a minimum payload required to set the linkedObjectIds on a primary\npass. The 3 required parameters include;\n\n1. ISSUERID.PRIMARY_OBJECT_ID\n2. ISSUERID.PRIMARY_CLASS_ID\n3. ISSUERID.LINKED_OBJECT_ID\n\n#### Example JSON Request to add a linked object to a pass object\n\n```carbon\n ...\n {\n \"id\": \"ISSUERID.PASS_OBJECTID\",\n \"classId\": \"ISSUERID.PASS_CLASSID\",\n \"barcode\": {\n \"type\": \"qrCode\",\n \"value\": \"QR code\"\n },\n \"linkedObjectIds\": {\"ISSUERID.LINKED_PASS_OBJECTID\"}\n }\n ...\n```\n\n#### Example JSON Response after linking an object to a pass object\n\n```scdoc\n …\n \"state\": \"active\",\n \"linkedObjectIds\": {\n \"ISSUERID.LINKED_PASS_OBJECTID\"\n }\n …\n```\n\n#### Expected behavior\n\nAfter receiving a successful response, devices with the pass you updated\nshould receive the linked pass. This linked pass will be grouped together with\nthe primary pass. Users can see the linked pass by swiping right.\n\n#### Exception handling\n\nPotential errors may happen with incorrect use of the API which can\ninclude;\n\n| **Message** | **Reason** |\n|------------------------------------------------------------------------------------|----------------------------------------------------------------------|\n| Primary object and linked object don't share the same issuer ID. | You cannot attach a linked object to another issuer's object. |\n| Primary object and linked object refer to the same object. | You cannot attach the same object as the linkedObject. |\n| Linked object does not exist. | The linked object should already be inserted into the Wallet API. |\n| Linked object already has another linked object. Cannot add nested linked objects. | Linked objects cannot have another linked object. |\n| Object is already linked to another object. Cannot add nested linked objects. | Primary object cannot be a linked object by itself. |\n| Cannot add any more linked objects, limit exceeded. | The limit of 50 linked passes has been reached for the primary pass. |"]]
