Schnittstellenbeschreibung: Consent Management

Das Modul enthält in der aktuellen Version die notwendige Datenstruktur, BPM-Prozesse und REST-Schnittstelle, um OptIn- und OptOut-Prozesse im CRM abzubilden. Die Umsetzung von Webservices zur Abbildung des Frontends auf Seiten des Empfängers (z.B. die Newsletter-Anmeldeseite zur Auswahl von Präferenzen) ist in dem Modul nicht enthalten und muss durch den Kunden oder durch einen CURSOR Partner (z.B. Evalanche) bereitgestellt werden.

Zur Unterstützung der Bereitstellung des Frontends werden mögliche praktische Anwendungsfälle in den folgenden Artikeln beschrieben:

Anwendungsfall	Beschreibung	Artikel
Abfrage per E-Mail	Einholung von OptIns via E-Mail von natürlichen Personen (GP/AP)	Single OptIn (SOI): Abfrage per E-Mail
Kundenportal	Pflege von Kontaktpräferenzen im Benutzerprofil eines Kundenportals o.ä.	Single OptIn (SOI): Kundenportal
Anmeldung auf Webseite	Einholung von OptIns über öffentlich zugängliche Anmeldungsformulare auf Webseiten o.ä.	Double OptIn (DOI): Anmeldung auf Website
Abmeldelink in Newsletter	Übertragung von OptOuts aus Abmeldeformularen o.ä.	OptOut: Abmeldelink in Newsletter

Die technische Übersicht der OptIn-Schnittstelle ist analog zu restlichen Endpunkten unter https://<host>:<port>/rest/doc/v1/services/optin beschrieben. Beispiele für die einzelnen Abfragen sind in den folgenden Abschnitten aufgeführt.

Endpunkte

Get Consent Data for Person

GET /v1/optins/{contactId}

Details

Full Path	https://{servername}/rest/api/optin/v1/optins/{contactId}
HTTP verb	GET
Description	Returns all consent data for a specific person.

Example Request

GET /v1/optins/example@example.com

CODE

none

Example Response

CODE

{
    "optIns": [
        {
            "pk": "1s9dh7g1hgd4117mOpIn",
            "type": "C0INFOTYPE_NEWSLETTER",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Zus_C0Approval"
        },
        {
            "pk": "9pmpq1hgd4117eOpIn",
            "type": "C0INFOTYPE_PRODUCTINFO",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Zus_C0Approval"
        },
        {
            "pk": "fvvvvvuevpqlk1hgd4117uOpIn",
            "type": "C0INFOTYPE_SURVEYS",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Abl_C0Approval"
        }
    ],
    "properties": {
        "contactId": "example@example.org",
        "pk": "pk123",
        "adBlocked": false
    }
}

Get Consent Options

GET /v1/optins/flows/{extRefNo}

Details

Full Path	https://{servername}/rest/api/optin/v1/optins/flows/{extRefNo}
HTTP verb	GET
Description	Returns all consent options within a specific process.
Notes	Only applicable for optin processes originating in the CRM.

Example Request

GET /v1/optins/flows/999c02ad-dff9-4540-9af8-b3c6e8ca6e63

CODE

none

Example Response

CODE

{
    "optIns": [
        {
            "pk": "1s9dh7g1hgd4117mOpIn",
            "type": "C0INFOTYPE_NEWSLETTER",
            "status": "C0OPTINSTATUS_REQUESTED",
            "extRefNo": "999c02ad-dff9-4540-9af8-b3c6e8ca6e63"
        },
        {
            "pk": "9pmpq1hgd4117eOpIn",
            "type": "C0INFOTYPE_PRODUCTINFO",
            "status": "C0OPTINSTATUS_REQUESTED",
            "extRefNo": "999c02ad-dff9-4540-9af8-b3c6e8ca6e63"
        },
        {
            "pk": "fvvvvvuevpqlk1hgd4117uOpIn",
            "type": "C0INFOTYPE_SURVEYS",
            "status": "C0OPTINSTATUS_REQUESTED",
            "extRefNo": "999c02ad-dff9-4540-9af8-b3c6e8ca6e63"
        }
    ],
    "properties": {
        "contactId": "example@example.com",
        "pk": "pk123",
        "adBlocked": false
    }
}

