# Leadharvester-Integration mit QC Text Builder Dieses Dokument beschreibt den minimalen, aber vollstaendigen Integrations-Workflow zwischen **Leadharvester** und **QC Text Builder**. Ziel: - Leadharvester holt zuerst die verfuegbaren Templates aus QC Text Builder. - Leadharvester zeigt Template-Name, Thumbnail und Vollansicht/Preview an. - Danach waehlt der User oder Upstream-Prozess ein Template. - Anschliessend uebergibt Leadharvester die gesammelten Stammdaten und Kontextdaten per Intake an QC Text Builder. - QC Text Builder erzeugt oder aktualisiert daraus einen Draft. --- ## 1) Basisdaten - QC Text Builder Base URL lokal: `http://localhost:8080` - Template-Liste: `GET /api/templates` - Template-Detail: `GET /api/templates/{id}` - Draft-Intake: `POST /api/drafts/intake` --- ## 2) Gesamt-Workflow ### Schritt 1: Templates aus QC Text Builder abrufen Leadharvester ruft zuerst die verfuegbaren Templates ab: **Request** ```http GET /api/templates ``` **Beispiel lokal** ```text http://localhost:8080/api/templates ``` **Response-Struktur** ```json { "count": 1, "templates": [ { "id": 1408367, "name": "Mono QC 1- DE", "description": "", "locale": "DE", "thumbnailUrl": "https://rai.monosolutions.com//thumbnails/01408367/1408367.jpeg", "templatePreviewUrl": "https://u1408367.tool-apdialog.at", "type": "ai", "paletteReady": true, "rawTemplateJson": {}, "isAiTemplate": true, "isOnboarded": true, "manifestStatus": "reviewed", "lastDiscoveredAt": "2026-03-27T10:00:00Z" } ] } ``` ### Felder, die Leadharvester mindestens verwenden sollte - `id` - `name` - `thumbnailUrl` - `templatePreviewUrl` ### Bedeutung - `thumbnailUrl`: kleine Vorschau fuer Template-Karten - `templatePreviewUrl`: Vollansicht / Live-Preview des Templates - `id`: wird spaeter als `templateId` an den Draft-Intake uebergeben --- ## 3) Templates in Leadharvester anzeigen Leadharvester sollte die Template-Auswahl mindestens so darstellen: ```json { "templateId": 1408367, "label": "Mono QC 1- DE", "thumbnail": "https://rai.monosolutions.com//thumbnails/01408367/1408367.jpeg", "previewUrl": "https://u1408367.tool-apdialog.at" } ``` Nach der Auswahl muss Leadharvester mindestens diese Werte intern weitertragen: ```json { "selectedTemplateId": 1408367, "selectedTemplateName": "Mono QC 1- DE" } ``` --- ## 4) Stammdaten und Kontext in Leadharvester sammeln Leadharvester sammelt anschliessend die Nutzdaten fuer den Draft. ### Empfohlene Stammdaten (`globalData`) ```json { "companyName": "Dönerbude", "username": "jansvabenik", "email": "jan.svabenik@apdialog.com", "phone": "+41 79 123 45 67", "businessType": "Imbiss", "descriptionShort": "Frische Döner und schnelle Mittagsgerichte.", "descriptionLong": "Dönerbude bietet frisch zubereitete Spezialitäten, schnelle Bedienung und unkomplizierten Genuss für den Alltag.", "mission": "Frisches, gutes Essen schnell und unkompliziert anbieten.", "addressLine1": "Bahnhofstrasse 12", "addressCity": "Zürich", "addressZIP": "8001", "addressCountry": "Schweiz" } ``` ### Empfohlener Kontext fuer Textvorschlaege ```json { "websiteUrl": "https://example.com", "websiteSummary": "Frische Döner und schnelle Mittagsgerichte für Kundschaft in der Schweiz.", "businessType": "Imbiss", "localeStyle": "de-CH", "marketStyle": "Schweiz", "addressMode": "du", "contentTone": "locker", "promptInstructions": "Kurz, appetitlich und glaubwürdig formulieren." } ``` --- ## 5) Rueckuebergabe von Leadharvester an QC Text Builder Wenn Template + Stammdaten + Kontext feststehen, gibt Leadharvester die Daten per Intake zurueck an QC Text Builder. ### Endpoint ```http POST /api/drafts/intake Content-Type: application/json ``` ### Exakter Intake-Contract ```json { "draftId": "string, optional", "source": "string, required", "requestName": "string, required", "templateId": 0, "globalData": {}, "notes": "string, optional", "websiteUrl": "string, optional", "websiteSummary": "string, optional", "businessType": "string, optional", "localeStyle": "string, optional", "marketStyle": "string, optional", "addressMode": "string, optional", "contentTone": "string, optional", "promptInstructions": "string, optional", "styleProfile": { "localeStyle": "string, optional", "marketStyle": "string, optional", "addressMode": "string, optional", "contentTone": "string, optional", "promptInstructions": "string, optional" } } ``` ### Empfohlenes Request-Beispiel ```json { "source": "leadharvester", "requestName": "Dönerbude Intake 2026-03-27", "templateId": 1408367, "globalData": { "companyName": "Dönerbude", "username": "jansvabenik", "email": "jan.svabenik@apdialog.com", "phone": "+41 79 123 45 67", "businessType": "Imbiss", "descriptionShort": "Frische Döner und schnelle Mittagsgerichte.", "descriptionLong": "Dönerbude bietet frisch zubereitete Spezialitäten, schnelle Bedienung und unkomplizierten Genuss für den Alltag.", "mission": "Frisches, gutes Essen schnell und unkompliziert anbieten.", "addressLine1": "Bahnhofstrasse 12", "addressCity": "Zürich", "addressZIP": "8001", "addressCountry": "Schweiz" }, "notes": "Import aus Leadharvester", "websiteUrl": "https://example.com", "websiteSummary": "Frische Döner und schnelle Mittagsgerichte für Kundschaft in der Schweiz.", "businessType": "Imbiss", "localeStyle": "de-CH", "marketStyle": "Schweiz", "addressMode": "du", "contentTone": "locker", "promptInstructions": "Kurz, appetitlich und glaubwürdig formulieren.", "styleProfile": { "localeStyle": "de-CH", "marketStyle": "Schweiz", "addressMode": "du", "contentTone": "locker", "promptInstructions": "Kurz, appetitlich und glaubwürdig formulieren." } } ``` --- ## 6) Backend-Verhalten beim Intake QC Text Builder macht beim Intake aktuell Folgendes: - Wenn `draftId` fehlt oder leer ist, wird ein **neuer Draft** erzeugt. - Wenn `draftId` gesetzt ist, wird ein bestehender Draft **aktualisiert**. - Der Draft wird mit Status **`draft`** gespeichert. - `fieldValues` werden beim Intake leer initialisiert. - Wenn `globalData` fehlt, wird automatisch `{}` verwendet. - Wenn top-level `businessType` gesetzt ist und `globalData.businessType` leer ist, wird `businessType` in `globalData` gespiegelt. - Wenn `styleProfile` gesetzt ist, wird dieses bevorzugt; fehlende Felder darin werden aus den flachen Stilfeldern ergaenzt. --- ## 7) Rueckgabe aus QC Text Builder an Leadharvester Der Draft-Intake liefert den gespeicherten Draft zurueck. ### Erwartung - **201 Created**, wenn ein neuer Draft erstellt wurde - **200 OK**, wenn ein bestehender Draft aktualisiert wurde ### Wichtige Rueckgabefelder ```json { "id": "1774540501012861000", "templateId": 1408367, "source": "leadharvester", "requestName": "Dönerbude Intake 2026-03-27", "status": "draft", "createdAt": "2026-03-27T12:00:00Z", "updatedAt": "2026-03-27T12:00:00Z" } ``` ### Was Leadharvester speichern sollte Mindestens: ```json { "qcDraftId": "1774540501012861000", "qcTemplateId": 1408367, "qcDraftStatus": "draft" } ``` Diese `qcDraftId` ist wichtig, damit Leadharvester denselben Draft spaeter erneut aktualisieren oder weiterverfolgen kann. --- ## 8) Minimaler Integrationsablauf fuer Coder ```json { "steps": [ "GET /api/templates", "Template in Leadharvester anzeigen (name + thumbnailUrl + templatePreviewUrl)", "templateId aus der Auswahl merken", "Lead-/Stammdaten in Leadharvester sammeln", "POST /api/drafts/intake mit templateId + globalData + Kontext", "draft id aus der Response speichern" ] } ``` --- ## 9) Wichtige Regeln - Leadharvester muss **vor** dem Intake die Templates abrufen. - Leadharvester sollte die `templateId` immer aus der aktuellen Template-Liste verwenden. - `thumbnailUrl` ist fuer kleine Vorschauen gedacht. - `templatePreviewUrl` ist fuer die Vollansicht / Preview gedacht. - Leadharvester sollte die vom Intake zurueckgegebene `draftId` speichern. - Diese `draftId` sollte bei spaeteren Updates wiederverwendet werden. --- ## 10) Kurzfassung **Templates holen** - `GET /api/templates` **Draft anlegen/aktualisieren** - `POST /api/drafts/intake` **Pflicht fuer Leadharvester** - Template waehlen - `templateId` speichern - Stammdaten/Kontext senden - `draftId` aus Response speichern