# Publisher Webservice

# Verwaltung von Projekten über die V6 REST-API

## Einleitung
Die V6 REST-API bietet Admins die Möglichkeit, Projekte effizient zu verwalten. Mit dem `/Projects`-Endpoint können Projekte erstellt, ausgelesen, bearbeitet und gelöscht werden. Zusätzlich können Projekte anhand verschiedener Parameter gefiltert werden.

## Endpoint
**Für Admins:**
`https://SUBDOMAIN.de/ws/V6/admin/JSON/Projects`

---

## Parameter & Filter

### Erforderliche Parameter (bei POST und PUT)
| Parameter | Typ | Beschreibung |
| :--- | :--- | :--- |
| `title` | String | Titel des Projekts (Pflichtfeld) |
| `status` | Integer | Status des Projekts (Pflichtfeld) |
| `url` | String | URL des Projekts (Pflichtfeld) |

### Filteroptionen (bei GET)
Es kann nach allen Spalten der Tabelle `publisher.projects` gefiltert werden, z. B.:
* `id`
* `status`
* `publisher_id`
* `projecttype`
* `title`
* `url`
* `channel_id`
* `hidden`

**Beispiel für GET mit Filtern:**
```bash
curl -X GET -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" "https://SUBDOMAIN.de/ws/V6/admin/JSON/Projects?status=1&publisher_id=10"
```

---

## CRUD-Operationen

### GET: Abrufen von Projekten
Abrufen einer Liste von Projekten oder eines spezifischen Projekts anhand der `id`.

```bash
curl -X GET -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" "https://SUBDOMAIN.de/ws/V6/admin/JSON/Projects?id=5"
```

### POST: Erstellen eines neuen Projekts
```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 '{
  "title": "Neues Projekt",
  "status": 1,
  "url": "https://example.com"
}' "https://SUBDOMAIN.de/ws/V6/admin/JSON/Projects"
```

### PUT: Aktualisieren eines bestehenden Projekts
```bash
curl -X PUT -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 '{
  "id": 5,
  "title": "Geändertes Projekt",
  "status": 2,
  "url": "https://updated-example.com"
}' "https://SUBDOMAIN.de/ws/V6/admin/JSON/Projects"
```

### DELETE: Löschen eines Projekts
Löschen eines Projekts anhand der `id`.

```bash
curl -X DELETE -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" "https://SUBDOMAIN.de/ws/V6/admin/JSON/Projects?id=5"
```

---

## Antworten (Responses)

### Erfolgreiche Antwort
```json
{
  "id": 5,
  "status": 1,
  "publisher_id": 10,
  "projecttype": "page",
  "title": "Projektbeispiel",
  "description": "Beschreibung des Projekts",
  "url": "https://example.com",
  "channel_id": 2,
  "project_identifier_string": "abc123",
  "reach": "1000",
  "statistic_type": "internal",
  "external_sources_entity_id": "-1",
  "trackingtemplate": "template",
  "kpi_whitelist": "kpi1,kpi2",
  "hidden": false,
  "login_type": "pub",
  "exclude_from_salary": 0,
  "default_project": false,
  "insert_timestamp": "2025-01-27T12:00:00"
}
```

### Fehlerhafte Anfrage
```json
{
  "error": "Missing required field: title"
}
```

## Hinweise zur Fehlerbehandlung
* Bei fehlenden Pflichtfeldern (`title`, `status`, `url`) wird ein entsprechender Fehler zurückgegeben.
* Ungültige oder nicht vorhandene `id` bei GET, PUT oder DELETE resultieren in einer leeren Antwort oder einer Fehlermeldung.

# Publisher-Verwaltung über die V6 REST-API

# Publisher-Verwaltung über die V6 REST-API

## Authentifizierung

Erforderliche Header für alle Anfragen:

| Header | Beschreibung |
|---|---|
| `X-Network-ID` | Netzwerk-ID, z.B. `-1` für global |
| `X-Auth-Token` | API-User-Token |
| `X-Auth-ID` | API-User-Login-ID |
| `Content-Type` | `application/json` |

## Endpunkt

**Base URL:** `https://SUBDOMAIN.de/ws/V6/admin/REST/Publisher`

Es werden die üblichen HTTP-Methoden verwendet: `POST` zum Anlegen, `GET` zum Abrufen.

---

## CREATE Operation (POST)

**Methode & Pfad:** `POST /ws/V6/admin/REST/Publisher`

### Erforderliche Parameter

| Parameter | Typ | Beschreibung |
|---|---|---|
| `email` | String | Max. 255 Zeichen |
| `salutation` | String | z.B. `mr`/`mrs` |
| `prename` | String | Max. 255 Zeichen |
| `surname` | String | Max. 255 Zeichen |