Update Consent Options

PUT /v1/optins/flows/{extRefNo}

Details

Full Path	https://{servername}/rest/api/optin/v1/optins/flows/{extRefNo}
HTTP verb	PUT
Description	Updates all consent options within a specific process.
Notes	Only applicable for optin processes originating in the CRM. Updating consent data with status `C0OPTINSTATUS_CURRENT` is not recommended due to documentation purposes. Please create consent data in this case instead.

Example Request

PUT /v1/optins/flows/999c02ad-dff9-4540-9af8-b3c6e8ca6e63

CODE

[
    {
        "type": "C0INFOTYPE_NEWSLETTER",
        "approval": "Zus_C0Approval"
    },
    {
        "type": "C0INFOTYPE_PRODUCTINFO",
        "approval": "Zus_C0Approval"      
    },
    {
        "type": "C0INFOTYPE_SURVEYS",
        "approval": "Abl_C0Approval"
    }
]

Example Response

CODE

{
    "extRefNo": "999c02ad-dff9-4540-9af8-b3c6e8ca6e63",
    "optIns": [
        {
            "pk": "1s9dh7g1hgd4117mOpIn",
            "type": "C0INFOTYPE_NEWSLETTER",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Zus_C0Approval",
            "extRefNo": "999c02ad-dff9-4540-9af8-b3c6e8ca6e63"
        },
        {
            "pk": "9pmpq1hgd4117eOpIn",
            "type": "C0INFOTYPE_PRODUCTINFO",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Zus_C0Approval",
            "extRefNo": "999c02ad-dff9-4540-9af8-b3c6e8ca6e63"
        },
        {
            "pk": "fvvvvvuevpqlk1hgd4117uOpIn",
            "type": "C0INFOTYPE_SURVEYS",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Abl_C0Approval",
            "extRefNo": "999c02ad-dff9-4540-9af8-b3c6e8ca6e63"
        }
    ],
    "result": {
        "status": "Success",
        "code": 200
    }
}

Create Consent Data

POST /v1/optins/optins/{contactId}

Details

Full Path	https://{servername}/rest/api/optin/v1/optins/{contactId}
HTTP verb	POST
Description	Creates new consent data for a specific person.
Notes	Depending on nature of request (single optin or double optin), status must be set accordingly. No status implies value `C0OPTINSTATUS_CURRENT`.

Example Request

POST /v1/optins/example@example.com

CODE

[
    {
        "type": "C0INFOTYPE_NEWSLETTER",
        "approval": "Zus_C0Approval"
    },
    {
        "type": "C0INFOTYPE_PRODUCTINFO",
        "approval": "Abl_C0Approval"
    },
    {
        "type": "C0INFOTYPE_SURVEYS",
        "approval": "Abl_C0Approval"
    }
]

Example Response

CODE

{
    "optIns": [
        {
            "pk": "1s9dh7g1hgd4117mOpIn",
            "type": "C0INFOTYPE_NEWSLETTER",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Zus_C0Approval"
        },
        {
            "pk": "9pmpq1hgd4117eOpIn",
            "type": "C0INFOTYPE_PRODUCTINFO",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Abl_C0Approval"
        },
        {
            "pk": "fvvvvvuevpqlk1hgd4117uOpIn",
            "type": "C0INFOTYPE_SURVEYS",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Abl_C0Approval"
        }
    ],
    "result": {
        "status": "Success",
        "code": 200
    }
}

Update Consent Data (DOI)

PUT /v1/optins/flows/{extRefNo}/?approval=true

Details

