Comment gérer la gestion des droits d'accès à votre service ? (3/3)

Cette série d’articles donne les bonnes pratiques concernant la gestion des droits d’accès à votre service au travers de ProAbono.

<< Introduction
< Chapitre précédent : Récupérer les droits

3 / Ajustez les droits et la consommation

La ressource Usage permet de récupérer les droits, mais également de les modifier.

Caution

On ne peut pas utiliser les usages 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": "feat-users",
    "ReferenceCustomer": "cust-123456",
    "Increment": 5,
    "DateStamp": "2025-03-29T19:33:50.65Z"
}

Modifications multiples

POST /v1/Usages
[
  {
    "ReferenceFeature": "feat-users",
    "ReferenceCustomer": "cust-123456",
    "QuantityCurrent": 12,
    "DateStamp": "2025-03-29T19:33:50.65Z"
  },
  {
    "ReferenceFeature": "feat-text-messages-sent",
    "ReferenceCustomer": "cust-123456",
    "Increment": 3,
    "DateStamp": "2025-03-29T19:33:50.65Z"
  }
]

Tip

Pour plus de détails sur la requête, consultez la documentation dédiée.

Notez que les champs sont différents selon le type de Caractéristique.

Le champ DateStamp

Chaque modification doit être horodatée grâce à le champ DateStamp. Il est nécessaire pour éviter des problèmes de calculs et de modifications concurrentes. Ce champ est la date à laquelle la modification sera prise en compte dans les calculs. Notez qu’il est impossible 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 responsable 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.