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 
 {
 "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 
 {
 "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: 
 {
 "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": []