En este documento, se enumeran la terminología y los conceptos comunes que debes conocer para usar la API de la Billetera de Google.
Pases
Aprobada
Un pase es una instancia de un objeto Passes que se emite a un usuario para que lo guarde en su Billetera de Google. La API de la Billetera de Google proporciona compatibilidad con varios tipos de pases comunes, como tarjetas de embarque, entradas para eventos, tarjetas de ID y mucho más. La API de la Billetera de Google también proporciona un tipo de pase genérico que se puede usar para crear pases que no se admiten de forma específica.
En la mayoría de los casos, un pase se crea tanto con una clase Passes como con un objeto Passes.
Entidad emisora de pases
Una entidad emisora de pases es una entidad que crea pases y los emite a los usuarios para que los guarden en su Billetera de Google. La Entidad Emisora del Pase es propietaria de los pases y puede crearlos, emitirlos y actualizarlos. Las Entidades emisoras de pases pueden ser desarrolladores individuales, empresas y organizaciones, así como agregadores que crean y emiten pases en nombre de otras personas, como una empresa que se especializa en la implementación de entradas para eventos o cupones para minoristas.
Clase de pases
Una clase Passes se puede considerar como una plantilla compartida a partir de la cual se crean los pases. Una clase Passes define ciertas propiedades que se incluirán en todos los pases que la usen. Una entidad emisora de pases puede crear varias clases, cada una con su propio conjunto de propiedades que definen atributos, como el estilo y la apariencia, además de funciones adicionales, como el Toque inteligente, la inscripción y el acceso.
En la mayoría de los casos, se crea un pase proporcionando una clase Passes para definir la plantilla del pase y un objeto Passes para definir los detalles del pase individual que se emite.
Pasa objeto
Un Objeto Passes define un pase individual que se emite a un usuario para que lo guarde en su Billetera de Google. Los objetos Passes suelen contener información específica del usuario. Por ejemplo, mientras que una clase Passes podría definir cómo será un pase de tarjeta de regalo para una tienda específica, el Objeto Passes proporcionará detalles específicos, como el saldo o la fecha de vencimiento.
Se debe crear un Objeto Passes por cada pase que se emita, a diferencia de las clases Passes, que se pueden compartir entre muchas instancias de pase.
Pases privados
Algunos pases que creas con la API de la Billetera de Google pueden contener datos sensibles del usuario. Estos pases requieren protección adicional para proteger los datos de tus usuarios y se administran de manera diferente en la API de la Billetera de Google mediante el tipo Pase privado genérico. El pase privado genérico se debe utilizar en casos en los que se incluyan datos sensibles (como se define en la Política de Uso Aceptable de la API de la Billetera de Google) en el pase, y es posible que esté sujeto a controles de privacidad adicionales y revisiones durante la integración.
Toque inteligente
Smart Tap es un protocolo de comunicación de campo cercano propiedad de Google para transmitir datos entre un dispositivo móvil y una terminal de NFC. La tecnología de Toque inteligente les permite a los usuarios canjear pases guardados en su Billetera de Google con el teléfono cerca de cualquier terminal de NFC compatible.
Para usar el protocolo de toque inteligente con tus pases, debes establecer una relación con un proveedor de terminales compatible con el toque inteligente.
APIs y SDK
API de la Billetera de Google
La API de la Billetera de Google es un servicio de Google que te permite crear y emitir pases para que los usuarios los guarden en sus Billeteras de Google. La API se puede usar de varias formas diferentes, incluida la API de REST de la Billetera de Google, el SDK de Android de la Billetera de Google y la consola de la Billetera de Google.
API de REST de la Billetera de Google
La API de REST de la Billetera de Google es una interfaz para crear y administrar pases de manera programática a través del envío de solicitudes HTTP a la API de la Billetera de Google.
Si quieres usar la API de REST de la Billetera de Google, también necesitarás una cuenta de Google Cloud para crear una cuenta de servicio, que se usa para autenticar solicitudes a la API de REST de la Billetera de Google.
SDK de Android de la Billetera de Google
El SDK de la Billetera de Google para Android proporciona un conjunto de métodos útiles para trabajar con la API de la Billetera de Google en tus apps para Android, como crear y emitir pases.
Agregar a la Billetera de Google
Botón “Agregar a la Billetera de Google”
El botón “Agregar a la Billetera de Google” es un recurso aprobado por Google para presentar un pase a un usuario. Cuando un usuario haga clic en el botón o lo presione, se debería activar un vínculo “Agregar a la Billetera de Google” para iniciar el flujo de agregar el pase emitido a la Billetera de Google del usuario.
Se recomienda usar el botón “Agregar a la Billetera de Google” siempre que sea posible, ya que es un elemento de la IU conocido con el que tus usuarios ya saben cómo interactuar.
Los recursos y lineamientos para usar el botón están disponibles en los Lineamientos de marca de la API de la Billetera de Google.
Vínculo “Agregar a la Billetera de Google”
Con el vínculo “Agregar a la Billetera de Google”, puedes emitir un pase a un usuario con un hipervínculo normal. Podrás usarla en cualquier lugar donde puedas incluir hipervínculos, como correos electrónicos, SMS, sitios web y apps para dispositivos móviles.
Los vínculos “Agregar a la Billetera de Google” se crean agregando un JWT firmado a la URL https://pay.google.com/gp/v/save/.
Cuenta de la entidad emisora
Modo de demostración
Cuando crees tu cuenta de entidad emisora, esta estará en “modo de demostración” hasta que se te apruebe para el acceso de publicación. En el modo de demostración, puedes crear pases, pero solo puedes emitirlos a usuarios con los roles de “administrador” o “desarrollador” de tu cuenta de entidad emisora o a usuarios que se hayan agregado como cuentas de prueba en la consola de la Billetera de Google.
Mientras esté en “Modo de demostración”, el título de los pases que emitas comenzará automáticamente con las palabras “[SOLO PARA PRUEBA]” para indicar que este es un pase solo con fines de prueba.
Cuentas de prueba
Cuando la cuenta de la entidad emisora está en “modo de demostración”, si deseas emitir pases a cualquier usuario que no tenga los roles de “administrador” o “desarrollador” para tu cuenta, debes agregarlos como cuentas de prueba en la consola de la Billetera de Google. Los usuarios inscritos como cuentas de prueba podrán agregar los pases emitidos por ti a la Billetera de Google. Esto es útil para probar tus pases con un público más amplio en el “Modo de demostración”.
Perfil de la empresa
Si quieres crear una cuenta de entidad emisora para la API de la Billetera de Google, debes configurar un perfil de negocio cuando te registres en la Consola de Google Pay y la Billetera de Google. Un Perfil de Negocio proporciona a Google información básica sobre tu organización o empresa, y debe aprobarse para obtener el acceso de publicación.
Acceso de publicación
Antes de emitir pases que cualquier usuario pueda guardar en su Billetera de Google, se debe aprobar tu acceso de publicación. Para obtener la aprobación del acceso de publicación, debes haber creado al menos una clase Passes y tener un Perfil de Negocio completo. Las entidades emisoras que quieran emitir pases con el SDK de Android de la Billetera de Google también deben enviar la huella digital SHA-1 para su app.
Para solicitar acceso de publicación, ve a la consola de la Billetera de Google y haz clic en el botón "Solicitar acceso de publicación". El equipo de la Billetera de Google revisará tu solicitud y te notificará una vez que se te haya otorgado acceso de publicación.
Autenticación
Token web JSON (JWT)
Los tokens web JSON son un estándar de la industria de uso general para transferir información de forma segura como un objeto JSON. Cuando usas la API de la Billetera de Google, codificas los detalles del objeto de pases que quieres usar para crear una instancia de pase en formato JWT (que se pronuncia “jot”) y luego envías ese JWT en una solicitud a la API de la Billetera de Google.
Los JWT se mantienen seguros al firmarlos con un secreto compartido antes de enviarlos a la API de la Billetera de Google. Si usas la API de REST de la Billetera de Google, el secreto de firma es la clave de tu cuenta de servicio de Google Cloud. Si usas el SDK de Android de la Billetera de Google, el secreto de firma es la huella digital SHA-1 para tu app para Android.
Cuenta de servicio
Una cuenta de servicio de Google Cloud es un tipo especial de cuenta que suele usar una aplicación o una carga de trabajo de procesamiento, en lugar de una persona. En el caso de la API de la Billetera de Google, usarás una cuenta de servicio para autenticar las solicitudes enviadas a la API de REST de la Billetera de Google.
Las cuentas de servicio se crean en la consola de Google Cloud. Para usar una cuenta de servicio, también deberás habilitar la API de la Billetera de Google en la consola de Cloud para permitir que la cuenta de servicio realice solicitudes a la API de REST de la Billetera de Google.
Clave de cuenta de servicio
Una clave de cuenta de servicio es la credencial que usarás para autenticar llamadas a la API de REST de la Billetera de Google. La clave de la cuenta de servicio se considera altamente sensible y debe ser privada, ya que otorga acceso a muchas de las funciones de la entidad emisora de pases de tu cuenta con la API de REST de la Billetera de Google, incluida la creación de clases de pases y objetos de pases.
Huella digital SHA-1
La huella digital SHA-1 de tu certificado de firma de apps para Android es la credencial que usarás para autenticar llamadas a la API de la Billetera de Google cuando uses el SDK de Android de la Billetera de Google. La huella digital SHA-1 de tu certificado se genera con Gradle o keytool. Si quieres usar la huella digital para autenticar tus solicitudes, debes registrarla en la consola de la Billetera de Google.