1. Accueil
  2. Documents
  3. Documentation développeur
  4. SDK XcooBee
  5. SDK PHP

SDK PHP

Téléchargement et source

https://github.com/XcooBee/xcoobee-php-sdk

Compositeur / Packagiste:

https://packagist.org/packages/xcoobee/xcoobee-sdk

Licence

Publié sous: Apache v 2.0

SDK

Le SDK PHP XcooBee est une fonctionnalité permettant d'abstraire les appels de niveau inférieur et d'implémenter des comportements standard.
L'équipe XcooBee fournit cela pour améliorer la vitesse de mise en œuvre et montrer les meilleures pratiques tout en interagissant avec XcooBee.

En règle générale, toutes les communications avec XcooBee sont cryptées sur le fil car aucun des systèmes XcooBee n'accepte le trafic brut. Toutes les données envoyées à XcooBee par vous et vice versa sont également signées à l'aide des protocoles PGP. Les paquets de données que vous recevrez sont signés avec votre clé publique et les paquets que vous envoyez sont signés avec votre clé privée.

Si vous avez besoin de générer de nouvelles clés PGP, vous pouvez vous connecter à votre compte XcooBee et accéder à la page des paramètres pour ce faire.

Les systèmes XcooBee fonctionnent dans le monde entier mais avec des connexions régionales. Le SDK vous connectera automatiquement à votre point de terminaison régional.

Une documentation API plus détaillée et complète est disponible sur notre site de documentation.

Limites d'appels

Si vous utilisez des comptes de développeur, sachez qu'il existe une limite d'appels. Cela représente normalement 120 appels par heure ou 600 appels par période de 24 heures.

Pour les comptes d'abonnement, vos limites d'appels sont déterminées par votre compte et votre contrat. Si vous atteignez vos limites d'appels, vous devrez contacter votre responsable de compte ou l'assistance pour les augmenter.

Une fois que vous avez dépassé vos limites d'appels, votre appel retournera à l'état 429 trop de demandes.

Journaux

Comme toutes les transactions standard, les appels d'API sont enregistrés sur le réseau XcooBee. Ils ont les mêmes contraintes de durée de vie (TTL).

Commencer

Point de terminaison de l'API

Pour utiliser le point de terminaison de l'API de test, veuillez définir une variable d'environnement XBEE_STATE = test.

exemple:






export XBEE_STATE = test

ou si vous êtes sous Windows:






set XBEE_STATE = test

en utilisant PHP:






putenv ('XBEE_STATE = test');

L'objet de configuration

L'objet config contient toutes les informations de configuration de base pour votre configuration et votre utilisation spécifiques. Il peut être transparent géré par le SDK ou spécifiquement transmis à chaque fonction.
Les informations de base dans la configuration sont:

  • votre clé API de XcooBee
  • votre api-secret de XcooBee
  • votre pgp-secret / mot de passe de vous ou de XcooBee
  • votre identifiant de campagne par défaut de XcooBee

Le SDK tentera de déterminer l'objet de configuration en fonction du schéma suivant:

1.) Utilisez l'objet de configuration passé dans la fonction.

2.) Utilisez les informations définies par l'appel setConfig.

3.) Vérifiez le système de fichiers pour le fichier de configuration (.xcoobee / config)

À propos du secret et du mot de passe PGP

Toutes les données PGP sont facultatives pour l'objet de configuration. Si vous ne le fournissez pas, le SDK ignorera les étapes de décryptage / cryptage. Vous devrez le faire en dehors du SDK et fournir ou traiter vous-même les données.

Actuellement tous événements auquel vous vous abonnez depuis le réseau XcooBee communiquera avec une couche supplémentaire de cryptage PGP. Vous devrez décrypter la charge utile à l'aide de votre clé privée PGP.

Si vous fournissez la clé privée PGP et sa phrase de passe au SDK, le SDK déchiffrera automatiquement la charge utile et fournira le contenu pour un traitement ultérieur.

setConfig (configModel)

le setConfig call est le mécanisme pour créer l'objet de configuration initial. Vous pouvez l'utiliser plusieurs fois. Chaque fois que vous appelez, vous remplacerez les données existantes. Les données une fois définies persisteront jusqu'à ce que la bibliothèque soit supprimée ou clearConfig est appelé.






apiKey => la clé api fournie par le compte XcooBee apiSecret => l'api-secret (téléchargé lors de la création de la clé api chez XcooBee) pgpSecret => la clé pgp-secret soit générée par XcooBee soit fournie par vous pgpPassword => le pgp -password fourni par vous campaignId => l'ID de campagne par défaut de votre campagne sur XcooBee pageSize => limite de pagination (enregistrements par page), par défaut basé sur le jeu d'enregistrements, le maximum possible est 100

clearConfig ()

Supprime toutes les données de configuration dans l'objet de configuration.

config sur le système de fichiers

XcooBee SDK recherchera dans le système de fichiers les informations de configuration en tant que dernier mécanisme. Vous devez vous assurer que l'accès aux fichiers de configuration n'est pas public et correctement sécurisé. Une fois trouvées, les informations sont mises en cache et aucune recherche supplémentaire n'est effectuée. Si vous modifiez votre configuration, vous devrez redémarrer le processus qui utilise le SDK pour récupérer les modifications.