### Optionale Parameter

`company`, `street`, `zip`, `city`, `telephone`, `country` (ISO 3166 ALPHA-3), `billing_sepa_owner`, `billing_sepa_iban`, `billing_sepa_bic`, `companytype` (z.B. `un`/`priv`), `language_interface` (Default: `DEU`), `billing_mode` (Default: `1`), `billing_media` (Default: `1`), `country_billing` (Default: `DEU`), `country_publisher` (Default: `DEU`), `billing_limit` (Default: `25`), `dialog_email` (Default: Wert von `email`)

> Für `salutation`, `companytype` und `country` gibt es keine feste Werteliste, die serverseitig erzwungen wird — bitte trotzdem an die üblichen Werte halten, damit nachgelagerte Auswertungen (Rechnungsstellung, Sprachwahl etc.) korrekt funktionieren.

### Response

```json
{
  "data": {
    "id": 123,
    "name": "Max Mustermann",
    "email": "max.mustermann@example.com"
  },
  "log": "no logmessage provided",
  "sessionId": "",
  "session": null
}
```

Die eigentlichen Daten stehen im `data`-Feld.

---

## READ Operation (GET)

**Methode & Pfad:** `GET /ws/V6/admin/REST/Publisher` bzw. `GET /ws/V6/admin/REST/Publisher/{id}`

### Einzelnen Publisher abrufen

`GET /ws/V6/admin/REST/Publisher/{id}` — `id` ist Teil des URL-Pfads, keine Query-Parameter.

### Liste abrufen (mit Filtern)

Filter werden als Query-Parameter im Format `params[feld]=wert` übergeben, z.B.:

```
GET /ws/V6/admin/REST/Publisher?params[status]=1
```

Filterbar sind sowohl die Basis-Felder des Publisher-Accounts (`id`, `status`, `type`) als auch alle Felder aus dem Registrierungsprozess (`email`, `prename`, `surname`, `company`, `street`, `zip`, `city`, `telephone`, `country`, Billing-Felder etc.). Mehrere Filter zusammen werden UND-verknüpft, z.B.:

```
GET /ws/V6/admin/REST/Publisher?params[status]=5&params[prename]=Max
```

Filter auf Registrierungsfelder sind exakte Treffer (kein Teilstring-/Wildcard-Match).

### Status-Werte

Bekannte Werte für `status`:

| Status | Bedeutung |
|---|---|
| `1` | Bestätigter, aktiver Publisher |
| `5` | Neu registriert, noch nicht freigegeben |

(Für eine vollständige Übersicht aller möglichen Status-Werte bitte im Admin-Interface unter der Publisher-Verwaltung nachsehen.)

### Response-Format der Liste

```json
{
  "data": {
    "123": {
      "type": "pub",
      "id": 123,
      "status": 5,
      "settings": {
        "email": "max.mustermann@example.com",
        "prename": "Max",
        "surname": "Mustermann",
        "company": "",
        "street": "Musterstraße 1",
        "zip": "12345",
        "city": "Musterstadt",
        "country": "DEU",
        "...": "weitere im Registrierungsprozess gespeicherte Felder"
      }
    }
  },
  "log": "no logmessage provided",
  "sessionId": "",
  "session": null
}
```

Das `settings`-Objekt enthält alle für den Publisher gespeicherten Registrierungsdaten — welche Felder konkret enthalten sind, hängt davon ab, was beim jeweiligen Publisher tatsächlich hinterlegt wurde (kein festes Schema).

> **Bekannte Einschränkung:** Informationen zur Werbefläche (Werbefläche/Werbeflächen-URL), die im Registrierungsprozess ebenfalls abgefragt werden, sind über diese API aktuell **nicht** abrufbar. Das wird als Erweiterung nachgezogen.

### Beispiele

- Einzelner Publisher: `GET /ws/V6/admin/REST/Publisher/123`
- Neu registrierte, noch nicht freigegebene Publisher: `GET /ws/V6/admin/REST/Publisher?params[status]=5`
- Publisher per E-Mail suchen: `GET /ws/V6/admin/REST/Publisher?params[email]=max.mustermann@example.com`

---

## Fehlerbehandlung

Fehler werden in folgendem Format zurückgegeben:

```json
{
  "error": true,
  "msg": "<Fehlerbeschreibung>",
  "type": "Ws\\Error",
  "data": []
}
```

Der HTTP-Statuscode ist bei Fehlern durchgängig `500`.

| Fehler | Beispiel-`msg` |
|---|---|
| Fehlendes Pflichtfeld bei CREATE | `internal server error. Details: Missing required field: email` |
| Publisher nicht gefunden | `internal server error. Details: Model not found.` |
| Filter ohne Treffer | kein Fehler — liefert `"data": []` |