# Transaktions API - Dokumentation

Über die Transaktions-API holen Sie alle Transaktionen Ihres Partnerprogramms als Datei oder als JSON ab: mit Status, Umsatz, Provision, Publisher und Projekt. Damit lassen sich Abrechnung, Kostenauswertung und die Anbindung externer Tools (BI, Attribution, Data Warehouse) automatisieren. Diese Seite beschreibt, wie Sie einen Zugang einrichten, wie der Aufruf aussieht, welche Filter es gibt und was in jeder Spalte steht.

## Überblick

| Schritt | Was passiert | Wo |
|---|---|---|
| **1. Zugang einrichten** | eigener Benutzer mit eigenem API-Token, nur mit Leserechten | Systemsteuerung → Berechtigungsgruppen und Benutzerverwaltung |
| **2. Link holen** | fertiger Abruflink mit Token, Benutzer-ID und Format | API → Daten-API, Zeile **Transaktionen** |
| **3. Filtern und abrufen** | Zeitraum, Status, Kampagne an den Link hängen und regelmäßig abrufen | Ihr System oder das externe Tool |

---

## Schritt 1: Zugang einrichten

Jeder Benutzer im System hat seinen eigenen API-Token. Der Token gibt genau die Daten frei, die dieser Benutzer auch in der Oberfläche sehen darf.

**Für externe Tools und Dienstleister empfehlen wir immer einen eigenen Benutzer**, nicht Ihren persönlichen Zugang. So bestimmen Sie selbst, was das Tool sieht, und können den Zugang jederzeit sperren oder den Token erneuern, ohne dass Ihr eigener Login betroffen ist.

### Berechtigungsgruppe anlegen

1. **Systemsteuerung → Berechtigungsgruppen** öffnen und **Neue Gruppe anlegen** klicken.
2. Einen sprechenden Namen vergeben, zum Beispiel `API lesend`.
3. Nur das freigeben, was das Tool braucht:

