Daten und Automatisierung

Die Daten des Partnerprogramms in andere Systeme bringen.

Für Buchhaltung, Warenwirtschaft und eigene Auswertungen exportiert das Partnerprogramm seine Daten über Shopwares Import/Export als CSV-Datei. Eine Admin-API liefert Guthaben und Tageszahlen eines Partners und legt Auszahlungen an. Im Hintergrund halten geplante Aufgaben und Konsolenbefehle Provision, Partnergruppen, Auszahlungen und Klicks aktuell.

Marketing → Partnerprogramm → Seitenmenü System → Export

Export als CSV-Datei

Wie exportiere ich Partner, Buchungen, Auszahlungen und Klicks?

Das Partnerprogramm bringt vier Exportprofile für Shopwares Import/Export mit. Der Menüpunkt Export öffnet dort den Reiter Export. Jede Datei ist eine CSV-Datei mit Semikolon als Trennzeichen, bereit für Excel, die Buchhaltung oder ein eigenes Werkzeug. Die Profile sind Systemprofile: Sie lassen sich nicht ändern, aber unter Profile kopieren und als Kopie anpassen.

  1. 1Klicke im Seitenmenü des Partnerprogramms auf System → Export.

  2. 2Tippe im Feld Profil „partner_program“ ein; die Auswahl zeigt alle vier Profile. Wähle eines aus.

  3. 3Klicke auf Export starten.

  4. 4Unter Export-Aktivität steht der Export mit Profil, Status, Zahl der Einträge und Größe. Über das Menü der Zeile lädst du die Datei herunter. Aktivitäten, die älter als 30 Tage sind, entfernt Shopware automatisch.

ProfilInhaltSpalten der Datei
partner_program_partnersPartnerprogramm: Partnerid, name, code, customer_number, customer_email, active, confirmed, partner_group, commission_type, commission, commission_subsequent, payout_method, account_holder, iban, bic, paypal_email, vat_id, created_at
partner_program_commissionsPartnerprogramm: Provisionsbuchungenid, partner_code, order_number, type, level, amount, commission, commission_redeemed, comment, created_at
partner_program_redemptionsPartnerprogramm: Einlösungen und Auszahlungenid, number, partner_code, type, value, bonus, payout_method, payout_state, origin, recipient_name, recipient_iban, recipient_email, paid_at, created_at
partner_program_clicksPartnerprogramm: Klicksid, partner_code, clicked_at, landing_page, referrer, utm_source, utm_campaign, device, order_number, converted_at

Admin-API

Welche Admin-API bietet das Partnerprogramm?

Fünf Routen der Admin-API von Shopware binden ein anderes System an, etwa eine Buchhaltung oder ein eigenes Partnerportal. Alle liegen unter /api/_action/dvsn-affiliate/, antworten mit JSON und verlangen das Recht „Partnerprogramm nutzen (Vollzugriff)“. Beträge stehen in der Standardwährung, gerundet auf zwei Stellen. Angemeldet wird wie bei jeder Admin-API von Shopware, zum Beispiel mit einer Integration, deren Rolle dieses Recht hat.

Methode und PfadWas sie tutAntwort
GET …/partner/{partnerId}/balanceGuthaben eines Partners, gerechnet wie im Partnerbereich.commission (alle provisionsfähigen Buchungen), redeemed (eingelöst), available (verfügbar), openPayouts mit Anzahl und Betrag, dazu Code und Währung
GET …/partner/{partnerId}/daily?from=JJJJ-MM-TT&to=JJJJ-MM-TTZahlen je Tag, höchstens 366 Tage.je Tag orders, customers, turnover und commission
POST …/partner/{partnerId}/payoutLegt eine Auszahlung an wie ein Antrag des Partners, mit Herkunft „API“. Ohne Betrag gilt bei freiem Betrag das ganze Guthaben; bei Staffeln ist der Betrag Pflicht.201 mit payoutId, number, amount, state „requested“
POST …/payout/{payoutId}/decideGibt eine Auszahlung frei oder lehnt sie ab: decision „approve“ oder „reject“, bei Ablehnung optional reason.payoutId, number, amount, state
POST …/payout/{payoutId}/paidMeldet eine außerhalb bezahlte Auszahlung als ausgezahlt, optional mit reference (höchstens 255 Zeichen). Der Verlauf nennt die Referenz.payoutId, number, amount, state „paid“

