Skip to main content
POST
Découvrir les Factures

Vue d’Ensemble

Demande à un facturier ce qu’un compte donné doit actuellement. La réponse est un transactionId que vous interrogez ensuite ; lorsque la transaction atteint READY, son tableau bills[] contient tout ce qui est payable.
200 est un accusé de réception, pas un résultat. Cela signifie que la requête a été acceptée et qu’une transaction a été créée. Les factures arrivent plus tard, dans la transaction. Ne traitez jamais cette réponse comme « le compte ne doit rien ».
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 dans account 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 :
Les trois champs sont requis ensemble.
invoice_number jusqu’à 20 caractères, amount_without_stamp jusqu’à 20, ebb_key jusqu’à 30.
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.
Acceptée pour ADE et SEAAL comme alternative à reference. Elle doit faire exactement 25 caractères.
Exactement un identifiant. reference, contractNumber, aadlNumber et electronic_payment_key comptent pour le même emplacement, tout comme phoneNumber et phone_number ; sonelgaz et ade occupent chacun leur propre emplacement. N’en envoyer aucun, ou en envoyer deux, est rejeté avec un 400.

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

Interrogez Obtenir une Transaction par ID jusqu’à ce que status soit READY, puis lisez bills[] :

Réponses d’Erreur

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.
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.
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.
Vous avez déjà utilisé cette ref pour ce partenaire.
Que faire : ne réessayez pas aveuglément avec une nouvelle 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.
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.
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.
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é.
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.
L’API Bill Payment est en maintenance planifiée.
Que faire : respectez Retry-After et réessayez avec la même ref.
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 dans bills[]. 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.
Une bonne 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.
Référence complète des statuts →

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