Nous vous recommandons également d'examiner comment crypter le contenu de ces fichiers avec un cryptage spécifique au système d'exploitation pour une utilisation uniquement par le processus qui utilise le SDK XcooBee.

Les fichiers seront situés dans votre Accueil répertoire dans le .xcoobee sous-répertoire. Ainsi, le chemin complet de la configuration est:

/[homeedral/.xcoobee/config => les options de configuration

/[homeedral/.xcoobee/pgp.secret => la clé secrète pgp dans un fichier séparé

sous Windows, il se trouve à la racine de votre répertoire utilisateur

/Users/MyUserDir/.xcoobee/config => l'option de configuration

/Users/MyUserDir/.xcoobee/pgp.secret => la clé secrète pgp dans un fichier séparé

Le contenu initial du fichier de configuration est du texte brut, avec chaque option sur une ligne distincte.

fichier d'exemple:






apiKey = 8sihfsd89f7 apiSecret = 8937438hf campaignId = ifddb4cd9-d6ea-4005-9c7a-aeb104bc30be pgpPassword = quelque chose de secret pageSize = 10

options:






apiKey => l'api-key apiSecret => l'api-secret campaignId => l'ID de campagne par défaut pgpPassword => le mot de passe de votre clé pgp pageSize => limite de pagination

Réponses standard

Le système XcooBee a deux modes de réponse. Un, basé sur les appels d'API Web HTTP REST standard, et deux basés sur des webhooks asynchrones (HTTP POST) lorsque des événements se produisent.

Le paquet de réponse est structuré en enveloppe et détails. L'enveloppe contient des résultats opérationnels tels que Erreur ou Succès et horodatages. Le détail contient les données de retour associées à votre appel. XcooBee SDK renverra toujours une valeur, même s'il s'agit d'un objet d'erreur. Bref, il y a toujours un retour. L'absence de retour doit être traitée comme une erreur dans les réponses standard.

Les réponses Webhook (HTTP POST) sont basées sur des pratiques asynchrones. Le système XcooBee vous contactera et vous informera de l'événement. Celles-ci sont couvertes plus loin dans ce document.

Package de réussite

Structure d'objet pour la réponse:

  • temps
  • code (code de réponse 200-299)
  • request_id (la référence de demande associée)
  • résultat (objet de données)
    • l'objet de résultat est signé avec votre clé PGP publique s'il s'agit d'un un événement réponse.

Package d'erreur

Structure d'objet pour la réponse d'erreur:

  • temps
  • code (code de réponse: 300-500)
  • request_id (la référence de demande associée)
  • erreurs (tableau d'objets d'erreur avec données: message, détail)

Événements Webhook (HTTP POST)

Via le SDK, vous pouvez vous abonner à de nombreux événements disponibles sur le réseau XcooBee. Comme cela se produit à des moments différents, vous devrez être en mesure d'accepter la communication de XcooBee via HTTP POST vers un site cible disponible via Internet.

Comme alternative à un site public, vous pouvez utiliser le mécanisme d'interrogation d'événements comme décrit plus loin dans ce document pour recevoir cette communication.

Méthodologie

S'il y a une réponse retardée, l'appel sera accepté et la réponse retournée via la configuration d'événement HTTP POST. Votre système doit avoir un point de terminaison Web accessible par le système XcooBee pour les réponses aux événements. Un webhook n'est pas un point de terminaison REST (basé sur un verbe HTTP).

Le système de webhook utilise HTTPS PUBLIER appels pour vous envoyer des informations en réponse à un événement dans le traitement de XcooBee. Vous vous abonnez aux événements en appelant le Système-> addEventSubscription () méthode. Plus d'informations et d'exemples disponibles dans exemples / addEventSubscription.php Dans ce projet.

Les systèmes appelants doivent être conscients qu'il peut y avoir des retards et que les réponses peuvent être renvoyées dans un ordre différent de l'ordre d'appel.

Signature de livraison Webhook

Les charges utiles HTTP POST qui sont livrées au point de terminaison d'URL configuré de votre webhook contiendront plusieurs en-têtes spéciaux:

Entête La description
XBEE-ÉVÉNEMENT Type d'événement qui a déclenché la diffusion. Par exemple, consentement approuvé
XBEE-TRANS-ID Un GUID identifiant cet événement
SIGNATURE XBEE Le condensé hexadécimal HMAC du corps de la réponse *
XBEE-HANDLER Nom d'une fonction qui a été configurée comme gestionnaire pour le type d'événement actuel
  • le SIGNATURE XBEE l'en-tête sera envoyé si le webhook est configuré avec un secret. Le condensé hexadécimal HMAC est généré à l'aide de la fonction de hachage sha1 et du secret comme clé HMAC.

Implémentation de l'acceptation de Webhook

Vous pouvez implémenter votre propre accepteur de webhook et gérer toutes les informations qui vous sont transmises de cette manière. Github a un bon examen standard de ce processus. Exemples de webhook Github

Utiliser les outils SDK pour la gestion des événements

Le SDK propose une méthodologie d'acceptation des webhooks (HTTP POSTS) qui:

  • valide le contenu et les signatures
  • gère le cryptage / décryptage
  • gère les gestionnaires d'événements

Il s'agit d'un processus en plusieurs étapes qui est en fait simple dans la mise en œuvre finale. Il comporte trois parties:

a) déterminez comment vous souhaitez recevoir les événements

b) enregistrez votre abonnement à l'événement et vos paires de gestionnaires

