Billing
Esta guia aplica solo si su institucion esta desarrollando una app de pago para el Marketplace de HighLevel (poco comun para un colegio o universidad que solo usa HighLevel internamente). Si su caso es simplemente conectar sus propios sistemas, probablemente no necesiten esta página — les recomendamos revisar Integraciones Privadas en su lugar.
Webhook de facturacion (Billing)
Este webhook es esencial para las apps con facturacion externa dentro de nuestro marketplace. Los desarrolladores deben implementarlo para autorizar la instalación de la app.
Su proposito principal es capturar y actualizar la información de pago de las apps que usan un modelo de negocio de pago (Paid) y no utilizan el mecanismo de facturacion interno de HighLevel.
1. Requisitos previos para usar este webhook
Antes de usar este webhook, asegurate de cumplir lo siguiente en el Marketplace:
- Tu app debe tener un modelo de negocio marcado como Paid.
- La facturacion externa (External Billing) debe estar habilitada para tu app.
- Debes haber ingresado la Billing URL.
2. Obtencion de parametros desde la Billing URL
Cuando una Agencia o Ubicacion instala tu app, seran redirigidos a la Billing URL especificada en la configuración. Recibiras los siguientes parametros en la URL:
| Parametro | Valores posibles | Notas |
|---|---|---|
| clientId | <client_id> |
Se usa para validacion. |
| installType | location, agency |
Recibiras agency,location en caso de agencia y ubicacion a la vez. |
| locationId | <location_id> |
Lo recibiras en caso de location o agency,location. |
| companyId | <agency_id> |
Lo recibiras en caso de agency o agency,location. |
3. Uso del webhook
Después de procesar exitosamente el pago de tu lado, debes hacer una peticion a nuestro endpoint de webhook de facturacion:
https://services.leadconnectorhq.com/oauth/billing/webhook
Los parametros que debes incluir en la peticion del webhook son los siguientes:
Metodo de la peticion: POST
Headers de la peticion:
| Nombre | Valor | Notas |
|---|---|---|
| x-ghl-client-key | Tu client key | Debe ser del mismo cliente para el cual estas autorizando el pago. |
| x-ghl-client-secret | Tu Client Secret | El client secret correspondiente a la client key usada. |
| Content-Type | application/json |
Cuerpo de la peticion:
| Nombre | Valor | Notas |
|---|---|---|
| clientId | Tu client Id | |
| authType | Enum | Valores posibles: company y location. |
| locationId | <location_id> |
Requerido cuando authType es location. |
| companyId | <company_id> |
Requerido cuando authType es company. |
| subscriptionId | Tu subscription Id | Inclúyelo si configuraste un modelo de suscripción. |
| paymentId | Tu Payment Id | En caso de un modelo de pago único, puedes enviar este parametro. |
| amount | Monto facturado | Requerido. |
| status | Enum | Valores posibles: COMPLETED y FAILED. |
| paymentType | Enum | Valores posibles: one_time y recurring. |
Ejemplo
Aquí hay un ejemplo de comando cURL para la peticion del webhook:
curl --location 'https://services.leadconnectorhq.com/oauth/billing/webhook' \
--header 'x-ghl-client-key: <client_key>' \
--header 'x-ghl-client-secret: <client_secret>' \
--header 'Content-Type: application/json' \
--data '{
"clientId": "<client_id>",
"authType": "location",
"locationId": "<location_id>",
"subscriptionId": "<subscription_id>",
"paymentId": "<payment_id>",
"amount": 12,
"status": "COMPLETED",
"paymentType": "recurring"
}'
Preguntas frecuentes del webhook
¿Puedo recibir varios locationId en la Billing URL?
Si, en caso de instalaciones multiples, recibiras una lista de locationIds separados por coma en la billing URL.
¿Puedo actualizar varias ubicaciones en una sola llamada?
No, debes disparar el webhook para cada ubicacion y compania por separado.