Full Path	https://{servername}/rest/api/optin/v1/optins/flows/{extRefNo}/?approval=true
HTTP verb	PUT
Description	Updates all consent data after person’s click on confirmation link.
Note	Only applicable in double optin context. In this context approval=true sets pending selection to current status. It does not change approval status itself.

Example Request

PUT /v1/optins/flows/999c02ad-dff9-4540-9af8-b3c6e8ca6e63/?approval=true

CODE

none

Example Response

CODE

{
    "extRefNo": "77c94095-075e-4e59-9467-a847610a0d01",
    "optIns": [
        {
            "pk": "fvvvvvubsppa71hnkqfcvmOpIn",
            "type": "C0INFOTYPE_PRODUCTINFO",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Abl_C0Approval",
            "extRefNo": "999c02ad-dff9-4540-9af8-b3c6e8ca6e63"
        },
        {
            "pk": "fvvvvvvc8fm741hnkqfd05OpIn",
            "type": "C0INFOTYPE_SURVEYS",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Abl_C0Approval",
            "extRefNo": "77c94095-075e-4e59-9467-a847610a0d01"
        },
        {
            "pk": "fvvvvvvhipkt01hnkqfcsrOpIn",
            "type": "C0INFOTYPE_NEWSLETTER",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Zus_C0Approval",
            "extRefNo": "77c94095-075e-4e59-9467-a847610a0d01"
        }
    ],
    "result": {
        "status": "OK",
        "code": 200
    }
}

POST Set OptOut for Person

POST /v1/optins/{contactId}/?approval=false

Details

Full Path	https://{servername}/rest/api/optin/v1/optins/{contactId}/?approval=false
HTTP verb	POST
Description	Sets optouts for a specific person.

Example Request

POST /v1/optins/example@example.com/?approval=false

CODE

[
    {
        "type": "C0INFOTYPE_SURVEYS"
    }
]

Example Response

CODE

{
    "extRefNo": "face04aa-6b28-4565-a7a8-ae308f52c3c9",
    "optIns": [
        {
            "pk": "q9v72f1hnnk8b7sOpIn",
            "type": "C0INFOTYPE_SURVEYS",
            "status": "C0OPTINSTATUS_CURRENT",
            "approval": "Abl_C0Approval",
            "extRefNo": "face04aa-6b28-4565-a7a8-ae308f52c3c9"
        }
    ],
    "result": {
        "status": "Success",
        "code": 200
}

Objekte

	Beschreibung	Objekte
OptInInfoDTO	Detailinformationen zu einem Consent-Datensatz	pk - Der PK des Opt-In-Datensatzes type - Der PK des Nachschlagefeld-Wertes status - Der PK des Nachschlagefeld-Wertes approval - (optional) Der PK des Nachschlagefeld-Wertes extRefNo - (optional) Die Referenz eines Opt-In-Flows
OptInOverviewDTO	Die Übersicht der Consent-Datensätze für eine Abfrage	properties - Eigenschaften des zugehörigen Kontaktes optIns - Die Liste der OptInInfoDTOs für die Anfrage relevanten Opt-In-Datensätze
OptInDTO	Eine Übersicht einer Anlage bzw. Modifikation für Consent-Datensätze	extRefNo - (optional) Die Referenz eines Opt-In-Flows optIns - Die Liste der OptInInfoDTOs für die Anfrage relevanten Opt-In-Datensätze result - Ein OptInResultDTO mit einer Zusammenfassung über den Ausgang der Operation
OptInResultDTO	Eine Zusammenfassung über den Ausgang einer Operation	status - Eine textliche Beschreibung über das Ergebnis code - Ein Code zur technischen Kennzeichnung des Ergebnisses

Fehlercodes

520 - Kein Kontakt für die Id gefunden
521 - Keine Datensätze für extRefNo gefunden
522 - Daten der Anfrage ungenügend
525 - Fehler beim Mailversand