c) traiter les événements entrants

une Déterminez comment recevoir les événements

Vous avez deux options pour recevoir des événements du réseau XcooBee. Publication HTTP d'événement (webhook) ou interrogation d'événement.

POST HTTP

Lorsque vous choisissez d'utiliser HTTP POST, vous devez fournir un système ou un point de terminaison accessible sur le Web avec lequel le réseau XcooBee peut communiquer directement. Cela se produit normalement sur le port 443 (HTTPS / TLS). Lorsqu'un événement se produit sur le réseau XcooBee, par exemple, un utilisateur modifie son accord de consentement, le réseau XcooBee déclenchera un événement sur ce point de terminaison.

Vous spécifiez votre URL cible lors de la configuration de votre campagne de consentement dans l'interface utilisateur XcooBee. Vous ne pouvez pas le modifier ou le définir via le SDK.

Sondage d'événement

Vous pouvez également interroger les événements de votre système à intervalles réguliers. Ceci est utile lorsque vous ne disposez pas d'un système accessible sur le Web ou que vous êtes en mode développement. Le SDK a une méthode de prise en charge getEvents qui vous permet de récupérer tous les événements auxquels vous vous êtes abonné et qui se sont produits au cours des 72 dernières heures.

À des fins de test, vous trouverez également une application monopage (SPA) dans le sondeur répertoire de ce projet. Il interrogera et resoumettra les événements pour vous aux points de terminaison du réseau interne.

b Enregistrez votre abonnement à l'événement et vos paires de gestionnaires

C'est l'une des parties les plus simples. Lorsque vous vous abonnez à des événements à l'aide du addEventSubscription () vous fournissez également la fonction PHP que vous souhaitez invoquer lorsqu'un tel événement est renvoyé comme argument de fonction. Voir la définition de la fonction pour plus d'informations.

c Traiter les événements entrants

Le moyen le plus simple de traiter un événement entrant est d'appeler le handleEvents ([événement]) méthode de la Système classe.

Normalement, cela est inclus dans le point de terminaison de votre site (page) qui reçoit le HTTP POST de XcooBee. Si vous effectuez une interrogation d'événement, vous pouvez transmettre le corps POST complet comme un événement à la fonction.

Ce handleEvents validera l'appel et appellera vos gestionnaires que vous avez déclarés à l'étape b

Point de terminaison standard (URL cible)

Si vous choisissez d'accepter les événements via webhook (HTTP POST), nous vous recommandons de créer un point de terminaison standard pour gérer toutes les communications. Pendant le traitement de cette page, vous pouvez alors appeler le handleEvents () méthode.

Le point de terminaison standard à créer serait / xbee / webhook

Si votre site fonctionne sur localhost l'URL cible du webhook entièrement formée serait http://localhost/xbee/webhook.

En fonction de votre infrastructure et de votre bibliothèque de syntaxe, cela peut également être:

  • /xbee/webhook.php
  • /xbee/webhook.jsp
  • /xbee/webhook.cfm
  • /xbee/webhook.aspx

Appels système

ping ([config])

Peut être appelé pour voir si la configuration actuelle se connectera au système XcooBee. Cela renverra une erreur si votre utilisateur d'API n'a pas de clé PGP publique sur son profil.

options:






config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès
  • état 400 si erreur

addEventSubscription (arrayOfEventAndHandlerPairs [, campaignId, config])

Vous pouvez enregistrer des abonnements à des hooks en appelant la fonction addEventSubscription et en fournissant l'événement (comme spécifié dans ce document) et les paires de gestionnaires eventname => gestionnaire.

Il n'y a pas d'abonnement aux événements génériques, cependant, vous pouvez ajouter plusieurs gestionnaires à la fois.

Exemple:






$xcoobee-> system-> addEventSubscription (['ConsentDeclined' => 'lostHandler'], 'ifddb4cd9-d6ea-4005-9c7a-aeb104bc30be', $config);

Cela vous abonnera au système XcooBee pour recevoir Consentement refusé événements pour le ifddb4cd9-d6ea-4005-9c7a-aeb104bc30be campagne et appelez votre gestionnaire nommé refuséHandler (événement) lorsqu'un tel événement se produit.

Toutes les données d'événement sont jointes au événements objet dans les appels de fonction.

Aucune réponse n'est attendue directement de l'un des gestionnaires d'événements, donc les retours sont void / null.

options:






arrayOfEventAndHandlerPairs => tableau avec les cartes d'événements et de gestionnaires campaignId => facultatif: l'ID de campagne à utiliser sinon par défaut config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès
  • état 400 si erreur

listEventSubscriptions ([campaignId, config])

lister les abonnements actuels.

options:






campaignId => facultatif: n'obtient que les abonnements pour l'id de campagne config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • les données contiendront l'ensemble de données des abonnements en cours: type, campagne, dernier
  • état 400 si erreur

deleteEventSubscription (arrayOfEventNames [, campaignId, config])

supprimer les abonnements existants.
Si vous ne fournissez pas d'ID de campagne, l'événement sera supprimé pour l'ID de campagne par défaut. Si l'abonnement n'existe pas, nous retournerons toujours le succès.

options:






