318 lines
13 KiB
Markdown
318 lines
13 KiB
Markdown
# DOCUMENTACIÓN de Monte Providencia
|
||
|
||
: URIEL JARETH ALVARADO ORTIZ
|
||
Area: CRMS
|
||
Cliente: Monte Providencia
|
||
Equipo: URIEL JARETH ALVARADO ORTIZ
|
||
Prioridad: Muy Alta
|
||
Responsable: URIEL JARETH ALVARADO ORTIZ
|
||
Revisión: No
|
||
Status: Mensual
|
||
Última edición: 20 de mayo de 2026 22:30
|
||
Última edición por: URIEL JARETH ALVARADO ORTIZ
|
||
|
||
## Descripción breve de Monte Providencia
|
||
|
||
Monte Providencia es una empresa enfocada en empeño de autos con N sucursales en México. Algunas sucursales son FULL AUTOS (enfocados 100% en empeño de autos), algunas otras sucursales trabajan parcialmente con el empeño de autos.
|
||
|
||
## Contexto en Bucéfalo CRM (Go High Level)
|
||
|
||
La cuenta de marca “Monte Providencia” (locationid=GbKkBpCmKu2QmloKFHy3) manda los datos de contactos creados con sus sucursales con nomenclatura de nombre de cuenta #### - MP - TIENDA, donde #### es el codigo de tienda y TIENDA=Nombre de tienda. Los contactos en la cuenta principal se crean por formulario, redes sociales o integraciones por API por desarrollos especificos. Cada sucursal es un location en GHL.
|
||
|
||
Los contactos se sincronizan con los contactos de sucursales. Si un contacto se crea/modifica en sucursal se crea/modifica en cuenta de marca. Si un contacto se crea/modifica en marca se crea/modifica en sucursal. En el caso de oportunidades es la sucursal que tiene la prioridad, si una oportunidad se actualiza en sucursal se actualiza en cuenta de marca pero no a la inversa.
|
||
|
||
Un contacto puede tener más de una oportunida (posibilidad de empeño) por contacto.
|
||
|
||
## Datos relevantes de contacto y oportunidad
|
||
|
||
Los datos de contacto y sucursal son los minimos aceptados.
|
||
|
||
### Datos de contacto
|
||
|
||
- Nombre
|
||
- Apellido
|
||
- Teléfono
|
||
- Correo Electrónico
|
||
|
||
### Datos de vehículo
|
||
|
||
- SUCURSAL
|
||
- MARCA DE VEHÍCULO
|
||
- VERSIÓN DEL VEHÍCULO
|
||
- AÑO DE VEHÍCULO
|
||
- MODALIDAD DE EMPEÑO
|
||
- Sin Dejarlo (GPS)
|
||
- Tradicional (Resguardo)
|
||
|
||
### Acepetación de terminos (obigatorio para formulario web)
|
||
|
||
- **Acepta los términos para tu cotización ***
|
||
- Política de Privacidad para comunicación de marketing
|
||
|
||
### Pipeline y etapas
|
||
|
||
- Etapas
|
||
- PROSPECTO NUEVO
|
||
- Intento de contacto
|
||
- Contactado
|
||
- Cliente Interesado
|
||
- Cumple requisitos
|
||
- Solicitud Iniciada
|
||
- Préstamo aprobado
|
||
- En Pausa
|
||
|
||
### Campos personalizados relevantes (contacto y oportunidad)
|
||
|
||
- CANAL DE ORIGEN: Formulario, Llamada, WhatsApp, Facebook, Instagram, Sucursal.
|
||
- **Fuente de Prospecto: CLIENTE CONOCIDO, SUCURSAL, PROSPECCIÓN, REFERIDO, ALIANZA, EVENTO ESPECIAL, LEAD DIGITAL**
|
||
|
||
IMPORTANTE: LEAD DIGITAL siempre proviene de algun medio digital. El canal de origen de sucursal podría tener cualquier fuente de prospecto menos LEAD DIGITAL.
|
||
|
||
## Colección de campos personalizados (RELEVANTE PARA API)
|
||
|
||
### Paginación técnica obligatoria para escaneos completos en GHL
|
||
|
||
Cuando un script necesite auditar, buscar, sincronizar o corregir contactos u oportunidades en GHL, no debe asumir que una sola respuesta de API contiene todos los registros. Para evitar que queden datos fuera del escaneo, cada script debe implementar paginación completa, acumulación de resultados y deduplicación por `id`.
|
||
|
||
#### Contactos
|
||
|
||
Los contactos deben obtenerse usando la paginación cursor-based de GHL.
|
||
|
||
- Endpoint habitual: `GET https://services.leadconnectorhq.com/contacts/`
|
||
- Parámetros mínimos: `locationId={locationId}` y `limit`.
|
||
- Cursor/paginación: usar `meta.nextPageUrl`, `startAfter` y, cuando aplique, `startAfterId`.
|
||
- Regla: no usar paginación por offset para contactos.
|
||
- El script debe seguir solicitando páginas hasta que no exista `meta.nextPageUrl` ni cursor siguiente, o hasta alcanzar un límite explícito definido por el usuario (`--limit`, `--max-contacts`, etc.).
|
||
|
||
Flujo recomendado:
|
||
|
||
1. Inicializar `contacts = []`, `seen_ids = set()` y cursores vacíos.
|
||
2. Solicitar la primera página con `locationId` y `limit`.
|
||
3. Agregar cada contacto solo si su `id` no existe en `seen_ids`.
|
||
4. Leer `meta.nextPageUrl` y/o cursores `startAfter` / `startAfterId` para la siguiente página.
|
||
5. Detenerse cuando no haya siguiente cursor/URL, cuando una página venga vacía sin nuevo cursor, o cuando se alcance un límite explícito.
|
||
6. Reportar páginas consultadas, contactos recibidos, contactos únicos y duplicados descartados.
|
||
|
||
#### Oportunidades
|
||
|
||
Las oportunidades deben obtenerse con búsqueda por API, no con el endpoint simple de listado.
|
||
|
||
- Endpoint obligatorio: `POST https://services.leadconnectorhq.com/opportunities/search`
|
||
- Parámetro/filtro requerido: `locationId={locationId}`.
|
||
- Regla: no usar `GET /opportunities/` para escaneos completos porque puede devolver vacío o cero resultados aunque existan oportunidades.
|
||
- Si el resultado de búsqueda devuelve paginación/cursor o parámetros de página soportados por la API, el script debe iterar hasta agotar resultados o llegar a un límite explícito.
|
||
|
||
Flujo recomendado:
|
||
|
||
1. Inicializar `opportunities = []`, `seen_ids = set()` y estado de paginación vacío.
|
||
2. Ejecutar `POST /opportunities/search` con `locationId` y el tamaño de página permitido.
|
||
3. Agregar cada oportunidad solo si su `id` no existe en `seen_ids`.
|
||
4. Avanzar a la siguiente página usando el cursor/parámetro devuelto por la API, si existe.
|
||
5. Detenerse cuando no haya más resultados, cuando no haya cursor siguiente, cuando se repita un cursor ya visto o cuando se alcance un límite explícito.
|
||
6. Reportar páginas consultadas, oportunidades recibidas, oportunidades únicas y duplicados descartados.
|
||
|
||
#### Reglas de seguridad para cualquier paginador
|
||
|
||
- Deduplicar siempre por `id` antes de auditar, comparar, sincronizar o actualizar.
|
||
- Mantener un registro de cursores o URLs ya vistos para evitar loops infinitos.
|
||
- Implementar límites explícitos cuando el script sea de investigación (`--limit`, `--max-contacts`, `--max-opportunities`) y dejar claro en el resumen si el corte fue por límite.
|
||
- Respetar el rate limit por token antes de cada request.
|
||
- En ejecuciones paralelas, no aumentar workers sin considerar el rate limit de GHL.
|
||
- Si una página falla, registrar el error con contexto (`locationId`, endpoint, página/cursor) y reportarlo en el resumen final.
|
||
- En auditorías profundas, primero consolidar el dataset completo requerido y después ejecutar comparaciones, conteos o correcciones.
|
||
|
||
#### Resumen final esperado en scripts con paginación
|
||
|
||
Todo script que haga escaneos paginados debe reportar al final:
|
||
|
||
- Locations procesadas.
|
||
- Páginas consultadas.
|
||
- Registros recibidos desde GHL.
|
||
- Registros únicos procesados.
|
||
- Duplicados descartados.
|
||
- Registros omitidos por límite, si aplica.
|
||
- Errores por location o endpoint, si existieron.
|
||
|
||
### Mapeo técnico obligatorio de campos personalizados en GHL
|
||
|
||
Los IDs de campos personalizados de GHL pueden cambiar entre la cuenta de marca y cada sucursal. Por esta razón, todos los scripts que lean, comparen, sincronicen o actualicen campos personalizados de contactos u oportunidades deben resolver los IDs dinámicamente por `locationId` y por nombre de campo antes de operar datos.
|
||
|
||
Flujo obligatorio por cada location:
|
||
|
||
1. Consultar catálogo de objetos de la ubicación:
|
||
- Documentación: `https://marketplace.gohighlevel.com/docs/ghl/objects/get-object-by-location-id`
|
||
- Endpoint API: `GET https://services.leadconnectorhq.com/objects/?locationId={locationId}`
|
||
- Header requerido: `Version: 2021-04-15`
|
||
- Objetivo: inicializar/autorizar la consulta de metadatos de objetos para esa ubicación.
|
||
2. Consultar esquema del objeto requerido:
|
||
- Documentación: `https://marketplace.gohighlevel.com/docs/ghl/objects/get-object-schema-by-key`
|
||
- Endpoint API: `GET https://services.leadconnectorhq.com/objects/{objectKey}?locationId={locationId}`
|
||
- Header requerido: `Version: 2021-04-15`
|
||
- `objectKey`: usar `contact` para campos de contacto y `opportunity` para campos de oportunidad.
|
||
- Objetivo: obtener campos estándar y personalizados para mapear nombres funcionales como `Canal de Origen`, `Fuente de Prospecto`, `Sucursal`, `TIENDA`, `Vehículo`, `Marca del Vehículo`, `Versión del Vehículo` y `Año del Vehículo` a su ID real en esa sucursal.
|
||
|
||
Reglas técnicas:
|
||
|
||
- Ningún script debe hardcodear IDs de campos personalizados para contactos u oportunidades entre sucursales.
|
||
- El mapeo debe hacerse por nombre de campo y por `locationId`; un ID válido en una sucursal no debe asumirse válido en otra.
|
||
- Si un campo requerido no existe en el esquema de una ubicación, el script debe reportarlo claramente y evitar actualizaciones parciales inseguras.
|
||
- Esta regla aplica tanto para scripts de auditoría/lectura como para scripts mutadores (`fix_*`, `migrate_*`, `move_*`, `update_*`, `sync_contact_*`).
|
||
|
||
### Contactos
|
||
|
||
- Sucursal: En formulario normalmente se llena en automatico, cuando se crea en sucursal se hace una relación con el verificador de sucursal con el campo de TIENDA o con el nombre de la cuenta en GHL de ahi se hace la relación ya que el verificador de sucural ya tiene mapeado los campos, si no hay campo se deja vacio.
|
||
- Versión del vehículo
|
||
- Marca del Vehículo
|
||
- Año del Vehículo
|
||
- ¿Qué modalidad prefieres?
|
||
- Acepta los terminos para tu cotización
|
||
- ¿Cuándo necesitas el dinero?
|
||
- Check Comunicaciones de Marketing
|
||
- Canal de Origen
|
||
- FORMULARIO
|
||
- FACEBOOK
|
||
- WHATSAPP
|
||
- LLAMADA
|
||
- INSTAGRAM
|
||
- SUCURSAL
|
||
- Fuente de Prospecto
|
||
- CLIENTE CONOCIDO
|
||
- SUCURSAL
|
||
- PROSPECCIÓN
|
||
- REFERIDO
|
||
- ALIANZA
|
||
- EVENTO ESPECIAL
|
||
- LEAD DIGITAL
|
||
- REDES SOCIALES
|
||
- GALLARDETES
|
||
- TIENDA
|
||
- ALTAMIRA
|
||
- ATIZAPAN
|
||
- ATLACOMULCO
|
||
- CANCUN
|
||
- CD CARMEN
|
||
- CHILPANCINGO
|
||
- CUAJIMALPA
|
||
- CUAUTLA
|
||
- IZCALLI
|
||
- ECATEPEC
|
||
- EUGENIA
|
||
- GRAND PLAZA
|
||
- HUAUCHINANGO
|
||
- INDEPENDENCIA
|
||
- INTERLOMAS
|
||
- ISIDRO FABELA
|
||
- IXMIQUILPAN
|
||
- ZACATEPEC
|
||
- JOJUTLA
|
||
- LA VIGA
|
||
- MARINA NACIONAL
|
||
- METEPEC
|
||
- MIACATLAN
|
||
- MIAHUATLAN
|
||
- MORELIA 1
|
||
- MORELIA 3
|
||
- PILARES
|
||
- PINOTEPA
|
||
- PLAZA EL SALADO
|
||
- POCHUTLA
|
||
- PUEBLA
|
||
- QUERETARO
|
||
- REYNOSA
|
||
- SATELITE
|
||
- ZINACANTEPEC
|
||
- ZITACUARO
|
||
- TAMPICO
|
||
- TAPACHULA
|
||
- TEMIXCO
|
||
- TEXCOCO
|
||
- TULYEHUALCO
|
||
- TUXTLA 3
|
||
- URUAPAN
|
||
- VILLAS DEL SOL
|
||
- SENDERO
|
||
|
||
### Oportunidades
|
||
|
||
- CANAL DE ORIGEN
|
||
- Sucursal
|
||
- Persona que atendió al prospecto: Campo libre donde el asesor escribe su nombre ya que un solo usuario maneja el CRM pero varias personas usan el mismo usuario.
|
||
- Visita a sucursal: check para indicar si el prospecto visitó la sucursal.
|
||
- **Fecha de última visita a sucursal: fecha de calendario que indica la ultima visita del usuario.**
|
||
- **Fuente de Prospecto**
|
||
- CLIENTE CONOCIDO
|
||
- SUCURSAL
|
||
- PROSPECCIÓN
|
||
- REFERIDO
|
||
- ALIANZA
|
||
- EVENTO ESPECIAL
|
||
- LEAD DIGITAL
|
||
- REDES SOCIALES
|
||
- GALLARDETES
|
||
- Vehículo
|
||
- **Modalidad de Empeño**
|
||
- TIENDA
|
||
- ALTAMIRA
|
||
- ATIZAPAN
|
||
- ATLACOMULCO
|
||
- CANCUN
|
||
- CD CARMEN
|
||
- CHILPANCINGO
|
||
- CUAJIMALPA
|
||
- CUAUTLA
|
||
- IZCALLI
|
||
- ECATEPEC
|
||
- EUGENIA
|
||
- GRAND PLAZA
|
||
- HUAUCHINANGO
|
||
- INDEPENDENCIA
|
||
- INTERLOMAS
|
||
- ISIDRO FABELA
|
||
- IXMIQUILPAN
|
||
- ZACATEPEC
|
||
- JOJUTLA
|
||
- LA VIGA
|
||
- MARINA NACIONAL
|
||
- METEPEC
|
||
- MIACATLAN
|
||
- MIAHUATLAN
|
||
- MORELIA 1
|
||
- MORELIA 3
|
||
- PILARES
|
||
- PINOTEPA
|
||
- PLAZA EL SALADO
|
||
- POCHUTLA
|
||
- PUEBLA
|
||
- QUERETARO
|
||
- REYNOSA
|
||
- SATELITE
|
||
- ZINACANTEPEC
|
||
- ZITACUARO
|
||
- TAMPICO
|
||
- TAPACHULA
|
||
- TEMIXCO
|
||
- TEXCOCO
|
||
- TULYEHUALCO
|
||
- TUXTLA 3
|
||
- URUAPAN
|
||
- VILLAS DEL SOL
|
||
- SENDERO
|
||
|
||
## CORRELACIÓN ENTRE CONTACTOS Y OPORTUNIDADES (campos personalizados)
|
||
|
||
Los campos de sucursal (y tienda proximamente) siempre tienen que estar sincronizados y ser iguales con valores validos del “verificador de sucursales”.
|
||
|
||
Si un contacto tiene la etiqueta “sucursal” siempre será creado de manera manual siempre y cuando el contacto no aclare en el campo “source” (de API) algo que sea lo contrario (facebook, instagram, etc).
|
||
|
||
Los datos de vehiculo en contacto y oportunidad no tienen que ser siempre los mismos ya que en la oportunidad es la suma de los campos de contacto “Marca del vehiculo”, “Versión del Vehiculo” “año del vehiculó” pero solo cuando es lead digital. Si se crea una oportunidad de manera manual ya puede ser diferente el campo personalizado de vehículo en oportunidad.
|
||
|
||
## DATOS QUE SIEMPRE HAY QUE TENER PARA BUSINESS INTELLIGENCE
|
||
|
||
- Sucursal
|
||
- Canal de origen
|
||
- Fuente del Prospecto
|
||
|
||
### Consideración extra de oportunidades.
|
||
|
||
Todas las oportunidades deben de estar en un pipeline valido. Generalmente llamado “Standar”, en caso de ser necesario reubicar se debe de hacer con base al nombre de la etapa/stage. En caso de que sea oportunidad huerfana (no ubicado en pipeline valido) se debe de reubicar o marcar para su revisión.
|