Eine Auszahlung über die API nimmt denselben Weg wie der Antrag im Partnerbereich: vollständige Auszahlungsdaten, Staffel oder Mindestbetrag, Verrechnung mit der ältesten Provision zuerst, Nummer und Dokument. Sie erscheint in Liste und Prüfliste mit der Herkunft „API“ und geht wie jeder Antrag in die Prüfung; eine E-Mail an den Shop und eine Bestellung zur Einlösung entstehen dabei nicht. Gelesen werden Partner, Buchungen und Auszahlungen über die allgemeinen Endpunkte von Shopware, etwa /api/search/dvsn-affiliate, /api/search/dvsn-affiliate-commission und /api/search/dvsn-affiliate-redeem-history.

Welche Fehler meldet die API?

Abgelehnte Aufrufe antworten im Fehlerformat von Shopware mit einem eigenen Code, damit das anbindende System gezielt reagieren kann.

CodeHTTPWann
DVSN_AFFILIATE__PARTNER_NOT_FOUND404unbekannte Partner-ID
DVSN_AFFILIATE__PAYOUT_NOT_FOUND404unbekannte Auszahlung oder ein Gutschein statt einer Auszahlung
DVSN_AFFILIATE__INVALID_PERIOD400Datum fehlt oder ist falsch, from liegt nach to oder mehr als 366 Tage
DVSN_AFFILIATE__INVALID_AMOUNT400Betrag keine Zahl, keine Staffel, unter dem Mindestbetrag oder über dem Guthaben; ohne Betrag bei Staffeln
DVSN_AFFILIATE__INVALID_DECISION400decision ist weder „approve“ noch „reject“
DVSN_AFFILIATE__INVALID_REFERENCE400reference ist kein Text oder länger als 255 Zeichen
DVSN_AFFILIATE__PARTNER_INACTIVE409Partner inaktiv oder nicht freigeschaltet
DVSN_AFFILIATE__PAYOUT_NOT_ALLOWED409Die Art der Vergütung des Partners erlaubt keine Auszahlung.
DVSN_AFFILIATE__RECIPIENT_MISSING409Auszahlungsdaten des Partners unvollständig
DVSN_AFFILIATE__INVALID_TRANSITION409Übergang nicht erlaubt, etwa eine bezahlte Auszahlung ablehnen

Automatisierung

Welche geplanten Aufgaben laufen im Hintergrund?

Vier geplante Aufgaben halten das Programm aktuell. Sie laufen über die geplanten Aufgaben von Shopware und setzen damit einen laufenden Worker voraus. Die drei häufigen Aufgaben rechnen je Lauf höchstens 55 Sekunden und machen beim nächsten Lauf weiter, so blockiert auch ein Shop mit vielen Partnern den Worker nicht.

AufgabeTaktWas sie tut
dvsn.affiliate.update_commissionalle 15 MinutenAbgleich: bucht die Provision neuer Bestellungen, mit „Nur Partner mit neuen Bestellungen“ nur für diese Partner. Läuft nur mit „Per geplanter Aufgabe“.
dvsn.affiliate.promote_tiersalle 15 MinutenAufstieg in Partnergruppen; prüft immer alle Partner.
dvsn.affiliate.create_payoutsalle 15 MinutenLegt am Auszahlungstag die automatischen Auszahlungen an, an anderen Tagen tut sie nichts.
dvsn.affiliate.purge_clickstäglichLöscht Klicks nach ihrer Aufbewahrungsfrist.

