API - Customer Consentement

Owned by Stéphane Larzet (Unlicensed)
Last updated: 17 Oct 2019
3 min read

 Pour être informés de toutes les mises à jour concernant l’API v2 de SPREAD, inscrivez-vous ici : https://social-sb.com/z/newsletter-api-v1-v2

Méthodes disponibles


GET Customer Consents

Permet de gérer et récupérer l'historique des consentements des profils.

GET ⇒ social-sb.com/api/v2/customers-consents/{customer_id}

Paramètres obligatoires :

  • "customerId" : Identifiant SPREAD du customer

Paramètres complémentaires :

Aucun

Réponse :

Si GET ok alors

"customer": 
{
 "id": "123456",
 "consents": 
 [
 	{
 		"consentId": "9876",
 		"trackId": "1000",
 		"consentTechName": "NewsEmail",
 		"customerConsentCreatedAt": "2018-06-11 13:03:05",
 		"customerConsentStatus": "accepted",
		"customerConsentSource": "campaignParticipation",
		"customerConsentSourceId": "65745"
 	},
 	{
 		"consentId": "9875",
 		"trackId": "1001",
 		"consentTechName": "NewsSMS",
 		"customerConsentCreatedAt": "2018-06-11 13:03:38",
 		"customerConsentStatus": "refused",
		"customerConsentSource": "campaignParticipation",
		"customerConsentSourceId": "65746"
 	},
 	{
 		"consentId": "9874",
 		"trackId": "1002",
 		"consentTechName": "J'accepte d'être contacté occasionnellement par téléphone",
 		"customerConsentCreatedAt": "2018-06-11 13:03:44",
 		"customerConsentStatus": "unknown",
		"customerConsentSource": "campaignParticipation",
		"customerConsentSourceId": "65747"
 	}
 ]
},
"count": 3,
"nextPageUrl": "http://social-sb.com/api/v2/customers-consents/123456?startAt=3"

Sinon affichage d'un message d'erreur

Exemple d'appel PHP :

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://social-sb.com/api/v2/customers-consents/123456");
// Auth avec la clé publique et la clé privée (voir dans Paramétrage > Tracker)
curl_setopt($curl, CURLOPT_USERPWD, "clef_public:cle_privee");
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$curl_return = curl_exec($curl);
var_dump($curl_return);
curl_close($curl);

Faire une recherche précise :

Il est possible d'affiner la liste retournée en passant des paramètres GET.

Les paramètres d'affinage possibles :

  • "createdAfter" ⇒ seuls les consentements créés après la date passée en paramètre seront remontés
  • "createBefore" ⇒ seuls les consentements créés avant la date passée en paramètre seront remontés
  • "consentId" ⇒ seul le consentement ayant pour ID le paramètre sera remonté
  • "consentTechName" ⇒ seul le consentement ayant pour tech name le paramètre sera remonté
  • "customerConsentStatus" ⇒ seuls les consentements ayant le statut passé en paramètre seront remontés. Les valeurs possibles :
    • "accepted"
    • "refused"
    • "toBeConfirmed"
    • "unknown"
  • "customerConsentSource" ⇒ seuls les consentements venant d'une source comme celle passée en paramètre seront remontés. Les valeurs possibles :
    • "campaignParticipation"
    • "duplicationFromAPartnership"
    • "confirmationOfADoubleOptin"
    • "unsubscriptionUnifiedMessaging"
    • "manualImport"
    • "automaticImport"
    • "upstreamAPIGET"
    • "upstreamAPIGETJS"
    • "upstreamAPIPOST"
    • "unifiedMessaging"
    • "transactionalEmail"
    • "optinsMigration"
    • "manualUpdate"
    • "migrationOfCustomersToALegalBasis"
    • "prospectMigrationToALegalBasis"
    • "upstreamAPIv2POST"
    • "publicConsentManagementUserInterface

Les paramètres sur la pagination :

  • "startAt" ⇒ permet de commencer la liste des consentements à partir de l'occurence passée en paramètre
  • "maxResult" ⇒ permet de limiter le nombre de consentements remontés par pages (max 5000)


GET Customers Consent

Permet de récupérer tous les customers ayant répondu à un consentement.

GET ⇒ social-sb.com/api/v2/customers-consents

Paramètres obligatoires (à passer en paramètre GET) :

  • "consentId" : Identifiant SPREAD du consentement

OU

  • "consentTechName" : Le nom technique donné au consentement

OU

  • "trackId" : Identifiant SPREAD d'un consentement donné par un customer. Si le choix est de passer par la trackId, alors aucun paramètre d'affinage ne sera pris en compte.

Paramètres complémentaires :

Aucun

Réponse :

Si GET ok alors

