Skip to main content

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.

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. Vea "Identificación y autorización de usuarios para GitHub Apps" para obtener más información.

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 Enterprise Cloud 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 obtener información sobre cómo controlar las cancelaciones antes de que finalice una evaluación gratuita, vea "Gestión de las cancelaciones del plan". Vea "Gestión de los cambios del plan" para averiguar cómo realizar la transición de una evaluación gratuita, cuando esta expire, a un plan de pago.

Vea "Eventos de webhook de GitHub Marketplace" para obtener un ejemplo de la carga del evento marketplace_purchase.

Paso 2. Instalación

Si tu app es una GitHub App, GitHub Enterprise Cloud pedirá al cliente que seleccione a qué repositorios puede acceder dicha app cuando la compren. Entonces, GitHub Enterprise Cloud 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 Enterprise Cloud 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.

Si tu app es una OAuth App. GitHub Enterprise Cloud no la instala en ningún lugar. En su lugar, GitHub Enterprise Cloud 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 Enterprise Cloud 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:

  • Si la aplicación es una GitHub App, inicie el flujo de autorizaciones tan pronto como GitHub Enterprise Cloud redirija al cliente a la URL de configuración. Siga los pasos que se indican en "Identificación y autorización de usuarios para GitHub Apps".

  • Si la aplicación es una OAuth App, inicie el flujo de autorizaciones tan pronto como GitHub Enterprise Cloud redirija al cliente a la URL de instalación. Siga los pasos que se indican en "Autorización de OAuth Apps".

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. Con el token de acceso que ha recibido para el cliente en el Paso 3. Autorización, llame al punto de conexión "Enumeración de suscripciones para el usuario autenticado". 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 administrador 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.