Primer commit

2026-05-30 14:31:19 -06:00
commit a35d26fac0
277 changed files with 265240 additions and 0 deletions
@@ -0,0 +1,2 @@
+- [Bucéfalo / E3 / GHL relationship](brand_bucefalo_e3.md) — Bucéfalo es el white-label del proyecto sobre GoHighLevel; E3 es la marca dueña de Bucéfalo, no aparece en código.
+- [GHL custom fields API quirks](ghl_custom_fields_api.md) — V2 no sirve para contact/opportunity; matriz de mutabilidad PUT; asimetrías read/write key.
@@ -0,0 +1,17 @@
+---
+name: brand-bucefalo-e3
+description: Relación entre Bucéfalo, Consultoría E3 y GoHighLevel en este proyecto. Aclara cómo nombrar las cosas en UI/docs vs código.
+metadata:
+  type: project
+---
+
+Bucéfalo es el **white-label** que el cliente ve. Técnicamente corre sobre GoHighLevel — por eso el código del repo habla con `services.leadconnectorhq.com` y maneja PIT tokens de GHL.
+
+**Consultoría E3** es la **marca dueña/madre de Bucéfalo**, no aparece en el código ni en los scripts del repo. Si la encuentras mencionada como producto en algún lugar del código o de los docs internos del proyecto, es un bug — debe reemplazarse o eliminarse, no es la marca relevante para este sistema.
+
+**Why:** la confusión entre los tres niveles (E3 marca → Bucéfalo producto → GHL infraestructura) es fácil. La regla operativa es:
+- En código y scripts internos: GHL es OK porque es necesidad técnica (URLs, headers, conceptos de API).
+- En UI/docs orientados al cliente: solo Bucéfalo. Nunca GHL ni E3 como producto.
+- Marca propietaria (relaciones contractuales, ownership): E3.
+
+**How to apply:** cuando el usuario menciona "el CRM", "la plataforma" o el producto en cualquier contexto operativo, refiérete a Bucéfalo. Al editar scripts no introduzcas "E3" ni "Bucéfalo" salvo que el contexto lo pida explícitamente — el código habla de GHL por implementación.
@@ -0,0 +1,63 @@
+---
+name: ghl-custom-fields-api
+description: Endpoints reales de GHL para gestionar custom fields de contact/opportunity. V2 no sirve. Matriz de mutabilidad del PUT y asimetrías read/write.
+metadata:
+  type: reference
+---
+
+Validado empíricamente el 2026-05-23 contra la cuenta DEMO (`Vf7qQl3L9vakJ8hDtQ8e`).
+
+## Endpoints relevantes
+
+**Para contact y opportunity custom fields, usar SIEMPRE V1**: `/locations/{locId}/customFields/*` con `Version: 2021-07-28`.
+
+**Custom Fields V2** (`/custom-fields/*`) NO funciona para contact/opportunity — GHL responde explícitamente: *"Fields with model contact is not supported on this route"*. V2 es solo para custom objects definidos por el usuario.
+
+**NO existe endpoint upsert** para contact/opportunity. Hay que hacer GET-or-create del lado del cliente.
+
+## CRUD V1 disponible
+
+- `GET /locations/{locId}/customFields` → lista todos
+- `GET /locations/{locId}/customFields/{cfId}` → uno solo, response `{customField: {...}, traceId}` envuelto
+- `POST /locations/{locId}/customFields` → crea
+- `PUT /locations/{locId}/customFields/{cfId}` → actualiza
+- `DELETE /locations/{locId}/customFields/{cfId}` → borra, response `{succeded: true}` (GHL escribe `succeded` con un solo "e")
+
+## Matriz de mutabilidad del PUT
+
+| Propiedad | Comportamiento |
+|---|---|
+| `name`, `placeholder`, `position`, `description`, `parentId`, `options` | ✅ Acepta y aplica |
+| `fieldKey` | ❌ 422 "property fieldKey should not exist" — inmutable absoluto |
+| `dataType` | ⚠ 200 OK pero **silently ignored** — inmutable de facto. La API miente. |
+| `picklistOptions` | ❌ 422 "property picklistOptions should not exist" — usar `options` en writes |
+
+**Why importante:** el caso `dataType` es trampa real. Si tu repair script asume que 200 = aplicado, te equivocas. Siempre verificar con GET post-PUT cuando hay duda.
+
+## Asimetrías read vs write
+
+| Concepto | Key al leer | Key al escribir |
+|---|---|---|
+| Opciones de SINGLE_OPTIONS | `picklistOptions` | `options` |
+| Valor de CF en contact | `value` | `value` |
+| Valor de CF en opportunity | `fieldValue` | `value` |
+
+## dataTypes válidos
+
+`TEXT, LARGE_TEXT, NUMERICAL, PHONE, MONETORY, CHECKBOX, SINGLE_OPTIONS, MULTIPLE_OPTIONS, FLOAT, TIME, DATE, TEXTBOX_LIST, FILE_UPLOAD, SIGNATURE, RADIO`
+
+Nota la ortografía: `NUMERICAL` (no NUMERIC), `MONETORY` (no MONETARY). GHL las escribe así.
+
+## Implicación para reparación
+
+Lo único auto-reparable con seguridad:
+1. Crear campo faltante (id y fieldKey serán nuevos, no copiados).
+2. Sincronizar opciones (agregar las que faltan).
+3. Renombrar (riesgo medio — puede romper workflows del cliente).
+
+Lo que NO se debe auto-reparar nunca:
+1. Cambiar dataType (imposible vía API; requiere delete + recreate = data loss).
+2. Borrar campos sobrantes (data loss).
+3. Mergear duplicados (decisión manual de cuál preservar).
+
+Ver también [[brand-bucefalo-e3]].