Bexio Integration

Zeitschätzung vollumfänglich

Arbeitspaket	Aufwand
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
	203h	CHF 25'375

Grundsätzliche Routine (Accounts, Contacts)

bexio	Sage Sales Management
Kontakt vom Typ Firma	Account
Kontakt vom Typ Person ohne Firmenbezug	Contact, optional zusätzlicher Account „Privatkunde“
Kontakt vom Typ Person mit Firmenbezug	Contact mit Verknüpfung zu Account
Lieferant	Account oder Contact mit Klassifikation „Lieferant“
Kunde und Lieferant	Account/Contact mit mehreren Rollen

Verarbeitungsregeln

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	Sage Contact, → optional technischer Account „Privatpersonen“ oder eigener B2C-Account

Feldzuordnung Bexio "Kontakte" ↔ Sage "Accounts"

bexio Kontakt vom Typ Firma ↔ Sage Account

bexio-Feld	Sage Account	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

Zusätzliche Rollenfelder

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

Feldzuordnung Bexio "Kontakte" ↔ Sage "Contacts"

bexio Kontakt vom Typ Person ↔ Sage Contact

bexio-Feld	Sage Contact	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	Sage Salesorder	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

Auftragspositionen

bexio Position	Sage Salesorder Line	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.

Feldzuordnung Bexio Rechnungen ↔Sage "Sales"

Hier würde es Sinn machen nur die Kopfdaten zu übermitteln

bexio Rechnung	Sage Sales	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

Polling-Intervalle für alle Entitäten

Entität	Empfehlung
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