arrayOfEventNames => tableau avec les noms d'événement à désabonner campaignId => facultatif: l'ID de campagne à utiliser sinon par défaut config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • les données contiendront le nombre d'abonnements supprimés
  • état 400 si erreur

triggerEvent (type [, config])

Déclenchez un événement de test sur le webhook de campagne configuré. La structure sera la même que celle d'un événement réel (avec charge utile chiffrée et signature HMAC).
Vous recevrez également ÉVÉNEMENT XBEE-TEST en-tête, qui indique que l'événement est test. Si le webhook de la campagne n'est pas configuré, vous recevrez une erreur.

options:






type => nom de l'événement config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • les données contiendront des données d'événement de test
  • état 400 si erreur

handleEvents (événements)

Cette fonction ne nécessite pas d'appel à l'API XcooBee. C'est plutôt le gestionnaire des appels que vous recevez de XcooBee via des webhooks comme indiqué précédemment.

Vous devez intégrer cette fonction dans le processeur d'itinéraire / de point final qui est appelé lorsque XcooBee vous renvoie l'un des événements pour lesquels vous vous êtes inscrit précédemment. Vous pouvez découvrir de quels événements il s'agit en appelant le listEventSubscriptions méthode.

La publication du webhook sera validée dans cette méthode et si la publication est valide, nous examinerons les événements enregistrés et invoquerons en outre la fonction d'espace réservé mappé pour chaque événement créé avec le addEventSubscription () méthode.

Facultativement, l'objet de données d'événements peut être transmis avec les données de l'en-tête HTTP et de l'appel POST.

Il existe deux modes de fonctionnement pour handleEvents ().

a) Sans paramètre de fonction événements:

Quand vous appelez handleEvents () sans un événements fonction, la méthode recherchera les données d'événement dans le flux webhook (HTTP POST). Vérifiez les signatures HTTP par rapport aux signatures attendues, puis traitez l'événement.

b) Avec paramètre de fonction événements:

Dans le cas où vous interrogez séparément les événements de XcooBee, vous pouvez appeler handleEvents (événements) directement avec les événements. Si vous fournissez spécifiquement les événements, la méthode ne recherchera pas les variables d'en-tête HTTP POST pour la vérification et traitera directement les événements comme prévu.

options:






events => optionnel: tableau d'objets avec des données de publication HTTP

réponse

  • pas de réponse, puisqu'il s'agit d'un appel interne aux gestionnaires d'événements mappés

getEvents ([config])

Dans les cas où vous ne pouvez pas utiliser les publications de webhook directes sur vos sites, par exemple si vous êtes en développement ou si votre système n'est pas accessible directement via Internet, vous pouvez extraire vos événements de XcooBee.

Si vous utilisez un accès basé sur l'extraction, assurez-vous qu'aucun point de terminaison n'est défini dans votre campagne car XcooBee tentera sinon de publier sur le point de terminaison et enregistrera une erreur. Sans point de terminaison de campagne, XcooBee enregistrera les événements auxquels vous êtes abonné et répondra à vos pull requests.

Vous avez 72 heures pour récupérer les événements enregistrés. Une fois extraits, les événements seront supprimés. Assurez-vous donc de les enregistrer si vous avez besoin de les rejouer.

Votre intervalle de traction ne doit pas être supérieur à 1 getEvents () appel par minute, sinon l'erreur HTTP 429 sera renvoyée. Nous recommandons toutes les 62 secondes pour éviter tout problème de minuterie.

options:






config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • les données contiendront un tableau d'événements depuis le dernier appel
  • état 400 si erreur

Administration du consentement Appels au consentement

getCampaignInfo ([campaignId, config])

obtenir des informations de base sur la campagne (configuration, types de données et options). Les informations ne renverront pas les utilisateurs enregistrés avec la campagne.

options:






campaignId => facultatif: l'ID de campagne à utiliser sinon par défaut config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • les données contiendront un objet de données de campagne
  • état 400 si erreur

listCampaigns ([config])

obtenir toutes les campagnes d'utilisateurs

options:






config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • les données contiendront un tableau d'objets de campagne
  • état 400 si erreur

getDataPackage (packagePointer [, config])

À METTRE EN ŒUVRE:

Lorsque les données sont hébergées pour vous chez XcooBee, vous pouvez demander le package de données à chaque fois que vous en avez besoin. Vous devrez fournir packagePointer. Cet appel ne répondra qu'à la source d'appel autorisée.

options:






packagePointer => le packagePointer pour les données que vous souhaitez recevoir config => optionnel: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • les données contiendront l'objet de données demandé
      Le SDK déchiffrera cela pour vous s'il a accès aux clés PGP sinon vous devez déchiffrer cet objet
  • état 400 si erreur

listConsents ([statusIds, config])

Requête pour la liste des consentements pour une campagne donnée. L'entreprise peut obtenir le consentement général pour tout consentement créé dans le cadre d'une campagne. Il s'agit d'un jeu d'enregistrements de plusieurs pages. Données renvoyées: consentId, date de création, date d'expiration, xcoobeeId

réponse possible / filtre pour l'état:

0 = en attente, 1 = actif, 2 = mise à jour, 3 = offre, 4 = annulé, 5 = expiré, 6 = rejeté

options:






statusIds => facultatif: tableau de nombres, l'un des statuts de consentement valides, s'il n'est pas spécifié, tout sera retourné config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra l'objet de données de consentement: consent_id, status_id, date_c, date_e, xcoobee_id
  • état 400 si erreur