So findest du sie in den Einstellungen (Partnerprogramm-Menü links unter System → Einstellungen):

  • Karte System · Geplante Aufgaben und Konsole → Geplante Aufgaben ausführenAus: Der Abgleich der Provisionen, der Aufstieg in Partnergruppen, die automatischen Auszahlungen und das Löschen alter Klicks kehren bei jedem Aufruf sofort zurück und tun nichts. Ein fälliger Auszahlungstag wartet, bis die Aufgaben wieder an sind, und macht dann weiter. Klicks nach ihrer Aufbewahrungsfrist bleiben liegen, bis der Befehl sie löscht.

  • Karte System · Geplante Aufgaben und Konsole → Konsolenbefehle erlaubenAus: Jeder Konsolenbefehl mit dem Präfix „dvsn-affiliate:“ bricht mit einer Meldung ab, bevor er etwas tut. Administration, Partnerbereich und geplante Aufgaben sind nicht betroffen.

Welche Konsolenbefehle gibt es?

Fünf Befehle für die Konsole, zum Beispiel für einen eigenen Cronjob in großen Shops. Sie laufen aus dem Shopware-Ordner mit bin/console. Die Karte System · Berechnung der Provision legt fest, auf welchen Wegen die Provision neuer Bestellungen entsteht.

BefehlOptionenWas er tut
dvsn-affiliate:update-commission--partner-code (-pc), --only-delta, --debug-mode (-dm)Abgleich aller Partner oder eines Partners; mit --only-delta nur Partner mit neuen Bestellungen, mit --debug-mode mit jeder Berechnung. Läuft nur mit „Per Konsolenbefehl“.
dvsn-affiliate:reset-orderBestellnummern, durch Komma getrenntLöscht die Provisionsbuchungen dieser Bestellungen, damit der nächste Abgleich sie neu rechnet. Bestellungen mit eingelöster oder ausgezahlter Provision bleiben unberührt.
dvsn-affiliate:tier:promote--partner-code (-pc)Aufstieg in die höchste erreichte Partnergruppe, für alle oder einen Partner.
dvsn-affiliate:click:purge--sales-channel mit der ID eines VerkaufskanalsLöscht Klicks nach der Aufbewahrungsfrist ihres Verkaufskanals.
dvsn-affiliate:payout:createLegt die automatischen Auszahlungen eines fälligen Auszahlungstags an.

So findest du sie in den Einstellungen (Partnerprogramm-Menü links unter System → Einstellungen):

  • Karte System · Berechnung der Provision → Live beim Aufruf des PartnerbereichsBeim Aufruf des Partnerbereichs wird für den aktuellen Partner live die aktuelle Provision berechnet. Für kleinere Shops die empfohlene Vorgehensweise, um dem Partner immer seine aktuellsten Daten anzuzeigen. Je größer der Shop, desto länger ist jedoch die Wartezeit für den Aufruf, da die Berechnung der Provision von neuen Bestellungen im Zweifel sehr lange dauern kann.

  • Karte System · Berechnung der Provision → Per geplanter AufgabeDie Provision von neuen Bestellungen wird asynchron und automatisch für alle Partner in einer geplanten Aufgabe berechnet. Für kleine bis mittelgroße Shops empfohlen, um einen „Stau“ von Bestellungen zu vermeiden, wenn ein Partner seinen Partnerbereich aufruft.

  • Karte System · Berechnung der Provision → Nur Partner mit neuen BestellungenWenn aktiviert, geht jeder Lauf der geplanten Aufgabe zur Berechnung nur die Partner durch, die eine Bestellung ohne Provision haben, statt jeden Partner. Für Shops mit vielen Partnern empfohlen. Gilt nur für die geplante Aufgabe; der Konsolenbefehl hat dafür die Option --only-delta. Der Aufstieg in Partnergruppen hat eine eigene geplante Aufgabe und prüft immer alle Partner.

  • Karte System · Berechnung der Provision → Per KonsolenbefehlDie Provision von neuen Bestellungen wird über einen Konsolenbefehl für alle oder einzelne Partner berechnet. Die Ausführung des Konsolenbefehls muss selber geplant und sichergestellt werden. Für mittelgroße bis große Shops empfohlen, um alle Provisionen von neuen Bestellungen möglichst kontinuierlich und zeitnah zu berechnen, um Last auf den Shop zu minimieren.

