Une séparation entre catalogue public et réception privée
Les données publiques décrivent le service, le pays, le tarif et la durée d’une offre. Elles ne contiennent ni numéro attribué ni code reçu. Les activations sont associées à un compte et à une commande, avec un suivi privé distinct.
Le répertoire des services et des pays est distinct des offres commerciales. Le contrat exige que le catalogue de l’API fournisse les prix et disponibilités faisant autorité pour une commande.
Catalogue et commande
Le contrat existant prévoit GET /catalog/products pour la liste d’offres et GET /catalog/products/:slug pour une fiche. Le backend fournit le prix faisant autorité, la durée et une disponibilité explicite ; un stock absent reste inconnu.
Une commande transmet l’identifiant du produit avec une clé d’idempotence. Le serveur vérifie prix et stock avant de réserver ou attribuer. Les actions sensibles ne sont pas déclenchées par une simple lecture de page.
États de réception
Le module distingue allocating, waiting, received, completed, cancelled, expired et failed. L’attribution peut être en cours sans numéro ; une attente ou réception réelle exige un numéro et une échéance du serveur.
Chaque message possède un identifiant stable, une date et son texte. Le code extrait peut être fourni par le backend lorsqu’il existe ; l’interface ne doit pas deviner un OTP. Le répertoire public ne contient aucun numéro attribué ni code privé.
Actions autorisées et actualisation
GET /activations et GET /activations/:id sont des lectures privées. POST /activations/:id/actions transmet cancel, finish ou resend avec une clé d’idempotence. Le backend annonce les actions autorisées pour l’état et les vérifie à nouveau avant de les exécuter.
Les lectures privées utilisent la session, la langue de l’interface et une politique de cache adaptée. L’intervalle de suivi vient du contrat ; l’échéance et l’état du serveur restent prioritaires sur un compteur affiché dans le navigateur.
Paiement, attribution et secrets fournisseur
La facture crypto fixe actif, réseau, montant, adresse et échéance. La confirmation du paiement et l’attribution du numéro sont deux événements distincts. Le backend doit gérer les échecs, les reprises et les demandes répétées sans double attribution.
Les clés fournisseur et secrets de paiement restent sur le serveur. L’API autorise chaque lecture par compte, définit la conservation des messages et ne publie pas les identifiants internes du fournisseur. Cette page décrit le contrat d’intégration ; elle n’annonce pas une API publique opérationnelle.
Repères des endpoints du contrat
| Méthode | Chemin | Rôle |
|---|---|---|
GET | /catalog/products | Catalogue public |
GET | /activations | Activations du compte |
GET | /activations/:id | Suivi privé de réception |
POST | /activations/:id/actions | Action autorisée |
Ces chemins décrivent le contrat du frontend, sans annoncer des endpoints de production publiés. Fournisseur, authentification et paiement restent à connecter.