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 : Récupérer les droits par API
Chap 4. Ajuster les droits et la consommation par API
La ressource Usage permet de récupérer les droits, mais également de les modifier. Le nom de cette ressource vient de la facturation à l’Usage : elle permet de gérer non seulement des droits mais de la facturation à montant variable. Les Usages sont les valeurs des Caractéristiques dans un Abonnement.
Notez bien : on ne peut pas utiliser la ressource Usage pour modifier un abonnement non-démarré. Si votre objectif est de créer un abonnement sur-mesure, il faut utiliser la création d’abonnement avec surcharge (subscription override).
Modification unique
POST /v1/Usage
{
"ReferenceFeature": "f1",
"ReferenceCustomer": "cust-1",
"Increment": 5,
"DateStamp": "2016-03-29T19:33:50.65Z"
}
Modifications multiples
POST /v1/Usages
[
{
"ReferenceFeature": "f1",
"ReferenceCustomer": "cust-1",
"QuantityCurrent": 12,
"DateStamp": "2016-03-29T19:33:50.65Z"
},
{
"ReferenceFeature": "f2",
"ReferenceCustomer": "cust-1",
"Increment": 3,
"DateStamp": "2016-03-29T19:33:50.65Z"
}
]
Les champs et les réponses sont décrits dans la documentation API. Notez que les champs sont différents selon le type de Caractéristique.
Le champ DateStamp
Chaque modification doit être horodatée en utilisant le champs DateStamp. Il est nécessaire pour éviter des problèmes de calculs et de modifications concurrentes. Ce champs est la date à laquelle la modification sera prise en compte dans les calculs. Notez qu’il n’est pas possible de programmer une modification dans le futur.
Modification rejetée
Dans certains cas la modification sera rejetée. Nous recommandons vivement de gérer tous ces cas, afin d’avoir une intégration robuste et d’éviter que vos commerciaux ou votre responsables produit ne vous sollicite en urgence.
| Motif | Status HTTP | Code d’erreur |
|---|---|---|
| Le client n’a pas d’abonnement actif ou aucun de ses abonnements actifs ne contient cette Caractéristique | 403 | Error.Api.Usage.NoneMatching |
| La modification entraîne un paiement et le client n’a pas de moyen de paiement valide | 403 | Error.Customer.PaymentSettings.Missing |
| Le client a des impayés | 403 | Error.Customer.Billing.CappingReached |
Modification acceptée
Selon les paramètres de l’abonnement, une modification peut entraîner une augmentation du coût de l’abonnement et/ou un extra sur la prochaine facture. Si la modification est liée à une interaction du client dans votre service, il est vivement recommandé de demander une validation au client en lui indiquant l’impact sur sa prochaine facture. Consultez l’article ‘Achat Intégré‘ pour en savoir plus.