docs: update readme with api optimization and getAllRows lessons learned [31188f42]

connector-superoffice/README.md

@@ -185,6 +185,21 @@ Die Simulation von E-Mails via Terminen (Appointments) erforderte Workarounds f
 3.  **Rollen-Dynamik:**
     *   Um zu verhindern, dass alte Rollen (z.B. "Infrastruktur") nach einer Beförderung/Änderung in SuperOffice "kleben" bleiben, führt das System nun bei jeder Namens- oder Funktionsänderung einen **Rollen-Reset** durch.
 
+---
+
+### 10. Lessons Learned: API Optimization & Certification (Feb 24, 2026)
+
+Um die Zertifizierung für den SuperOffice App Store zu erhalten, mussten kritische Performance-Optimierungen durchgeführt werden.
+
+1.  **Die `getAllRows`-Falle:**
+    *   **Problem:** SuperOffice monierte in der Validierung API-Calls wie `getAllRows` (implizit oft durch Abfragen ganzer Objekte ohne Filter), die unnötige Last verursachen.
+    *   **Lösung:** Implementierung von **OData `$select`**. Wir fordern nun strikt nur die Felder an, die wir wirklich benötigen (z.B. `get_person(id, select=['JobTitle', 'UserDefinedFields'])`).
+    *   **Wichtig:** Niemals pauschal `get_person()` aufrufen, wenn nur die Rolle geprüft werden soll.
+
+2.  **NullReference bei `$select`:**
+    *   **Problem:** Wenn `$select` genutzt wird, gibt SuperOffice nicht angeforderte komplexe Objekte (wie `Contact` in `Person`) als `null` zurück. Der Zugriff `person['Contact']['ContactId']` führt dann zum Crash.
+    *   **Lösung:** Robuste Checks (`if contact_obj and isinstance(contact_obj, dict)`) und primäre Nutzung der IDs direkt aus dem Webhook-Payload (`FieldValues`), um API-Calls komplett zu vermeiden.
+
 ## Appendix: The "First Sentence" Prompt
 This is the core logic used to generate the company-specific opener.