Recht

Welches Recht brauchen Admin-Benutzer und Integrationen?

Ein einziges Recht öffnet das ganze Partnerprogramm: alle Seiten des Seitenmenüs, die Reiter „Partnerprogramm“ an Bestellung, Kunde und Produkt, den Export, die Admin-API und die Seiten des Zusatz-Plugins Multi-Level-Marketing. Mit ihm kommt Shopwares Recht für Import/Export, weil der Menüpunkt „Export“ dort die Profile öffnet, und das Speichern der Konfiguration, das der Einrichtungsassistent braucht.

  1. 1Öffne Einstellungen → Benutzer & Rechte und bearbeite die Rolle, etwa „Partnermanagement“.

  2. 2Schalte unter Zusätzliche Berechtigungen in der Gruppe Partnerprogramm das Recht Partnerprogramm nutzen (Vollzugriff) ein und speichere.

  3. 3Import/Export gehört als Abhängigkeit dazu; ohne es öffnet der Menüpunkt „Export“ nichts.

Was außerdem gilt:

  • Als Partner anmelden am Partner braucht zusätzlich Shopwares Recht „Imitiere einen Kundenlogin“; ohne es bleibt der Knopf gesperrt und nennt den Grund.
  • Das Auszahlungsdokument als PDF darf jeder angemeldete Benutzer der Administration laden.
  • Für die Admin-API legst du unter Einstellungen → Integrationen eine Integration mit einer Rolle an, die das Recht hat.

← Zurück zum Handbuch

Häufige Fragen

Wie exportiere ich alle Partner als CSV-Datei?

Im Seitenmenü des Partnerprogramms unter System, Export das Profil partner_program_partners wählen und Export starten. Die Datei steht danach unter Export-Aktivität zum Herunterladen bereit, als CSV mit Semikolon.

Kann ich die Exportprofile anpassen?

Die vier Profile sind Systemprofile und lassen sich nicht ändern. In Shopwares Import/Export unter Profile kannst du eines kopieren und die Kopie anpassen, etwa Spalten weglassen.

Kann ein externes System Auszahlungen anlegen?

Ja. Die Route POST /api/_action/dvsn-affiliate/partner/{partnerId}/payout legt eine Auszahlung wie ein Antrag des Partners an, mit Herkunft API. Sie geht wie jeder Antrag in die Prüfung; über die API lässt sie sich auch freigeben und als bezahlt melden.

Wie oft wird die Provision neuer Bestellungen berechnet?

Die geplante Aufgabe läuft alle 15 Minuten. Dazu rechnet das Partnerprogramm live, wenn ein Partner seinen Partnerbereich öffnet, und auf Wunsch per Konsolenbefehl. Jeder der drei Wege ist einzeln schaltbar.

Was passiert, wenn der Worker von Shopware nicht läuft?

Dann laufen die geplanten Aufgaben nicht: Die Provision entsteht nur noch live beim Aufruf des Partnerbereichs oder per Konsolenbefehl, Partner steigen nicht auf, automatische Auszahlungen warten und alte Klicks bleiben liegen.

Welches Recht braucht ein Mitarbeiter für das Partnerprogramm?

Das Recht Partnerprogramm nutzen (Vollzugriff) unter Zusätzliche Berechtigungen in seiner Rolle. Es öffnet das ganze Partnerprogramm einschließlich Export und Admin-API.

Ausführlich im Handbuch

Weitere Kapitel

Multi-Level-Marketing Partner verdienen an den Bestellungen der Partner, die sie geworben haben: Ebenen, Sätze, Netzwerk am Partner, Statistiken und der Baum im Partnerbereich. Ansehen → Alle Einstellungen Alle Karten der Konfiguration mit jedem Feld, seinem Standardwert und seiner Wirkung, für Partnerprogramm und Multi-Level-Marketing. Ansehen → Begriffe Die Wörter des Partnerprogramms in je zwei Sätzen erklärt, mit üblichen Synonymen und dem Ort, an dem sie im Shop stehen. Ansehen →