| Berechtigung | Einstellung | Wofür |
|---|---|---|
| **Transaktionsliste** | `ACCESS_READ` | Transaktions-API |
| **Export-Links** | `yes` | Abruflinks auf der Seite Daten-API |
| **Publisher Daten anzeigen** | `yes`, wenn Publisher-Namen gebraucht werden | Spalten `publisher_prename`, `publisher_surname`, `publisher_searchtitle` |
| Statistiken, die abgerufen werden sollen | `ACCESS_READ` | nur bei Nutzung der [Statistik-API](https://docs.easy-m.de/link/46) |
| alles andere | `ACCESS_DENY` bzw. `no` | |

Was die einzelnen Rechte bedeuten, steht unter [Berechtigungen für Nutzer des Systems einstellen](https://docs.easy-m.de/link/191).

### Benutzer anlegen

1. **Systemsteuerung → Benutzerverwaltung** öffnen und einen neuen Benutzer anlegen.
2. Name und E-Mail so wählen, dass klar ist, wofür der Zugang da ist, zum Beispiel `API Kostenimport`.
3. Die eben angelegte Berechtigungsgruppe zuweisen und speichern.

### Token ablesen

- **Als dieser Benutzer einloggen** und **API → Daten-API** öffnen. Dort stehen der Token und die fertigen Abruflinks.
- Superuser sehen den Token auch direkt in der **Benutzerverwaltung** beim Benutzer, Feld **API-Token** (Auge-Symbol zum Einblenden).

**Token erneuern:** In der Benutzerverwaltung über das Pfeil-Symbol neben dem Token oder auf der Seite Daten-API über **Neu generieren**. Der alte Token ist danach sofort ungültig. Das externe Tool braucht dann den neuen Link.

**Zugang beenden:** Benutzer in der Benutzerverwaltung deaktivieren oder löschen. Der Token funktioniert danach nicht mehr.

---

## Schritt 2: Der Aufruf

```
https://<Systemdomain>/api/<ACCESS-TOKEN>/admin/<BENUTZER-ID>/get-orders.<FORMAT>
```

| Teil | Inhalt |
|---|---|
| `<Systemdomain>` | Domain Ihres Systems, die Sie auch für den Login nutzen |
| `<ACCESS-TOKEN>` | API-Token des Benutzers aus Schritt 1 |
| `<BENUTZER-ID>` | ID dieses Benutzers |
| `<FORMAT>` | `csv`, `json` oder `xml` |

Am einfachsten kopieren Sie den Link fertig von **API → Daten-API**, Zeile **Transaktionen**. Token und Benutzer-ID sind dort schon eingesetzt.

**Beispiel:** alle bestätigten und ausgezahlten Transaktionen aus Januar 2026 als JSON

```
https://<Systemdomain>/api/<ACCESS-TOKEN>/admin/<BENUTZER-ID>/get-orders.json?condition[l:status]=confirmed,paid&condition[period][from]=01.01.2026&condition[period][to]=31.01.2026&condition[datemode]=incoming
```

Mit `curl`:

```bash
curl -g "https://<Systemdomain>/api/<ACCESS-TOKEN>/admin/<BENUTZER-ID>/get-orders.csv?condition[period][from]=01.01.2026&condition[period][to]=31.01.2026" -o transaktionen.csv
```

`-g` ist nötig, damit `curl` die eckigen Klammern nicht selbst auswertet.

### Antworten

| Code | Bedeutung |
|---|---|
| `200` | Daten kommen im gewählten Format. |
| `401` | Token oder Benutzer-ID passen nicht zusammen, oder der Token wurde erneuert. |
| `404` | Die Adresse stimmt nicht, meist ein Tippfehler im Pfad oder Format. |

---

## Schritt 3: Filtern

Alle Filter werden als Parameter an den Link gehängt und mit `&` verbunden.

### Zeitraum

| Parameter | Beispiel | Bedeutung |
|---|---|---|
| `condition[period][from]` | `01.01.2026` | Startdatum |
| `condition[period][to]` | `31.01.2026` | Enddatum |
| `condition[datemode]` | `incoming` | Worauf sich der Zeitraum bezieht, siehe unten |

| `datemode` | Der Zeitraum gilt für |
|---|---|
| `incoming` | das Transaktionsdatum, also wann die Bestellung erfasst wurde |
| `processing` | das Datum der Bestätigung oder Stornierung |
| `payout` | das Auszahlungsdatum |

Für Kostenauswertungen nach Bestelldatum nehmen Sie `incoming`, für die tatsächlich ausgezahlten Provisionen eines Monats `payout`.

### Status

| Parameter | Wert | Liefert |
|---|---|---|
| `condition[l:status]` | `open` | offene Transaktionen |
| | `confirmed` | bestätigte Transaktionen |
| | `paid` | ausgezahlte Transaktionen |
| | `canceled` | stornierte Transaktionen |

Mehrere Status mit Komma trennen: `condition[l:status]=confirmed,paid`

### Kampagne

| Parameter | Beispiel | Bedeutung |
|---|---|---|
| `condition[l:campaigns]` | `1` oder `1,3` | nur Transaktionen dieser Kampagnen |

---

## Die Felder

Die Datei enthält eine Zeile je Transaktion. Beträge sind netto, sofern nicht anders angegeben.

### Transaktion

| Feld | Inhalt |
|---|---|
| `id` | Eindeutige ID der Transaktion in unserem System |
| `ordertoken` | Ihre Bestellnummer, wie sie beim Tracking übergeben wurde |
| `ebestid` | Verschlüsselte Bestellnummer, wie der Publisher sie sieht |
| `type` | Art der Transaktion, zum Beispiel Sale, Lead oder View |
| `status` | 0 offen, 1 bestätigt, 2 storniert, 3 ausgezahlt |
| `sub_status` | Ihr eigener Bearbeitungsstatus |
| `cancel_reason` | Stornogrund |
| `visibility` | Sichtbarkeit für den Publisher |
| `timestamp` | Zeitpunkt der Transaktion |
| `order_timestamp` | Zeitpunkt des Bestellaufrufs |
| `action_timestamp` | Zeitpunkt des Klicks oder Views, der zur Bestellung führte |
| `status_change_date` | Datum der letzten Statusänderung |
| `last_change` | Zeitpunkt der letzten Änderung |
| `payoutdate` | Auszahlungsdatum |
| `description` | Beschreibung, die mit der Transaktion übergeben wurde |
| `basket_items` | Anzahl der Artikel im Warenkorb |

### Umsatz und Provision

| Feld | Inhalt |
|---|---|
| `turnover` | Provisionsrelevanter Bestellwert |
| `turnover_brutto` | Bestellwert inklusive Steuern |
| `source_turnover` | Bestellwert, wie er ursprünglich übergeben wurde |
| `original_turnover` | Bestellwert in der Währung der Bestellung |
| `attributed_turnover` | Anteiliger Bestellwert, wenn ein Attributionsmodell aktiv ist |
| `order_currency` | Währung der Bestellung |
| `commission` | **Provision des Publishers**, aktueller Stand nach dem Sales-Abgleich |
| `source_commission` | Provision zum Zeitpunkt der Transaktion, ändert sich nicht |
| `attribution` | Betrag der gezahlten Attribution |
| `trigger_id` | Trigger der Transaktion |
| `trigger_title` | Name des Triggers |
| `trigger_type` | Fixvergütung oder prozentuale Vergütung |
| `trigger_value` | Vergütung, die zum Zeitpunkt der Transaktion im Trigger hinterlegt war |
| `commission_group_id` | Provisionsgruppe des Publishers zum Zeitpunkt der Transaktion |
| `campaign_group_title` | Name dieser Provisionsgruppe |
| `salary_id` | Auszahlung, mit der die Transaktion abgerechnet wurde |
| `bonus_id` | Bonuslauf, falls die Transaktion aus einem Bonus stammt |

### Publisher, Projekt und Kampagne

| Feld | Inhalt |
|---|---|
| `publisher_id` | ID des Publishers |
| `publisher_prename`, `publisher_surname` | Vor- und Nachname des Publishers |
| `publisher_searchtitle` | Suchtitel des Publishers |
| `project_id` | ID des Projekts (Website oder Kanal des Publishers) |
| `project_title` | Name des Projekts |
| `campaign_id` | ID der Kampagne |
| `campaign_title` | Name der Kampagne |
| `advertiser_id` | ID des Advertisers |
| `advertiser_title` | Name des Advertisers |
| `admedia_id` | Werbemittel, über das die Transaktion entstand |
| `subid` | Sub-ID, die der Publisher mitgegeben hat |

### Herkunft und Tracking

| Feld | Inhalt |
|---|---|
| `source` | Quelle der Transaktion |
| `referrer` | Seite, auf der geklickt wurde |
| `country` | Land der Transaktion |
| `user_agent` | Browser und Gerät des Kunden |
| `session_id` | Session-ID, die mit der Transaktion übergeben wurde |
| `action_id` | Action-ID, die mit der Transaktion übergeben wurde |
| `order_actions_id` | Verweis auf den provisionsrelevanten Klick oder View |
| `customer_journey_status` | Kennziffer zur Customer Journey |
| `delivered_tagcode_count` | Anzahl der ausgespielten Tags |
| `delivered_tagcode_serversided_url` | Übermittelter serverseitiger Trackingaufruf |

### Externe Quellen

Nur gefüllt, wenn Transaktionen aus einem angebundenen Netzwerk oder einer externen Quelle stammen.

| Feld | Inhalt |
|---|---|
| `external_sources_entity_id` | Konto-ID in der externen Quelle |
| `external_sources_turnover` | Bestellwert laut externer Quelle |
| `external_sources_currency_code` | Währung in der externen Quelle |
| `external_sources_currency_rate` | Umrechnungskurs in Ihre Systemwährung |
| `source_project_id` | Publisher- oder Projekt-ID in der externen Quelle |
| `source_project_title` | Publisher- oder Projektname in der externen Quelle |

---

## Häufige Fragen

**Wie komme ich an die Affiliate-Kosten je Publisher?**
Bestätigte und ausgezahlte Transaktionen abrufen (`condition[l:status]=confirmed,paid`) und die Spalte `commission` je `publisher_id` oder `project_title` summieren. Offene Transaktionen können sich im Sales-Abgleich noch ändern.

**Brauche ich nur Summen statt einzelner Transaktionen?**
Dafür ist die [Statistik-API](https://docs.easy-m.de/link/46) da, zum Beispiel `get-statistic_publisher` oder `get-statistic_daily`.

**Wie oft darf ich abrufen?**
Einmal pro Stunde oder einmal pro Nacht reicht für fast alle Fälle. Rufen Sie lieber kurze Zeiträume häufiger ab als ein ganzes Jahr auf einmal.

**Das Tool bekommt plötzlich `401`.**
Der Token wurde erneuert oder der Benutzer deaktiviert. Neuen Link von der Seite Daten-API holen und im Tool hinterlegen.