"consent": {
 "id": "9874",
 "consentTechName": "J'accepte d'être contacté occasionnellement par téléphone",
 "customers": 
 [
 	{
 		"id": "123456",
 		"trackId": "1002",
 		"customerConsentCreatedAt": "2018-04-06 09:36:56",
 		"customerConsentStatus": "unknown",
		"customerConsentSource": "campaignParticipation",
		"customerConsentSourceId": "65745"
 	},
 	{
 		"id": "123457",
 		"trackId": "1003",
 		"customerConsentCreatedAt": "2018-04-09 09:06:25",
 		"customerConsentStatus": "refused",
		"customerConsentSource": "campaignParticipation",
		"customerConsentSourceId": "65746"
 	},
 	{
 		"id": "123458",
 		"trackId": "1004",
 		"customerConsentCreatedAt": "2018-04-09 09:50:33",
 		"customerConsentStatus": "toBeConfirmed",
		"customerConsentSource": "campaignParticipation",
		"customerConsentSourceId": "65747"
 	} 
 ]
},
"count": 4,
"nextPageUrl": "http:social-sb.com/api/v2/customers-consents?consentId=9874&startAt=4"

Sinon, affichage d'une erreur

Exemple d'appel PHP :

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://social-sb.com/api/v2/customers-consents?consentId=9874");
// Auth avec la clé publique et la clé privée (voir dans Paramétrage > Tracker)
curl_setopt($curl, CURLOPT_USERPWD, "clef_public:clef_privee");
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$curl_return = curl_exec($curl);
var_dump($curl_return);
curl_close($curl);

Faire une recherche précise :

Il est possible d'affiner la liste retournée en passant des paramètres GET.

Les paramètres d'affinage possibles :

  • "createdAfter" ⇒ seuls les consentements créés après la date passée en paramètre seront remontés
  • "createBefore" ⇒ seuls les consentements créés avant la date passée en paramètre seront remontés
  • "customerConsentStatus" ⇒ seuls les consentements ayant le statut passé en paramètre seront remontés. Les valeurs possibles :
    • "accepted"
    • "refused"
    • "toBeConfirmed"
    • "unknown"
  • "customerConsentSource" ⇒ seuls les consentements venant d'une source comme celle passée en paramètre seront remontés. Les valeurs possibles :
    • "campaignParticipation"
    • "duplicationFromAPartnership"
    • "confirmationOfADoubleOptin"
    • "unsubscriptionUnifiedMessaging"
    • "manualImport"
    • "automaticImport"
    • "upstreamAPIGET"
    • "upstreamAPIGETJS"
    • "upstreamAPIPOST"
    • "unifiedMessaging"
    • "transactionalEmail"
    • "optinsMigration"
    • "manualUpdate"
    • "migrationOfCustomersToALegalBasis"
    • "prospectMigrationToALegalBasis"
    • "upstreamAPIv2POST"
    • "publicConsentManagementUserInterface

Les paramètres sur la pagination :

  • "startAt" ⇒ permet de commencer la liste des consentements à partir de l'occurence passée en paramètre
  • "maxResult" ⇒ permet de limiter le nombre de consentements remontés par pages (max 5000)


POST Create Customer Consent

Permet de créer un consentement validé pour un profil et un consentement donnés.

POST ⇒ social-sb.com/api/v2/customers-consents/{customerId}

Paramètres obligatoires :

  • "customerId" : Identifiant SPREAD du profil (valeur à passer dans l'url)

  • "consentId" : Identifiant SPREAD du consentement (valeur à passer en POST)   OU   "consentTechName" : Identifiant SPREAD unique d'un consentement pour un site donné

  • "createdAt" : La date du consentement
  • "customerConsentStatus" : La valeur du consentement. Trois valeurs possibles : "accepted", "refused" ou "unknown". Cette dernière valeur ne fonctionne que s'il existe déjà une valeur pour ce consentement et ce customer.

Paramètres complémentaires :

  • "ip" : L'adresse IP du profil
  • "channelId" : L'identifiant unique SPREAD du canal sur lequel doit s'ajouter le consentement. Si aucun channel ID n'est fourni, le consentement s'ajoutera à tous les canaux du consentement.

Réponse :

Si POST ok alors

"consent": 
{
 "id": 9876,
 "techName": "NewsEmail",
 "customer": 
 {
 	"id": "123456",
	"trackId": "1000",
 	"customerConsentCreatedAt": "2O18-06-30 09:10:34",
 	"customerConsentStatus": "accepted"
 }
}

Sinon, affichage d'un message d'erreur

Exemple d'appel PHP :

$curl_post_data = array(
    'consent' => array(
        "id" => 9876,
		"techName" => "NewsEmail",
        "createdAt" => "2O18-06-30 09:10:34",
		"customerConsentStatus" => "accepted",
        "ip" => "1.1.1.1" # pas obligatoire
    )
);

$curl_post_data = json_encode($curl_post_data);

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, "https://social-sb.com/api/v2/customers-consents/123456");
curl_setopt($curl, CURLOPT_POSTREDIR, CURL_REDIR_POST_ALL);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
//// Auth avec la clé publique et la clé privée (voir dans Paramétrage > Tracker)
curl_setopt($curl, CURLOPT_USERPWD, "clef_public:clef_privee");
curl_setopt($curl, CURLOPT_POSTFIELDS, $curl_post_data );
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_VERBOSE, 1);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$curl_return = curl_exec($curl);
var_dump($curl_return);
curl_close($curl);