La superficie programable

La v1 llegó a su fin de soporte el 31 de diciembre de 2025: lo existente sigue funcionando, pero no hay soporte ni actualizaciones, y se está quitando la generación de API keys nuevas. Cualquier tutorial que empiece por "copiá tu API key" es contenido muerto.

Quedan dos mecanismos: Private Integration Tokens para lo interno o de una sola sub-cuenta, y OAuth 2.0 para apps públicas y del marketplace.

El host es https://services.leadconnectorhq.com. Cada request lleva Authorization: Bearer <token> y —esto es lo que más falla en la primera llamada— un header Version con valor de fecha: 2021-07-28. No es opcional.

Un PIT se crea en Settings → Private Integrations eligiendo scopes, y se muestra una sola vez. Son "access tokens de OAuth2 estáticos": no se auto-renuevan, a diferencia de los de OAuth, que expiran a diario. Los refresh tokens rotan al usarse: cada renovación devuelve uno nuevo que hay que guardar.

Los scopes usan notación de punto (contacts.readonly, contacts.write), tienen un nivel y gobiernan también qué eventos de webhook podés recibir. La guía oficial es pedir el mínimo.

Límites y webhooks

Hay un límite de ráfaga y un tope diario, contados por app y por recurso (una Location o una Company): dos instalaciones tienen presupuestos separados. La respuesta trae headers como X-RateLimit-Daily-Remaining.

Los webhooks llegan con type, timestamp, webhookId y data, con nombre de evento en PascalCase: ContactCreate, InboundMessage. Se firman con X-GHL-Signature (Ed25519), y cada reintento repite el mismo deliveryId: tu handler tiene que ser idempotente.