getConsentData (consentId [, config])

Requête pour un consentement spécifique donné. L'entreprise peut obtenir une définition de consentement pour tout consentement qui a été créé. Les données ont normalement trois domaines: qui, quels types de données, quelles sont les utilisations, combien de temps.

options:






consentId => l'identifiant de consentement pour lequel récupérer les informations config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra l'objet de données de consentement: utilisateur, types de données, types de consentement, expiration
  • état 400 si erreur

getCookieConsent (xid [, campaignId, config])

Il s'agit d'un mécanisme de raccourci pour interroger le système XcooBee pour le consentement de l'utilisateur existant pour le type de consentement Suivi de site Web (1400), Suivi d'application Web (1410) pour des types de données d'utilisation spécifiques (cookie d'application (1600), cookie d'utilisation (1610) et cookie publicitaire (1620)). Nous récupérerons uniquement le consentement actif pour les cookies sur le site Web identifié dans l'identifiant de la campagne et nous indiquerons si l'utilisateur a accepté les cookies.

Remarque:

  • Votre site dans votre campagne doit correspondre à l'origine de l'appel car nous n'utilisons pas le cryptage PGP dans cet appel pour la vitesse.
  • L'utilisateur doit être connecté à XcooBee

Le retour est une liste CSV comme celle-ci:

  • application, utilisation, publicité

options:






xid => XcooBee Id de l'utilisateur à vérifier le consentement campaignId => facultatif: l'ID de campagne à utiliser sinon par défaut config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra le CSV de consentement des cookies du site Web: application, utilisation, publicité
  • état 400 si erreur

requestConsent (xid [, refId, campaignId, config])

Envoie le consentement ou le consentement et la demande de données à un utilisateur spécifique en utilisant les données de la campagne. La définition de la campagne détermine les données (uniquement le consentement ou le consentement + les données) que nous demanderons à l'utilisateur.

options:






xid => XcooBee Id de l'utilisateur à vérifier le consentement refId => facultatif: ID de référence généré par vous qui vous identifie cette demande. Max 64 caractères. Cela vous sera retourné dans la réponse à l'événement campaignId => facultatif: l'ID de campagne à utiliser sinon par défaut config => facultatif: l'objet de configuration

Lorsque l'utilisateur répond à la demande de consentement, un webhook se déclenche depuis XcooBee vers le point de terminaison identifié dans la campagne. Le SDK n'autorise pas la création ou la modification de points de terminaison. Veuillez utiliser l'interface graphique.

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra vrai
  • état 400 si erreur

confirmConsentChange (consentId [, config])

Utilisez cet appel pour confirmer que les données ont été modifiées dans les systèmes de l'entreprise en fonction du changement demandé par l'utilisateur.

options:






consentId => le consentement pour lequel les données doivent être confirmées config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra vrai
  • état 400 si erreur

confirmDataDelete (consentId [, config])

Envoyer par entreprise pour confirmer que les données ont été purgées des systèmes de l'entreprise

options:






consentId => le consentement pour lequel les données ont été supprimées config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra vrai
  • état 400 si erreur

setUserDataResponse (message, consentId [, requestRef, filename, config])

Les entreprises peuvent répondre aux données des utilisateurs demandées via cet appel. Des points de location standard seront déduits pour cela. L'appel enverra un message au centre de communication de l'utilisateur. Vous devez également envoyer un fichier avec les données de l'utilisateur afin de fermer la demande de données.

options:






message => le texte à envoyer à l'utilisateur en tant que données utilisateur consentId => le consentement pour lequel les données ont été supprimées requestRef => facultatif: identifiant unique de la demande de données, vous le recevrez sur l'événement `UserDataRequest` filename => facultatif : pointeur vers le fichier contenant les données de l'utilisateur config => optionnel: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra vrai
  • état 400 si erreur

Ce sont des événements renvoyés à votre point de terminaison dans le cadre de l'utilisateur travaillant avec son centre de consentement. Tous les points de terminaison sont déterminés dans chaque campagne de consentement.

Consentement approuvé

Se déclenche lorsqu'une demande de consentement est approuvée. L'objet de consentement est renvoyé.
Il contient:

  • référence de consentement
  • Types de données
  • types de consentement
  • expiration

Consentement refusé

Se déclenche lorsqu'une demande de consentement est refusée. Vous devez supprimer les données utilisateur et envoyer une confirmation XcooBee via confirmDataDelete ().
Les données soumises contiennent:

  • référence de consentement

Consentement modifié

Se déclenche lorsque le consentement est modifié. Un objet de consentement standard est renvoyé.
Il contient:

  • référence de consentement
  • Types de données
  • types de consentement
  • expiration

ConsentementNearExpiration

Se déclenche lorsqu'un consentement actif est sur le point d'expirer (dans les 30 jours). Ce n'est pas exactement 30 jours car les processus du système XcooBee peuvent pousser légèrement cela. Vous devez prévoir une demande de renouvellement de consentement si vous souhaitez utiliser les données utilisateur plus longtemps.
Il contient:

  • référence de consentement
  • expiration

Consentement expiré

Se déclenche lorsque le consentement a expiré. Vous devez supprimer les données utilisateur et envoyer une confirmation XcooBee via confirmDataDelete ().
Il contient:

  • référence de consentement

