Gestionar las compras nuevas y las pruebas gratuitas

Cuando un cliente adquiere un plan de pago, una evaluación gratuita o la versión gratuita de la aplicación GitHub Marketplace, recibirás el webhook del evento marketplace_purchase con la acción purchased, que inicia el flujo de compra.

En este artículo

Nota: Este artículo se aplica solo a las aplicaciones de publicación en GitHub Marketplace. Para más información sobre la publicación de GitHub Actions en GitHub Marketplace, consulta "Publicar acciones en GitHub Marketplace".

Si ofreces una GitHub App en GitHub Marketplace, esta debe identificar a los usuarios siguiendo el flujo de autorizaciones de OAuth. No necesitas configurar una OAuth app por separado para admitir este flujo. Para obtener más información, consulta "Autenticación con una aplicación de GitHub en nombre de un usuario".

Paso 1. Compra inicial y evento de webhook

Antes de que un cliente compre la aplicación de GitHub Marketplace, selecciona un plan de listado. También eligen si quieren comprar la app desde su cuenta personal o su cuenta de organización.

El cliente completa la compra haciendo clic en Complete order and begin installation (Completar pedido y empezar la instalación).

GitHub luego envía el webhook marketplace_purchase con la acción purchased a la aplicación.

Lea el objeto effective_date y marketplace_purchase del webhook marketplace_purchase para determinar qué plan compró el cliente, cuándo se inicia el ciclo de facturación y cuándo comienza el siguiente ciclo de facturación.

Si la aplicación ofrece una evaluación gratuita, lea el atributo marketplace_purchase[on_free_trial] del webhook. Si el valor es true, la aplicación tendrá que realizar un seguimiento de la fecha de inicio de la evaluación gratuita (effective_date) y de la fecha en que esta finaliza (free_trial_ends_on). Use la fecha free_trial_ends_on para mostrar los días que quedan para que finalice una evaluación gratuita en la interfaz de usuario de la aplicación. Esto puede hacerlo en un banner o en la interfaz de usuario de facturación. Para aprender a controlar las cancelaciones antes de que finalice una evaluación gratuita, consulta "Gestionar las cancelaciones de plan". Consulta "Gestionar cambios de plan" para averiguar cómo realizar la transición de una evaluación gratuita, cuando esta expire, a un plan de pago.

Consulta "Eventos de webhook para la API de GitHub Marketplace" para ver un ejemplo de la carga del evento marketplace_purchase.

Paso 2. Instalación

Si tu app es una GitHub App, GitHub pedirá al cliente que seleccione a qué repositorios puede acceder dicha app cuando la compren. Entonces, GitHub instala la app en la cuenta del cliente seleccionado y le otorga acceso a los repositorios seleccionados.

En este momento, si ha especificado una URL de configuración en la configuración de la GitHub App, GitHub redirigirá al cliente a esta URL. Si no especificaste una URL de configuración, no podrás manejar las compras de tu GitHub App.

Nota: La dirección URL de la instalación se describe como opcional en la configuración de GitHub App, pero es un campo obligatorio si quiere ofrecer la aplicación en GitHub Marketplace. Para obtener más información, vea «Acerca de la URL de configuración».

Si tu app es una OAuth app. GitHub no la instala en ningún lugar. En su lugar, GitHub redirige al cliente a la dirección URL de la instalación que ha especificado en el listado de GitHub Marketplace.

Cuando un cliente compra una OAuth app, GitHub redirige al cliente a la URL que elige (ya sea de configuración o de instalación) y esta incluye el plan de precios que eligió el cliente como un parámetro de consulta: marketplace_listing_plan_id.

Paso 3. Authorization

Cuando un cliente compra tu app, debes enviar a dicho cliente a través del flujo de autorización de OAuth:

Para cualquier tipo de aplicación, el primer paso consiste en redirigir al cliente a https://github.com/login/oauth/authorize.

Después de que el ciente complete la autorización, tu app recibirá un token de acceso de OAuth para el cliente. Necesitas este token para el siguiente paso.

Nota: Cuando autorice a un cliente para una evaluación gratuita, concédale el mismo acceso que tendría en el plan de pago. Los migrarás al plan pagado después de que termine el periodo de pruebas.

Paso 4. Aprovisionar las cuentas de los clientes

Tu app debe aprovisionar una cuenta de cliente para cada compra nueva. Mediante el token de acceso que recibiste para el cliente en el Paso 3. Autorización, llama al punto de conexión "GET /user/marketplace_purchases". La respuesta incluirá la información account del cliente y mostrará si están en una evaluación gratuita (on_free_trial). Utiliza esta información para completar el aprovisionamiento y la configuración.

Nota: En la versión actual de GitHub Marketplace, es posible que un cliente compre la aplicación desde GitHub Marketplace cuando ya tiene una cuenta existente comprada desde el sitio web de la aplicación. Si comprueba que ya ha configurado una cuenta para el cliente que ha comprado la aplicación, por favor, notifique estas compras "duplicadas" al Soporte técnico de GitHub.

Si la compra es para una organización y es por usuario, puedes solicitar al cliente que escoja qué miembros de la organización tendrán acceso a la app que se compró.

Puedes personalizar la forma en la que los miembros de la organización reciben acceso a tu app. Estas son algunas sugerencias:

Precios de tarifa plana: si la compra se realiza para una organización mediante precios de tarifa plana, la aplicación puede obtener todos los miembros de la organización mediante la API y solicitar al propietario de la organización que elija qué miembros tendrán usuarios de pago en el lado del integrador.

Precios por unidad: un método para aprovisionar puestos por unidad es permitir a los usuarios que ocupen un puesto a medida que inicien sesión en la aplicación. Una vez que el cliente llegue al umbral de conteo de plazas, tu app puede notificarle que necesita mejorar el plan a través de GitHub Marketplace.