Découvrir les Factures
Paiement de factures
Découvrir les Factures
Démarrer une découverte de factures pour un compte partenaire
POST
Découvrir les Factures
Vue d’Ensemble
Demande à un facturier ce qu’un compte donné doit actuellement. La réponse est untransactionId que vous interrogez ensuite ; lorsque la transaction atteint READY, son tableau bills[] contient tout ce qui est payable.
La découverte ne déplace pas d’argent et ne vous engage à rien. Vous pouvez l’exécuter en toute sécurité avant de montrer à un client ce qu’il doit.
Corps de la Requête
string
requis
Le facturier à interroger. Exactement l’une des valeurs
ADE, SONELGAZ, SEAAL, AADL, Algérie Télécom — accents compris.Consultez d’abord Lister les Partenaires ; un partenaire UNAVAILABLE répond 503 PARTNER_UNAVAILABLE.object
requis
Le compte à rechercher. Il doit porter exactement un identifiant — voir Identifiants de compte ci-dessous. Zéro identifiant, ou deux, est rejeté.
string
requis
Votre propre référence pour cette découverte. Maximum 100 caractères, et unique parmi vos transactions en cours pour ce partenaire.Réutiliser une
ref répond 403 DUPLICATED_REF. C’est aussi ainsi que vous récupérez une réponse perdue — voir Obtenir une Transaction par Référence.Identifiants de compte
Envoyez le champ qui appartient au partenaire que vous interrogez. C’est également le champ que l’API retourne dansaccount sur chaque transaction pour ce partenaire.
Deux formes plus riches sont également acceptées lorsque le facturier a besoin de plus d’un seul numéro pour identifier une facture :
sonelgaz — forme facture
sonelgaz — forme facture
Les trois champs sont requis ensemble.
invoice_number jusqu’à 20 caractères, amount_without_stamp jusqu’à 20, ebb_key jusqu’à 30.ade — forme facture
ade — forme facture
Les quatre champs sont requis ensemble.
sub_id exactement 12 caractères, period au format MM/YYYY, amount jusqu’à 20 caractères, pay_key exactement 7 caractères.electronic_payment_key — clé de 25 caractères
electronic_payment_key — clé de 25 caractères
Acceptée pour ADE et SEAAL comme alternative à
reference. Elle doit faire exactement 25 caractères.Réponse
boolean
requis
true lorsque la découverte a été acceptée.object
requis
object
requis
string
requis
Identifiant de corrélation, également envoyé dans l’en-tête de réponse
X-Request-Id.Exemples
Réponse de Succès
status soit READY, puis lisez bills[] :
Réponses d’Erreur
400 — Erreur de validation
400 — Erreur de validation
Le corps de la requête ne correspondait pas au schéma.
details liste tous les champs en échec, pas seulement le premier. Causes courantes : une ref manquante, un partner qui ne fait pas partie des cinq valeurs, un account sans identifiant ou avec deux, une electronic_payment_key qui ne fait pas exactement 25 caractères, un phoneNumber qui n’est pas une ligne fixe algérienne valide.Que faire : corrigez la requête. La réessayer telle quelle retourne la même erreur.400 — Compte invalide
400 — Compte invalide
L’identifiant est structurellement acceptable mais inutilisable pour ce partenaire.Que faire : demandez au client de vérifier le numéro inscrit sur sa facture. C’est l’erreur à lui présenter ;
ERR_VALIDATION est destinée à vos journaux.401 — Jeton d'accès manquant ou invalide
401 — Jeton d'accès manquant ou invalide
La clé était absente ou a été rejetée.Un en-tête manquant retourne
MISSING_ACCESS_TOKEN à la place, avec le même statut HTTP.Que faire : vérifiez la clé avec Valider la Clé API.403 — Référence en double
403 — Référence en double
Vous avez déjà utilisé cette Que faire : ne réessayez pas aveuglément avec une nouvelle
ref pour ce partenaire.ref — vous démarreriez une deuxième découverte pour le même compte. Retrouvez la découverte existante avec Obtenir une Transaction par Référence et poursuivez à partir de son état.409 — Facture déjà payée
409 — Facture déjà payée
Ce compte a déjà été payé récemment, une nouvelle découverte est donc refusée.Que faire : c’est une protection contre le double paiement, pas un échec. Retrouvez la transaction réussie dans Lister les Transactions et montrez ce reçu au client.
409 — Paiement en cours
409 — Paiement en cours
Un autre paiement pour ce compte n’est pas encore terminé.Que faire : attendez que ce paiement atteigne un état final, puis recommencez. Ne lancez pas les deux en parallèle.
503 — Partenaire indisponible
503 — Partenaire indisponible
Le facturier est injoignable, ou est actuellement désactivé.Que faire : rafraîchissez Lister les Partenaires et réessayez plus tard. Aucune transaction n’a été créée et rien n’a été débité. Cette réponse ne comporte pas de
Retry-After ; espacez vos tentatives de votre côté.503 — Authentification indisponible
503 — Authentification indisponible
Nous n’avons pas pu vérifier votre clé à temps. Votre clé n’est pas en cause.Que faire : attendez le
Retry-After (5 secondes) et réessayez la même requête avec la même ref.503 — Service indisponible
503 — Service indisponible
L’API Bill Payment est en maintenance planifiée.Que faire : respectez
Retry-After et réessayez avec la même ref.500 — Erreur interne
500 — Erreur interne
Quelque chose a échoué de notre côté.Que faire : vérifiez si la découverte a bien été créée avec Obtenir une Transaction par Référence avant de réessayer, et envoyez le
requestId au support si le problème persiste.Le seuil de découverte de 200 DZD
Les factures inférieures à 200 DZD sont filtrées pendant la découverte et n’apparaissent jamais dansbills[].
Une transaction READY avec un bills[] vide signifie donc l’une de deux choses, et l’API ne fait pas la distinction entre elles :
- le compte ne doit rien, ou
- tout ce qu’il doit est en dessous du seuil de 200 DZD.
Formulez cela avec soin pour vos clients. « Aucune facture n’est payable pour le moment » est exact ; « vous ne devez rien » ne l’est pas.
Prévention des requêtes dupliquées
ref rend une découverte sûre à réessayer. Si une erreur réseau masque la réponse, recherchez la ref au lieu d’envoyer une deuxième découverte.
ref est dérivée de quelque chose que vous stockez déjà — votre propre identifiant de facture ou de commande — afin de pouvoir toujours la reconstruire. Voir Découvrir les factures pour une recette de nommage.
Cycle de Vie du Statut
1
PENDING
La réponse que vous venez de recevoir. La découverte est en file d’attente et en cours d’exécution.
2
READY
Découverte terminée.
bills[] est présent — possiblement vide. Choisissez un billId et appelez Payer une Facture.3
FAILED
La découverte n’a pas pu aboutir.
error.code explique pourquoi : INVALID_ACCOUNT, PARTNER_UNAVAILABLE, BILL_ALREADY_PAID ou PAYMENT_DECLINED.Bonnes Pratiques
Vérifiez d'abord le partenaire
Une carte des partenaires mise en cache vous permet de masquer un facturier indisponible avant que le client ne saisisse un numéro de compte.
Dérivez la ref, ne l'inventez pas
Construisez
ref à partir de votre propre identifiant de commande afin de pouvoir toujours retrouver la transaction.Ne supposez jamais que 200 signifie vide
Les factures arrivent dans la transaction, pas dans cette réponse. Interrogez avant d’annoncer quoi que ce soit à un client.
Lisez fee depuis la réponse
Chaque facture porte son propre
fee. Ne le recalculez pas dans votre propre code.Endpoints Associés
Lister les Partenaires
Vérifiez d’abord la disponibilité
Obtenir une Transaction par ID
Interroger pour obtenir les factures
Payer une Facture
En payer une
Obtenir une Transaction par Référence
Récupérer une réponse perdue
Découvrir les Factures
Le guide complet
Partenaires et Comptes
Règles d’identifiant par partenaire