UserDataRequest

Se déclenche lorsque l'utilisateur demande d'extraire ses données actuelles de vos systèmes. C'est pour répondre à la portabilité des données du RGPD. Vous devez créer un extrait de données et l'envoyer à la boîte XcooBee de l'utilisateur. Vous pouvez le faire en embauchant le réponse-données-xcoobee bee avec la référence GUID de la demande.
Il contient:

  • référence de consentement
  • xcoobeeId

UserMessage

Se déclenche lorsque l'utilisateur vous envoie un message concernant une demande de consentement.
Votre campagne peut activer / désactiver cette fonctionnalité dans le options de campagne. Vous pouvez y répondre en utilisant un sendUserMessage () appel.
Il contient:

  • référence de consentement
  • xcoobeeId
  • message

Administration du consentement Appels de données

Cette section couvre les événements qui sont utilisés dans le cadre de la collecte de données et du consentement en même temps.

Événements de données (webhooks)

Événements soumis par XooBee à votre système.

Données approuvées

Se déclenche lorsque le consentement est donné et que les données ont été fournies par l'utilisateur. Un objet de consentement standard est renvoyé.
Il contient:

  • référence de consentement
  • types de données avec des données
  • types de consentement
  • expiration

Données refusées

Se déclenche lorsque l'utilisateur a refusé de fournir des données et son consentement. Vous devez supprimer les données utilisateur et envoyer une confirmation XcooBee via confirmDataDelete ().
Il contient:

  • référence de consentement

Données modifiées

Se déclenche lorsque les données ou le consentement sont modifiés. Un objet de consentement standard est renvoyé.
Il contient:

  • référence de consentement
  • types de données avec des données
  • types de consentement
  • expiration

DataNearExpiration

Se déclenche lorsqu'un consentement actif est sur le point d'expirer (dans les 30 jours).
Ce n'est pas exactement 30 jours car les processus du système XcooBee peuvent pousser légèrement cela.
Vous devez prévoir une demande de renouvellement de consentement si vous souhaitez utiliser les données utilisateur plus longtemps.
Il contient:

  • référence de consentement
  • expiration

Données expirées

Se déclenche lorsque les données ont expiré. Vous devez supprimer les données utilisateur et envoyer une confirmation XcooBee via confirmDataDelete ().
Il contient:

  • référence de consentement

UserDataRequest

Se déclenche lorsque l'utilisateur demande d'extraire ses données actuelles de vos systèmes.
C'est pour répondre à la portabilité des données du RGPD.
Vous devez créer un extrait de données et l'envoyer à la boîte XcooBee de l'utilisateur.
Vous pouvez le faire en embauchant le réponse-données-xcoobee bee avec la référence GUID de la demande.
Il contient:

  • référence de consentement
  • xcoobeeId

UserMessage

Se déclenche lorsque l'utilisateur vous envoie un message concernant une demande de consentement.
Votre campagne peut activer / désactiver cette fonctionnalité dans le options de campagne. Vous pouvez y répondre en utilisant le sendUserMessage () une fonction.
Il contient:

  • référence de consentement
  • xcoobeeId
  • message

Message

sendUserMessage (message, consentid, [violationid], [config])

Cette fonction vous permet d'envoyer un message aux utilisateurs. Vous pouvez communiquer les problèmes concernant la violation, le consentement et les données de cette manière. Il créera un fil de discussion pour l'utilisateur et pour vous et y ajoutera ce message.

options:






message => le texte à envoyer à l'utilisateur en tant que données utilisateur, peut être au format html. Max 2000 caractères consentId => l'identifiant de consentement qui déclenche la notification violationId => facultatif: violation liée, l'utilisateur recevra un message avec les actions proposées déclarées dans une violation config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra vrai
  • état 400 si erreur

getConversations ([config])

Cette fonction vous permet d'obtenir une liste des discussions avec les utilisateurs concernant les violations, les consentements, etc.

options:






config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra vrai
  • état 400 si erreur

getConversation (userId [, config])

Cette fonction vous permet d'avoir une discussion complète avec l'utilisateur sélectionné.

options:






userId => l'ID utilisateur config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra vrai
  • état 400 si erreur

Violation

L'API de violation est le principal moyen d'interagir avec les utilisateurs pendant la violation. La déclaration de violation et les notifications initiales se produisent dans l'interface utilisateur.

Événements de violation (webhooks)

Brèche présentée

Se déclenche lorsque l'utilisateur a ouvert un avis de violation.
Il contient:

  • référence de consentement

BreachBeeUtilisé

Se déclenche lorsque l'utilisateur a utilisé une abeille que vous avez identifiée dans l'avis de violation.
Il contient:

  • référence de consentement
  • référence abeille

UserMessage

Se déclenche lorsque l'utilisateur vous envoie un message concernant une demande de consentement.
Votre campagne peut activer / désactiver cette fonctionnalité dans le options de campagne. Vous pouvez y répondre en utilisant le sendUserMessage () une fonction.
Il contient:

  • référence de consentement
  • xcoobeeId
  • message

API Bee

L'API Bee est la principale interface pour embaucher des abeilles. La plupart du temps, cela se fera en deux étapes. Dans la première étape, vous téléchargez vos fichiers à traiter par les abeilles en utilisant télécharger des fichiers() appel. Si vous n'avez pas spécifié de point de terminaison de boîte d'envoi, vous devrez également appeler le décollage() fonction avec les paramètres de traitement de l'abeille.

