# Touchpoint Webservice

# EMID Webservice

### 📝 Einleitung
Um zu einer **EMID** automatisiert die zugehörigen Touchpoint-Daten aus dem **easy.affiliate-System** auslesen zu können, stellt die easy Marketing GmbH eine Webservice-API zur Verfügung. Diese liefert zu einer EMID (= `_id` eines Dokuments der MongoDB-Collection `tracking.action`) den kompletten Touchpoint zurück: Zeitpunkt, Typ, Triplet (Kampagne/Projekt/Werbemittel), Weiterleitungs-URL sowie **alle GET-Parameter** des ursprünglichen Requests.

Typischer Use-Case: Zu einer Liste von aaaids/EMIDs die GET-Parameter (z. B. Partner-ID) ermitteln, ohne manuellen Einzel-Download über TripleA.

Jedem User stehen hierfür ein **Authentifizierungs-Token** und eine **Login_id** zur Verfügung, die über das Frontend abgerufen werden können.

* **User-ID:** Wo ist die User-ID hinterlegt? (Siehe Frontend-Profil)
* **Access-Token:** Wo ist der Access-Token hinterlegt? (Siehe API-Einstellungen)

---

### Endpunkte

| Zielgruppe | URL |
| :--- | :--- |
| **Admin** | `https://SUBDOMAIN.de/ws/V6/admin/JSON/Emids/Read` |
| **Advertiser** | `https://SUBDOMAIN.de/ws/V6/advertiser/JSON/Emids/Read` |

---

### Beispiele

#### Beispiel mit cURL
```bash
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-Network-ID: -1" \
  -H "X-Auth-Token: ADMIN_APIUSER_TOKEN" \
  -H "X-Auth-ID: ADMIN_APIUSER_LOGIN_ID" \
  -d '{ "emid": "6512a1f0c3e4b2a1d0f9e8a7" }' \
  https://DOMAIN/ws/V6/admin/JSON/Emids/Read
```
---
#### Codebeispiel
Mit der folgenden Methode kann zu einer EMID der Touchpoint ausgelesen werden. Ein Beispielaufruf sieht folgendermaßen aus:

##### Headers
| Variable | Wert / Bedeutung |
| :--- | :--- |
| **Content-Type** | `application/json` |
| **X-Network-ID** | `-1` |
| **X-Auth-Token** | `ADMIN_APIUSER_TOKEN` |
| **X-Auth-ID** | `ADMIN_APIUSER_LOGIN_ID` |

##### Body
```json
{
    "emid": "1314e1f0c3a4b2a1d0f3e5a7"
}
```
---
### Variablenerläuterung

#### Headers
| Variable | Bedeutung | Datentyp |
| :--- | :--- | :--- |
| **Content-Type** | Der Content-Type des Requests | String |
| **X-NETWORKID** | Hier wird die ID des Mandanten eingetragen. Wenn nur ein Mandant vorhanden ist oder mandantenübergreifend gearbeitet wird, muss der Wert “-1” eingetragen werden. | Integer |
| **X-AUTH-TOKEN** | Hier wird der API-Authentifizierungs-Token des Admin Nutzers hinterlegt. | String |
| **X-AUTH-ID** | Hier wird die ID des Admin Nutzers hinterlegt. | Integer |

---

#### Body

| Parameter | Beschreibung | Datentyp | Pflichtfeld |
| :----- | :--- | :--- | :--- |
| <span style="white-space:nowrap">**emid**</span> | Klick-/Action-ID (24-stellig hex) = `_id` des Dokuments in `tracking.action`. Alternativ als `id` übergebbar. | <span style="white-space:nowrap">String</span> | <span style="white-space:nowrap">✅ Ja</span> |

---

### Response

Die Antwort enthält das komplette Action-Dokument im Feld `data`.

##### Beispiel (Erfolg)
```json
{
    "data": {
        "_id": "6512a1f0c3e4b2a1d0f9e8a7",
        "sessionid": "…",
        "time": "2026-09-15 06:51:30",
        "type": "click",
        "triplet": {
            "campaign_id": 146,
            "project_id": 42,
            "admedia_id": 7
        },
        "iphash": "…",
        "deeplink": "https://ziel-shop.de/…",
        "Request": {
            "Get": {
                "partner_id": "12345",
                "subid": "…"
            },
            "Server": {
                "HTTP_REFERER": "https://…",
                "HTTP_USER_AGENT": "Mozilla/5.0 …"
            }
        }
    },
    "log": "no logmessage provided",
    "sessionId": null,
    "session": null
}
```

#### Felder im `data`-Objekt
| Feld | Beschreibung | Datentyp |
| :--- | :--- | :--- |
| <span style="white-space:nowrap">**_id**</span> | EMID (ObjectId des Action-Dokuments) | String |
| <span style="white-space:nowrap">**sessionid**</span> | Session-ID des Users | String |
| <span style="white-space:nowrap">**time**</span> | Zeitpunkt des Touchpoints | Datetime |
| <span style="white-space:nowrap">**type**</span> | Typ des Touchpoints (`click`, `view`, …) | String |
| <span style="white-space:nowrap">**triplet.campaign_id**</span> | Kampagnen-ID | Integer |
| <span style="white-space:nowrap">**triplet.project_id**</span> | Projekt-ID | Integer |
| <span style="white-space:nowrap">**triplet.admedia_id**</span> | Werbemittel-ID | Integer |
| <span style="white-space:nowrap">**iphash**</span> | Hash der IP-Adresse | String |
| <span style="white-space:nowrap">**deeplink**</span> | Weiterleitungs-/Ziel-URL | String |
| <span style="white-space:nowrap">**Request.Get**</span> | Alle GET-Parameter des Requests (z. B. Partner-ID) | Object |
| <span style="white-space:nowrap">**Request.Server**</span> | Server-Variablen des Requests (`HTTP_REFERER`, `HTTP_USER_AGENT`, …) | Object |

> **Hinweis:** Der Endpunkt liefert **IDs**, keine Klartext-Namen. Kampagnen-/Projekt-/Werbemittel-**Titel** müssen bei Bedarf separat aufgelöst werden.

---

### Fehler

Fehler werden als JSON mit `error: true` zurückgegeben.

| Typ | `message` (Beispiel) | Ursache |
| :--- | :--- | :--- |
| **Ws\NotFoundException** | `The requested entity 'Action <emid> not found' couldn't be found.` | EMID existiert nicht in `tracking.action` |
| **InvalidArgumentException** | `internal server error. Details: Invalid emid format` | `emid` ist keine gültige 24-stellige Hex-ObjectId |
| **InvalidArgumentException** | `Missing emid parameter` | `emid`/`id` fehlt im Body |
| **403** | – | Authentifizierung fehlgeschlagen (Token/Session ungültig) |

##### Beispiel (nicht gefunden)
```json
{
    "data": false,
    "error": true,
    "type": "Ws\\NotFoundException",
    "message": "The requested entity 'Action 6512a1f0c3e4b2a1d0f9e8a7 not found' couldn't be found.",
    "session": null,
    "sessionid": null
}
```

**\*) Hinweis:** Der Endpunkt verarbeitet **eine EMID pro Request**. Für eine Liste bitte pro EMID einen Request absetzen; die CSV-Aufbereitung erfolgt clientseitig aus der JSON-Antwort.