Die Daten der Abonnemente müssen in eine eigene Datenbank der Middleware synchronisiert werden, damit beim zugriff nicht auf die Live-Daten im CRM zugegriffen werden müssen. Sonst kann der Kunde bei beispielsweise eines API-Problems bei Sage nicht auf eine Ausgabe zugreifen.
[](https://wiki.go-solution.ch/uploads/images/gallery/2026-07/GdiqjQIHYm4nsDoo-image.png) ## Mögliche CRM Datenstruktur #### Kontakt beziehungsweise Benutzer| Feld | Beispiel |
|---|---|
| CRM Account ID | `4711` |
| OIDC Subject | `8b153fb2-...` |
| `kunde@example.ch` | |
| Status | aktiv |
| Identity Provider | `keycloak` |
| Feld | Beispiel |
|---|---|
| Subscription ID | `SUB-2026-00123` |
| Contact ID | `4711` |
| Produktcode | `MAGAZIN-PREMIUM` |
| Beginn | `2026-01-01` |
| Ende | `2026-12-31` |
| Status | aktiv |
| Kündigungsdatum | optional |
| Grace Period bis | optional |
| CRM-Produktcode | PressMatrix-ID |
|---|---|
| `MAGAZIN-PREMIUM` | `com.publisher.magazin.premium` |
| `MAGAZIN-2026` | `magazin_issue_2026_*` |
| `ARCHIV-ZUGANG` | Kategorie `archive` |
| Arbeitspaket | Aufwand | Preis |
|---|---|---|
| Technische Analyse bexio API und API-Prototyp | 16h | |
| OAuth-/Token-Handling bexio | 6h | |
| Directus-/MySQL-Tabellen und Migrationen | 8h | |
| Generischer bexio API Client in PHP | 16h | |
| Polling, Cursor, Pagination und Retry | 16h | |
| Lookup- und Benutzer-Mappings | ??? Wird im CRM über Subtabellen geregelt | |
| Kontakte Firma ↔ Sage Accounts | 20h | |
| Kontakte Person ↔ Sage Contacts | 20h | |
| Firmen-/Personenbeziehungen | 12h | |
| Dubletten- und Konfliktlogik Kontakte | ??? Regeln... | |
| Auftragskopf bidirektional | 20h | |
| Auftragspositionen bidirektional | 25h | |
| Status-, Steuer- und Rundungsmapping Aufträge | ???? müssen wir hier etwas beachten | |
| Rechnungen → Sage Sales | 16h | |
| Lösch-/Stornoverhalten | ??? allenfalls über Status | |
| Logging, Monitoring und Fehlerbehandlung | 12h | |
| Integrations- und Regressionstests | 8h | |
| Dokumentation und Deployment | 8h | |
| **Gesamtentwicklung exkl. ?** | **203h à CHF 125.00** | **CHF 25'375** |
| bexio | Sage Sales Management |
|---|---|
| Kontakt vom Typ Firma | Account |
| Kontakt vom Typ Person ohne Firmenbezug | Account mit Flag "natürliche Person" |
| Kontakt vom Typ Person mit Firmenbezug | Contact mit Verknüpfung zu Account |
| Kunde und Lieferant | Account/Contact mit mehreren Rollen |
| Regel | Sage Sales Management |
|---|---|
| bexio contact\_type = Firma | Account |
| bexio contact\_type = Person + Firmenrelation vorhanden | Sage Contact unter bestehendem Sage Account |
| bexio contact\_type = Person + keine Firmenrelation | Account mit Flag "natürlicher Person" |
| bexio Kontakt Feld | Sage Account Feld | Richtung | Bemerkung |
|---|---|---|---|
| `id` | Custom Field `bexio_contact_id` | B → S | Unveränderbare technische Referenz |
| Sage Account-ID | Mappingtabelle `sage_entity_id` | S → Middleware | Nicht zwingend als bexio-Feld verfügbar |
| `nr` | `accountCode` / Custom Field `bexio_contact_nr` | B ↔ S | Geschäftsnummer, nicht als Primärschlüssel verwenden |
| `contact_type_id` | Custom Field `contact_type` | B → S | Firma/Person |
| `name_1` | `name` | B ↔ S | Firmenname |
| `name_2` | `additionalName` / Custom Field | B ↔ S | Zusatzname oder Abteilung |
| `address` | `address` / `address1` | B ↔ S | Strasse und Hausnummer |
| `postcode` | `postalCode` | B ↔ S | |
| `city` | `city` | B ↔ S | |
| `country_id` | `country` / `countryId` | B ↔ S | Lookup-Mapping erforderlich |
| `mail` | `email` | B ↔ S | Firmen-E-Mail |
| `mail_second` | Custom Field `email_secondary` | B ↔ S | Optional |
| `phone_fixed` | `phone` | B ↔ S | |
| `phone_fixed_second` | Custom Field `phone_secondary` | B ↔ S | Optional |
| `phone_mobile` | `mobilePhone` | B ↔ S | Bei Firma eventuell leer |
| `fax` | `fax` / Custom Field | B ↔ S | Falls in Sage vorhanden |
| `url` | `website` | B ↔ S | |
| `remarks` | `comments` / `description` | B ↔ S | Konfliktanfällig bei bidirektionalem Mapping |
| `language_id` | `language` / Custom Field | B ↔ S | Lookup-Tabelle |
| `user_id` | `ownerId` | B ↔ S | Benutzerzuordnung erforderlich |
| `owner_id` | `ownerId` | B ↔ S | Bedeutung in bexio vorgängig prüfen |
| `is_lead` | Account-Klassifikation / Leadstatus | B ↔ S | Businessregel definieren |
| `contact_group_ids` | Tags / Klassifikation | B ↔ S | Many-to-many |
| `contact_branch_ids` | Branche / Segment | B ↔ S | Lookup-Mapping |
| `updated_at` | `source_updated_at` | B → Middleware | Grundlage für Polling |
| Sage Änderungszeit | `sage_updated_at` | S → Middleware | Konflikterkennung |
| technischer Hash | `payload_hash` | intern | Verhindert unnötige Updates |
| Sage-Feld | Werte |
|---|---|
| `business_partner_roles` | Kunde, Lieferant, Interessent |
| `is_customer` | Boolean |
| `is_supplier` | Boolean |
| `bexio_contact_type` | Firma, Person |
| `bexio_contact_id` | Numerische bexio-ID |
| `bexio_contact_nr` | Sichtbare bexio-Kontaktnummer |
| bexio Kontakt Feld | Sage Contact Feld | Richtung | Bemerkung |
|---|---|---|---|
| `id` | Custom Field `bexio_contact_id` | B → S | Technische Referenz |
| Sage Contact-ID | Mappingtabelle | S → Middleware | |
| `nr` | Custom Field `bexio_contact_nr` | B ↔ S | Keine technische ID |
| `name_1` | `lastName` | B ↔ S | Zuordnung anhand effektiver bexio-Nutzung prüfen |
| `name_2` | `firstName` | B ↔ S | Kann je Datenpflege umgekehrt verwendet sein |
| `salutation_id` | `salutation` | B ↔ S | Lookup erforderlich |
| `salutation_form` | Custom Field `salutation_form` | B ↔ S | Optional |
| `title_id` | `title` | B ↔ S | Lookup |
| `birthday` | `birthday` | B ↔ S | Datenschutz beachten |
| `address` | `address` | B ↔ S | Privat- oder Geschäftsadresse |
| `postcode` | `postalCode` | B ↔ S | |
| `city` | `city` | B ↔ S | |
| `country_id` | `country` | B ↔ S | Lookup |
| `mail` | `email` | B ↔ S | Empfohlenes Dublettenmerkmal |
| `mail_second` | Custom Field `email_secondary` | B ↔ S | |
| `phone_fixed` | `phone` | B ↔ S | |
| `phone_fixed_second` | Custom Field | B ↔ S | |
| `phone_mobile` | `mobilePhone` | B ↔ S | |
| `fax` | `fax` / Custom Field | B ↔ S | |
| `skype_name` | Custom Field | B ↔ S | Nur falls weiterhin relevant |
| `remarks` | `comments` / `description` | B ↔ S | Konfliktregel notwendig |
| `language_id` | `language` | B ↔ S | Lookup |
| Firmenrelation | `accountId` | B ↔ S | Über Kontaktbeziehung bestimmen |
| `user_id` / `owner_id` | `ownerId` | B ↔ S | Benutzer-Mapping |
| `contact_group_ids` | Tags / Kategorien | B ↔ S | |
| `updated_at` | Middleware-Syncstatus | B → intern |
Kritischer Punkt: Account-Verknüpfung Für eine Person mit Firmenbezug muss die Reihenfolge lauten: 1. Firmenkontakt in bexio identifizieren. 2. Zugehörigen Sage Account suchen oder erstellen. 3. Person als Sage Contact erstellen. 4. `accountId` des Contacts auf den Sage Account setzen. 5. Beziehung in einer Mappingtabelle speichern. Eine Person sollte nicht anhand des Firmennamens allein zugeordnet werden. Primär sollte die bexio-Beziehungs-ID beziehungsweise die externe Kontakt-ID verwendet werden.
### Feldzuordnung Bexio "Aufträge" ↔Sage "Salesorders" bexio stellt Aufträge als Dokumentressource bereit. Für eine vollständige Synchronisation müssen Dokumentkopf und Positionen getrennt betrachtet werden. Die bexio API bietet Verwaltungsfunktionen für Verkaufsaufträge und weitere Verkaufsdokumente. #### AuftragsKopf| bexio Auftrag Feld | Sage Salesorder Feld | Richtung | Bemerkung |
|---|---|---|---|
| `id` | Custom Field `bexio_order_id` | B → S | Technischer Schlüssel |
| Sage Salesorder-ID | Mappingtabelle | S → intern | |
| `document_nr` | `orderNumber` | B ↔ S | Sichtbare Auftragsnummer |
| `title` | `name` / `title` | B ↔ S | |
| `contact_id` | `accountId` | B ↔ S | Über Kontaktmapping |
| `contact_sub_id` | `contactId` | B ↔ S | Ansprechpartner |
| `user_id` | `ownerId` | B ↔ S | Benutzer-Mapping |
| `project_id` | `projectId` / Custom Field | B ↔ S | Optional |
| `language_id` | `language` | B ↔ S | Lookup |
| `currency_id` | `currency` | B ↔ S | Lookup, ISO-Code bevorzugen |
| `payment_type_id` | `paymentTerms` | B ↔ S | Lookup |
| `bank_account_id` | Custom Field | B ↔ S | Nur falls fachlich benötigt |
| Dokumentdatum | `orderDate` | B ↔ S | Feldname in bexio prüfen |
| `is_valid_from` | `validFrom` | B ↔ S | Optional |
| `is_valid_to` | `validUntil` | B ↔ S | Optional |
| `header` | `headerText` / Beschreibung | B ↔ S | |
| `footer` | `footerText` / Beschreibung | B ↔ S | |
| `contact_address` | Rechnungsadresse | B ↔ S | Snapshot des Dokuments |
| `delivery_address` | Lieferadresse | B ↔ S | |
| `delivery_address_type` | Lieferadresstyp | B ↔ S | Lookup |
| `total_net` | `netAmount` | B → S | Berechnetes Feld möglichst nicht zurückschreiben |
| `total_taxes` | `taxAmount` | B → S | |
| `total_gross` | `grossAmount` | B → S | |
| `mwst_type` | `taxType` | B ↔ S | Lookup |
| `mwst_is_net` | `pricesIncludeTax` | B ↔ S | Boolean-Transformation |
| `show_position_taxes` | Custom Field | B ↔ S | Darstellungsinformation |
| `kb_item_status_id` | `status` | B ↔ S | Statustabelle erforderlich |
| `api_reference` | `externalReference` | B ↔ S | Sehr gut für Integrationsreferenz geeignet |
| `updated_at` | Syncstatus | B → intern | Polling |
| Sage Änderungszeit | Syncstatus | S → intern | Konflikterkennung |
| bexio Position Feld | Sage Salesorder Line Feld | Richtung | Bemerkung |
|---|---|---|---|
| Positions-ID | `externalLineId` | B → S | Mappingtabelle |
| `amount` | `quantity` | B ↔ S | |
| `unit_id` | `unit` | B ↔ S | Lookup |
| `text` | `description` | B ↔ S | |
| `unit_price` | `unitPrice` | B ↔ S | |
| `discount_in_percent` | `discountPercent` | B ↔ S | |
| Artikelreferenz | `productId` / `articleId` | B ↔ S | Nur mit Artikelmapping |
| Steuersatz-ID | `taxRate` / `taxId` | B ↔ S | Lookup |
| Positionssumme | `lineTotal` | B → S | Berechnetes Feld |
| Sortierung | `position` / `sortOrder` | B ↔ S | |
| Positionstyp | `lineType` | B ↔ S | Normal, Titel, Zwischensumme, Text etc. |
| bexio Rechnung Feld | Sage Sales Feld | Richtung | Bemerkung |
|---|---|---|---|
| `id` | Custom Field `bexio_invoice_id` | B → S | Technische Referenz |
| `document_nr` | `saleNumber` / `invoiceNumber` | B → S | |
| `title` | `name` / `title` | B → S | |
| `contact_id` | `accountId` | B → S | Über Mapping |
| `contact_sub_id` | `contactId` | B → S | Ansprechpartner |
| `user_id` | `ownerId` | B → S | Benutzer-Mapping |
| `project_id` | Custom Field / Projekt | B → S | Optional |
| `currency_id` | `currency` | B → S | Lookup |
| `language_id` | Custom Field | B → S | |
| Rechnungsdatum | `saleDate` / `invoiceDate` | B → S | |
| Fälligkeitsdatum | `dueDate` | B → S | |
| `payment_type_id` | `paymentTerms` | B → S | Lookup |
| `header` | `description` / Custom Field | B → S | |
| `footer` | Custom Field | B → S | |
| `total_net` | `netAmount` | B → S | |
| `total_taxes` | `taxAmount` | B → S | |
| `total_gross` | `grossAmount` | B → S | |
| erhaltene Zahlungen | `paidAmount` | B → S | Falls Sales dies unterstützt |
| offener Betrag | `openAmount` | B → S | |
| Rechnungsstatus | `status` | B → S | Entwurf, offen, bezahlt, storniert |
| `mwst_type` | `taxType` | B → S | |
| `mwst_is_net` | `pricesIncludeTax` | B → S | |
| `contact_address` | Rechnungsadresse | B → S | Dokument-Snapshot |
| `api_reference` | `externalReference` | B → S | |
| `updated_at` | Syncstatus | B → intern |
| Entität | Intervall |
|---|---|
| Kontakte | alle 5–15 Minuten |
| Aufträge | alle 5 Minuten |
| Rechnungen | alle 5–15 Minuten |
| Lookup-Daten | täglich |
| vollständiger Abgleich | nachts oder wöchentlich |
Laut Schnittstellendokumentation können Kunden oder Firmen nicht explizit abgeholt werden. Kundendaten sind immer Bestandteil einer Bestellung.. **Die Schnittstellen-Integration ist nach diesem Kriterium "fragwürdig"**
- Gutscheinbestellungen können zeitlich gefiltert abgerufen werden. - Einzelne Bestellungen können abgerufen werden. - Neue Gutscheinbestellungen können angelegt werden. - Für neu erstellte Bestellungen existiert ein Webhook. - Kundendaten sind Bestandteil einer Bestellung. - Es sind **keine öffentlich dokumentierten, eigenständigen CRUD-Endpunkte für Kunden oder Firmen** ersichtlich. #### Realisierbarkeit| Gewünschte Entität | Realisierbarkeit | Empfohlene Richtung |
|---|---|---|
| Accounts | Teilweise, nur über Bestellung nicht sinnvoll weil keine eindeutige Kennung vorhanden ist | e-guma → Sage Sales Management |
| Kontakte | Teilweise, nur über Bestellung nicht sinnvoll weil keine eindeutige Kennung vorhanden ist | e-guma → Sage Sales Management |
| Sales | Gut möglich | e-guma → Sage Sales Management |
| Aufträge | Gut möglich | e-guma → Sage Sales Management; optional Sage → e-guma |
| Gutschein-/Produktstammdaten | Möglich | e-guma → Sage Sales Management |
| Marketing-Einwilligung | Möglich | e-guma → Sage Sales Management |
Damit der Zugriff funktioniert muss "CRON\_SECRET" in den Environment-Variabeln im header "authorization" als Bearer mitgegeben werden!
| Endpunkt | Beschreibung | Zeiten |
| /api/lotta/access-groups | Access-Groups synchronisieren | 06:00, 12:00, 18:00 |
| /api/aleno/sync-reservations | Aleno-Reservierungen synchronisieren | 06:00, 12:00, 18:00 |
| /api/mews/sync-reservations | Mews-Reservierungen synchronisieren | 06:00, 12:00, 18:00 |
| /api/guests/process | Gäste-Zugriffe synchronisieren / aktualisieren | alle 5 Minuten |