La réponse immédiate ne couvrira que les problèmes avec les fichiers de la première abeille. Si vous souhaitez être informé de l'avancement du traitement, vous devrez vous abonner aux événements.

listBees (searchText [, config])

Cette fonction vous aidera à rechercher parmi les abeilles dans le système que votre compte peut embaucher. Ceci est une interface de recherche par mot-clé simple.

options:






searchtext => chaîne de mots-clés à rechercher dans le nom ou le libellé du système d'abeille dans la langue de votre compte config => optionnel: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra les données d'abeille de base: nom du système d'abeille, étiquette d'abeille, coût de l'abeille, type de coût
  • état 400 si erreur

uploadFiles (fichiers [, endpoint, config])

Vous utilisez la fonction uploadFiles pour télécharger des fichiers de votre serveur vers XcooBee. Vous pouvez télécharger plusieurs fichiers et vous pouvez éventuellement fournir un point de terminaison de boîte d'envoi. Si vous disposez d'un point de terminaison de boîte d'envoi, vous n'avez pas besoin d'appeler le décollage fonction car le point final spécifie déjà tous les paramètres de traitement. Si votre abonnement le permet, vous pouvez configurer les points de terminaison de la boîte d'envoi dans l'interface utilisateur XcooBee.

options:






files => tableau de chaînes avec des pointeurs de fichier vers le magasin de fichiers, par exemple: `c: \ temp \ mypic.jpg` ou` / home / mypic.jpg` endpoint => facultatif: le point de terminaison de la boîte d'envoi, par exemple `marketing data` ou `POS drop point` config => optionnel: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra vrai
  • état 400 si erreur

takeOff (abeilles, options [, abonnements, config])

Vous l'utilisez normalement comme appel de suivi pour télécharger des fichiers(). Cela lancera votre traitement. Vous spécifiez la ou les abeilles que vous souhaitez embaucher et le paramètre qui est nécessaire pour que l'abeille travaille sur vos fichiers. Si vous souhaitez être tenu à jour, vous pouvez fournir des abonnements. Veuillez noter que les abonnements déduiront des points de votre solde et entraîneront des erreurs lorsque votre solde est insuffisant.

Il s'agit de l'appel de fonction le plus complexe de l'API Bee et comporte plusieurs options et parties.

a) paramètres
b) abonnements
c) événements d'abonnement

options:






bees => tableau de noms de système d'abeilles (par exemple "xcoobee_digital_signature_detection") comme clé et leurs paramètres comme valeur options => options générales subscriptions => facultatif: le tableau des abonnements. Spécifie les abonnements config => facultatif: le tableau de configuration

une Paramètres

Les paramètres peuvent être spécifiques aux abeilles ou s'appliquer à l'ensemble du travail.

exemple de paramètres d'abeille spécifiques:






$bees ['xcoobee_testbee'] = ['hauteur' => 599, 'largeur' => 1200,];

Les paramètres généraux du poste à utiliser pour l'embauche sont spécifiés avec le processus préfixe comprenant les destinations (destinataires) auxquelles vous souhaitez envoyer la sortie du traitement.

exemple de paramètres généraux de processus:






