Visão Geral: Configuração Gerida vs. Personalizada de Emissor Google Wallet
Ao contrário do requisito de certificado por comerciante da Apple Wallet, a Passinstance fornece uma Infraestrutura Gerida de Emissor da Google Wallet pronta a usar para que possa publicar e distribuir passes Android imediatamente durante o onboarding (PUT /api/v1/onboarding/wallet-setup). Para marcas empresariais que necessitam da propriedade do seu próprio Issuer ID da Google Pay & Wallet Console ou de chaves sem contacto Google Smart Tap personalizadas, a Passinstance também suporta a associação de uma Conta de Serviço do Google Cloud dedicada (POST /api/v1/google-wallet/setup).
Pré-requisitos: Ao configurar um Issuer ID personalizado da Google Wallet, tem de convidar o
client_emailda Conta de Serviço do Google Cloud na Google Pay & Wallet Business Console -> Utilizadores com permissões de Developer. Sem esta vinculação IAM, a APIwalletobjectsda Google devolve403 Forbiddenquando a Passinstance tenta criar Classes ou Objetos.
Comparação entre Modo de Emissor Google Gerido vs. Personalizado
| Capacidade | Emissor Gerido Passinstance | Issuer ID Empresarial Personalizado |
|---|---|---|
| Tempo de Configuração | Instantâneo (0 minutos) | ~15 minutos (Google Cloud + Business Console) |
| Nome da Marca e Logótipo no Cartão | Totalmente personalizado por modelo (issuerName, programLogo) | Totalmente personalizado por modelo (issuerName, programLogo) |
| Acesso à Google Pay & Wallet Console | Gerido pela Passinstance | Acesso direto à sua própria Google Business Console |
Google Smart Tap NFC (NFC_SMART_TAP) | Utiliza a configuração do espaço de trabalho/leitor | Suporta o seu próprio smartTapMerchantId e collectorId personalizados |
Webhook de Retorno (/api/v1/wallet/callback) | Pré-configurado automaticamente | Configurado automaticamente na criação da classe |
API de Configuração da Google Wallet e Ativação de Modelos (Google Wallet Setup API)
Todos os endpoints de aprovisionamento de emissores e modelos da Google Wallet encontram-se sob /api/v1/google-wallet:
| Método | Caminho do Endpoint | Permissão Necessária | Descrição |
|---|---|---|---|
| POST | /api/v1/google-wallet/setup | wallet:manage, certificates:manage | Aprovisiona uma conta de emissor Google Wallet e um collector ID Smart Tap opcional utilizando os dados da empresa do seu espaço de trabalho. |
| GET | /api/v1/google-wallet/status | wallet:read / wallet:manage | Devolve { isConfigured, collectorId } indicando se a Google Wallet e o Smart Tap estão aprovisionados. |
| POST | /api/v1/google-wallet/repair-callbacks | wallet:manage, certificates:manage | Resincroniza URLs de webhook /api/v1/wallet/callback em falta nas Classes Google Wallet publicadas. |
| POST | /api/v1/google-wallet/templates/:templateId/activate | wallet:manage, certificates:manage | Ativa o aprovisionamento de classes Google Wallet para um modelo específico. |
| POST | /api/v1/google-wallet/templates/:templateId/deactivate | wallet:manage, certificates:manage | Desativa o suporte Google Wallet para um modelo específico. |
| GET | /api/v1/google-wallet/templates/:templateId/status | wallet:manage, certificates:read | Devolve { isEnabled, issuerId } para o modelo de destino. |
Exemplo: Inicializar a Configuração do Emissor Google Wallet
POST /api/v1/google-wallet/setup
X-API-Key: <API_KEY>
Resposta (201 Created):
{
"issuerId": "3388000000022194812",
"googlePayAccount": {
"accountIdentifier": "3388000000022194812",
"collectorId": "50992104"
},
"smartTapMerchantData": {
"smartTapMerchantId": "50992104"
}
}
A verificação posterior do estado através de GET /api/v1/google-wallet/status devolve { "isConfigured": true, "collectorId": "50992104" }, e os passes individuais expõem googleWalletTypeSource (Google Wallet source type: INITIAL_CREATION | MIGRATION | MANUAL_REGENERATION).
Boas Práticas Durante a Configuração de Modelos
-
1
Escolha a Categoria de Passe Google Correspondente: Em Editar Modelo -> Tipos de Passe, faça corresponder o seu programa a Fidelização (
LoyaltyClass), Oferta (OfferClass), Cartão Presente (GiftCardClass), Bilhete de Evento (EventTicketClass) ou Passe Genérico (GenericClass) — as classes da Google Wallet não podem mudar o tipo de recurso após serem publicadas. -
2
Teste Explicitamente as Pré-visualizações Android: Alterne entre Apple Wallet e Google Wallet no painel de pré-visualização em tempo real, pois as proporções de imagem (banner principal largo
androidBackgroundvs. recorte quadradogooglePayLogo) e as regras de truncagem de campos diferem entre plataformas. -
3
Utilize Substituições Android: Defina etiquetas e valores de campos Android adaptados através do Inspetor quando uma posição do layout Apple não tiver correspondência 1:1 no Android.
Consulte Google Wallet e Google Smart Tap para especificações de classes/objetos e NFC.
