Cette série d’articles donne les best practices pour intégrer ProAbono. Transmettez-la à votre équipe technique si vous voulez une intégration pérenne, qui vous permette de créer des offres et des abonnements à la volée sans assistance technique.
<< Chapitre 1
< Chapitre précédent : Mapper votre gestion de droits avec vos abonnements
Chap 4. Récupérer les droits par API
Les Caractéristiques
Les droits sont accordés aux Clients avec un Abonnement actif disposant des Caractéristiques associées. Ces droits sont configurés dans l’Offre d’abonnement ou directement dans l’Abonnement, si c’est un abonnement sur-mesure.
Exemples
Imaginons une caractéristique OnOff : ‘Accès à la section Premium’ :
- Un Abonnement à l’Offre ‘Premium’ contient la Caractéristique ‘Accès à la section Premium’
- Un Abonnement à l’Offre ‘Gratuite’ ne contient pas cette Caractéristique
- Un Abonnement à l’Offre ‘Pay-as-you-Go’ contient cette Caractéristique en option
Imaginons une caractéristique Limitation : ‘Nombre d’utilisateurs’ :
- Un Abonnement à l’Offre ‘Gratuite’ inclus 1 utilisateur
- Un Abonnement à l’Offre ‘Premium’ inclus 3 utilisateurs
- Un Abonnement à l’Offre ‘Pay-as-you-Go’ inclus 1 utilisateur et l’utilisateur supplémentaire coûte +X€/mois
Récupérer les droits
Les droits actuels d’un Client sont retournés par la ressource Usage de l’API Live. Le nom de cette ressource vient de la facturation à l’usage, car elle permet de gérer non seulement des droits mais de la facturation à montant variable. Les Usages sont les valeurs de chaque Caractéristique pour un Abonnement donné.
Cette ressource est conçue pour retourner les droits d’un client à tout moment par API. L’appel à cette ressource est optimisé pour la rapidité et supporte une charge colossale. Tant que l’utilisateur n’a pas souscrit, tant que l’abonnement n’est pas démarré, l’API ne retourne pas d’Usages.
Tous les droits pour un Client particulier
Utilisé typiquement pour récupérer les droits d’un utilisateur lorsqu’il se connecte.
GET /v1/Usages?ReferenceCustomer=cust-1
{
...
"Items": [
{
...
"IdSubscription": 10738,
"ReferenceSegment": "dev",
"ReferenceFeature": "f1",
"ReferenceCustomer": "cust-1",
"TypeFeature": "Limitation",
"QuantityIncluded": 3,
"QuantityCurrent": 4,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
},
{
...
"IdSubscription": 10738,
"ReferenceSegment": "dev",
"ReferenceFeature": "f2",
"ReferenceCustomer": "cust-1",
"TypeFeature": "Consumption",
"QuantityIncluded": 0,
"QuantityCurrent": 57,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
},
{
...
"IdSubscription": 10738,
"ReferenceSegment": "dev",
"ReferenceFeature": "f3",
"ReferenceCustomer": "cust-1",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
]
}
Tous les droits pour une Caractéristique particulière
Utilisé typiquement pour des traitement de masse sur les clients concernés.
GET /v1/Usages?ReferenceFeature=f1
{
"Page": 1,
"SizePage": 10,
"Count": 10,
"TotalItems": 158,
"Items": [
{
...
"IdSubscription": 4627,
"ReferenceSegment": "dev",
"ReferenceFeature": "f1",
"ReferenceCustomer": "cust-1",
"TypeFeature": "Limitation",
"QuantityIncluded": 1,
"QuantityCurrent": 1,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
},
...
]
}
Les droits pour un Client et une Caractéristique donnée
Utilisé typiquement pour vérifier les droits en temps-réel et l’Achat intégré.
GET /v1/Usage?ReferenceCustomer=cust-1&ReferenceFeature=f1
{
...
"IdSubscription": 4627,
"ReferenceSegment": "dev",
"ReferenceFeature": "f1",
"ReferenceCustomer": "cust-1",
"TypeFeature": "Limitation",
"QuantityIncluded": 1,
"QuantityCurrent": 1,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
Interprétation
La ressource Usage est générique, ce qui permet de s’en service pour tout type de droits, d’options et de règles de facturations. Il est essentiel de comprendre ce qui est retourné pour l’interpréter dans votre cas.
Chaque appel retourne le type de Caractéristique et les identifiants/référence permettant de connaître le Segment / Client / Caractéristique / Abonnement concerné.
Une période est également retournée (DatePeriodStart / DatePeriodEnd) : il s’agit de la période courante de l’abonnement concerné. Dans le cas des caractéristiques de type consommation, c’est ce qui permet d’indiquer au client à quel date son quota sera remis à zéro.
Pour une caractéristique OnOff
- IsIncluded (true|false) indique si la caractéristique est incluse sans frais dans l’abonnement.
- IsEnabled (true|false) indique si la caractéristique est active.
Notez qu’il est possible d’avoir une caractéristique incluse mais inactive (exemple : une option gratuite).
Dans la grande majorité des cas, IsEnabled est la seule valeur utile. Le prix d’activation n’est pas à considérer ici: consulter l’article Achat intégré si votre objectif est de permettre à vos clients d’activer une option payante sans passer par le Portail Client.
Pour les caractéristiques Limitation et Consumption
- QuantityIncluded est la quantité incluse sans frais dans l’abonnement.
- QuantityCurrent est la quantité actuelle.
Notez que QuantityIncluded peut être supérieur à QuantityCurrent. Par exemple : mon abonnement Premium me donne droit à 3 utilisateurs, que je peux ajouter à tout moment.
De même QuantityCurrent peut être supérieur à QuantityIncluded, si la quantité incluse a été dépassée. Par exemple : mon abonnement Premium me donne droit à 3 utilisateurs et me facture X€/mois par utilisateur supplémentaire.
Le tarif pour augmenter ou réduire les quantités n’est pas à considérer ici (le calcul peut être assez complexe). Consulter l’article Achat intégré si votre objectif est de permettre à vos clients d’augmenter une valeur sans passer par le Portail Client.
Pas de droits, pas de chocolat
Si le Client n’a pas de droits, c’est qu’il n’a pas d’abonnement actif. Cette situation peut se produire quand l’abonnement est terminé, résilié, quand le client a des impayés ou n’a plus de moyen de paiement valide.
Nous recommandons de lui lui couper l’accès à votre service et lui afficher le Portail Client en superposition (overlay). ProAbono lui proposera, selon les cas :
- De prendre un nouvel abonnement
- De mettre à jour ses moyens de paiement
- De régler ses impayés
- De télécharger ses anciennes factures (même après résiliation, il peut en avoir besoin)
Pas assez de droits
Le client peut avoir des droits, mais ils ne sont pas suffisants. Par exemple son abonnement ne lui donne pas accès à la section Premium, ou il veut ajouter un utilisateur mais il a déjà atteint son quota.
Dans le cadre d’une augmentation de quota, l’Achat intégré est la meilleure solution : le client achète des utilisateurs supplémentaires en un clic, directement depuis votre service.
Si l’achat intégré ne s’y prête pas, vous pouvez lui suggérer de passer sur une offre supérieure (upgrade), en le redirigeant vers la section ‘Abonnement’ de votre service.
Il est également possible de proposer un upgrade intégré, mais l’intégration est plus complexe. Consultez la documentation de l’upgrade pour en savoir plus.
Prochain chapitre : ajuster les droits et la consommation par API >