$options ['process'] ['userReference'] = 'myownreference'; $options ['process'] ['destinations'] = ['email @ null mysite.com', '~ jonny']; $options ['process'] ['fileNames] = [' filename.png '];

Les paramètres d'abeille spécifiés nécessitent le préfixe de nom d'abeille. Si le nom de l'abeille est xcoobee_testbee et cela nécessite deux paramètres la taille et largeur vous devrez ensuite les ajouter dans un tableau associatif à l'intérieur du tableau de paramètres avec une clé de nom d'abeille.

b Abonnements

Les abonnements peuvent être associés au processus global. Vous devrez spécifier un cible, une événements et un gestionnaire argument au minimum. le cible le point final doit être accessible par le système XcooBee via POST HTTP / S. le événements détermine les événements auxquels vous vous abonnez.

Ainsi, les trois clés pour chaque abonnement sont:

  • target => chaîne avec l'URL du point de terminaison cible
  • events => tableau avec les événements du cycle de vie auxquels s'abonner
  • handler => obligatoire: la fonction PHP qui sera appelée lorsque nous aurons des événements API bee

La signature HMAC prendra votre identifiant XcooBee comme clé secrète partagée et utilisera la clé publique PGP pour chiffrer la charge utile. Sans cela, vous utilisez toujours le cryptage SSL pour le transfert.

Pour vous abonner aux événements de processus globaux, le mot-clé processus doit être utilisé. Les détails de l'abonnement doivent y être attachés en tant que sous-clés.

N'oubliez pas que les abonnements déduisent des points de votre solde même s'ils échouent, veuillez donc valider que les points de terminaison que vous spécifiez dans cible sont valides.

Exemple d'abonnement sur le processus global.

exemple d'abonnements:






Abonnements aux processus: $subscriptions ['target'] = "https://monsite.com/beehire/notification/" $subscriptions ['events'] = ["error", "success", "livrer", "present", "download "," delete "," reroute "] $subscriptions ['handler] =" myBeeEventHandler "

c Événements d'abonnement

Le système d'événements pour les abeilles utilise des événements de niveau processus.

Événements de niveau processus

  • Erreur
    • Une erreur s'est produite lors du traitement de la transaction. S'il y a plusieurs erreurs, chacune d'elles est envoyée par courrier séparé.
    • Type d'événement envoyé dans l'en-tête POST - ProcessError
  • Succès
    • La transaction globale s'est terminée avec succès
    • Type d'événement envoyé dans l'en-tête POST - Processus Succès
  • livrer
    • Y a-t-il eu transfert d'un fichier, le fichier a été remis dans la boîte de réception du destinataire
    • Type d'événement envoyé dans l'en-tête POST - ProcessFileDelivered
  • présent
    • S'il y a eu transfert d'un fichier, le fichier a été vu par l'utilisateur
    • Type d'événement envoyé dans l'en-tête POST - ProcessFilePresented
  • Télécharger
    • S'il y a eu transfert d'un fichier et que l'utilisateur a téléchargé le fichier
    • Type d'événement envoyé dans l'en-tête POST - ProcessFileTéléchargé
  • supprimer
    • Cet événement se produit lorsque l'utilisateur supprime le fichier
    • Type d'événement envoyé dans l'en-tête POST - ProcessFileDeleted
  • dérouter
    • Lorsque l'utilisateur a des règles de boîte de réception automatisées et que le document a été envoyé à un autre endroit, un événement de réacheminement est déclenché
    • Type d'événement envoyé dans l'en-tête POST - ProcessReroute

Exemples de charge utile d'événement:

  • exemple d'événement de réussite:





{"date": "2017-12-04T16: 50: 40.698Z", "file": "myImage.jpg", "userReference": "88jenr", "destinataire": "~ john873", "event": " success "," eventLevel ":" bee "," source ":" Block4-post "," beeName ":" xcoobee_image_resizer "," transactionName ":" 9SDd8ccb "}
  • exemple d'événement d'erreur:





{"date": "2017-10-24T15: 22: 39.209Z", "file": "myhome2.jpg", "userReference": "no-reference", "receiver": "no-receiver", "event ":" error "," eventLevel ":" bee "," source ":" Block4-post "," beeName ":" xcoobee_image_converter "," message ":" Timeout error on container process "," transactionName ":" 0P4bbee "}

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra vrai
  • état 400 si erreur

API Inbox

L'API de la boîte de réception régit l'accès à votre boîte de réception. Vous pouvez répertorier, télécharger et supprimer des éléments de votre boîte de réception.

listInbox ([config])

Cette méthode présentera une liste paginée des éléments de la boîte de réception que vous pouvez télécharger. La liste sera pour l'utilisateur connecté à votre clé API. Vous ne pouvez consulter la boîte de réception d'aucun autre utilisateur à l'aide de cette méthode. Vous pouvez retourner jusqu'à 100 articles en un seul appel.
L'appel de cette méthode plus d'une fois par minute entraînera une erreur HTTP 429 (dépassant les limites d'appels).

Vous obtiendrez les points de données suivants:

  • ID du message
  • expéditeur
  • nom de fichier
  • fileSize (en octets)
  • date de réception
  • date d'expiration
  • downloadDate

Les éléments de la boîte de réception sont répertoriés par ordre d'arrivée, les éléments les plus récents en premier.

options:






config => facultatif: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra la liste des éléments de la boîte de réception dans le tableau: messageId, sender, fileName, fileSize, receptionDate, expirationDate, downloadDate
  • état 400 si erreur

getInboxItem (messageId [, config])

Cette méthode renverra un fichier et des balises méta de fichier. Lors du premier téléchargement, le downloadDate pour l'élément sera rempli.

options:






messageId => le message Id du fichier à télécharger config => optionnel: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra le fichier et l'objet file_meta (userRef, fileType, fileTags)
  • état 400 si erreur

deleteInboxItem (messageId [, config])

Cette méthode supprimera un fichier correspondant à votre identifiant de message. Si le fichier n'existe pas, une erreur sera renvoyée.

options:






messageId => le message Id du fichier à supprimer config => optionnel: l'objet de configuration

réponse

objet de réponse JSON standard

  • statut 200 en cas de succès:
    • l'objet de données contiendra vrai
  • état 400 si erreur

API utilisateur

getUserPublicKey (xid [, config])

Récupère la clé PGP publique d'un utilisateur telle que publiée sur son profil public. Si l'utilisateur a choisi de le masquer ou si l'utilisateur n'est pas connu, il renvoie nul.

exemple:






getUserPublicKey ('~ XcooBeeId');

options:






xid => XcooBee Id de l'utilisateur pour obtenir sa clé PGP publique config => optionnel: l'objet de configuration

réponse

public PGP ou nul

Dépannage

Erreur 401

Certains appels SDK nécessitent des origines autorisées.

Vous pouvez recevoir 401 réponses d'erreur de XcooBee si votre appel API provient d'un domaine ou d'une adresse IP non autorisés. Veuillez vous assurer que vous avez enregistré votre domaine dans votre campagne XcooBee URL de rappel option.

Erreur 429

Une fois que vous avez dépassé vos limites d'appels, votre appel retournera à l'état 429 trop de demandes. Veuillez mettre à jour votre abonnement ou contacter l'assistance.

Cet article vous a-t-il été utile ? Oui Non

Comment pouvons-nous aider ?