Partenaires et comptes - OneClickDz Flexy API

Vue d’ensemble

Avant de pouvoir découvrir quoi que ce soit, deux choses doivent être correctes : le facturier doit être disponible, et l’identifiant de compte doit être celui que ce facturier comprend. Cette étape couvre les deux, ainsi que la différence entre les deux erreurs que vous verrez lorsque le second est erroné.

Tout sur cette page utilise https://billapi.oneclickdz.com et l’en-tête X-Access-Token. Si vous n’avez pas confirmé à quel environnement appartient votre clé, commencez par Valider la clé API.

Vérifier la disponibilité

GET /v3/partners renvoie une entrée par facturier, chacune avec un unique champ status.

curl https://billapi.oneclickdz.com/v3/partners \
  -H "X-Access-Token: YOUR_API_KEY"

const response = await fetch("https://billapi.oneclickdz.com/v3/partners", {
  headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

const available = Object.entries(body.data)
  .filter(([, partner]) => partner.status === "ACTIVE")
  .map(([name]) => name);

console.log(available);

import os
import requests

response = requests.get(
    'https://billapi.oneclickdz.com/v3/partners',
    headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
)

body = response.json()
if not body['success']:
    raise RuntimeError(body['error']['code'])

available = [
    name for name, partner in body['data'].items()
    if partner['status'] == 'ACTIVE'
]

print(available)

<?php
$ch = curl_init('https://billapi.oneclickdz.com/v3/partners');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

if (!$body['success']) {
    throw new Exception($body['error']['code']);
}

$available = array_keys(array_filter(
    $body['data'],
    fn($partner) => $partner['status'] === 'ACTIVE'
));

print_r($available);
?>

{
  "success": true,
  "data": {
    "ADE": { "status": "ACTIVE" },
    "SONELGAZ": { "status": "ACTIVE" },
    "SEAAL": { "status": "UNAVAILABLE" },
    "AADL": { "status": "UNAVAILABLE" },
    "Algérie Télécom": { "status": "ACTIVE" }
  },
  "meta": { "timestamp": "2026-08-31T10:15:32.194Z" },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

Un facturier marqué UNAVAILABLE répond 503 PARTNER_UNAVAILABLE à la découverte comme au paiement. SEAAL et AADL sont actuellement UNAVAILABLE en sandbox comme en production — c’est le réglage actuel de l’opérateur, pas une limitation permanente, alors gardez-les dans votre code et laissez la carte décider de ce qu’il faut afficher.

Une clé PRODUCTION voit la disponibilité réelle ; une clé SANDBOX voit une carte figée, parce qu’une requête sandbox n’atteint jamais un facturier. N’utilisez pas le sandbox pour tester la réaction de votre application à la panne d’un facturier — utilisez les scénarios sandbox dédiés pour cela.

L’identifiant de chaque facturier

Envoyez exactement un identifiant, et envoyez le champ qui correspond au facturier que vous interrogez. L’API renvoie ce même champ dans account sur chaque transaction pour ce facturier.

Partenaire	Champ	Format	Exemple valide
`ADE`	`reference`	Jusqu’à 50 caractères	`"0123456789012345678901234"`
`SEAAL`	`reference`	Jusqu’à 50 caractères	`"0123456789012340000000000"`
`SONELGAZ`	`contractNumber`	Jusqu’à 50 caractères	`"9876543210"`
`AADL`	`aadlNumber`	Jusqu’à 50 caractères	`"1112223334"`
`Algérie Télécom`	`phoneNumber`	`0` ou `+213`, puis un chiffre de 2 à 4, puis 7 chiffres	`"023456789"`

{
  "partner": "ADE",
  "account": { "reference": "0123456789012345678901234" },
  "ref": "disc-inv-2026-0042"
}

Envoyez Algérie Télécom avec ses accents. La valeur est comparée caractère par caractère, et c’est aussi la clé que vous relisez dans la carte des partenaires.

Numéros de téléphone fixe

phoneNumber est un fixe algérien, pas un numéro mobile. Valide :

"023456789" — zéro de tête, puis un chiffre compris entre 2 et 4
"+213023456789" n’est pas valide ; utilisez "+21323456789" ou la forme locale "023456789"

Invalide :

"0778037340" — un numéro mobile, pas un fixe
"23456789" — zéro de tête manquant
"023 45 67 89" — contient des espaces
23456789 — un nombre au lieu d’une chaîne

Les formes d’identifiant plus riches

Deux facturiers acceptent un objet plus complet lorsqu’un seul numéro ne suffit pas à identifier une facture précise. Chaque champ à l’intérieur de ces objets est obligatoire.

SONELGAZ — forme facture

{
  "partner": "SONELGAZ",
  "account": {
    "sonelgaz": {
      "invoice_number": "9876543210",
      "amount_without_stamp": "15000",
      "ebb_key": "ABC123"
    }
  },
  "ref": "disc-inv-2026-0042"
}

invoice_number jusqu’à 20 caractères, amount_without_stamp jusqu’à 20, ebb_key jusqu’à 30.

ADE — forme facture

{
  "partner": "ADE",
  "account": {
    "ade": {
      "sub_id": "000123456789",
      "period": "07/2026",
      "amount": "12000",
      "pay_key": "1234567"
    }
  },
  "ref": "disc-inv-2026-0043"
}

sub_id exactement 12 caractères, period au format MM/YYYY, amount jusqu’à 20 caractères, pay_key exactement 7 caractères.

ADE et SEAAL — clé de 25 caractères

electronic_payment_key est accepté comme alternative à reference, et doit faire exactement 25 caractères.

{
  "partner": "ADE",
  "account": { "electronic_payment_key": "0123456789012345678901234" },
  "ref": "disc-inv-2026-0044"
}

Exactement un identifiant

L’objet account doit porter un seul identifiant, pas plus. Les champs se regroupent en quatre emplacements :

Emplacement	Champs
Clé de type référence	`reference`, `contractNumber`, `aadlNumber`, `electronic_payment_key`
Fixe	`phoneNumber`, `phone_number`
Facture SONELGAZ	`sonelgaz`
Facture ADE	`ade`

Exactement un emplacement doit être rempli. Zéro ou deux est rejeté avant que quoi que ce soit d’autre ne se produise.

{
  "partner": "ADE",
  "account": {
    "reference": "0123456789012345678901234",
    "phoneNumber": "023456789"
  },
  "ref": "disc-inv-2026-0045"
}

{
  "success": false,
  "error": {
    "code": "ERR_VALIDATION",
    "message": "account must contain exactly one identifier (electronic_payment_key, phone_number, sonelgaz, or ade)",
    "details": [
      "account must contain exactly one identifier (electronic_payment_key, phone_number, sonelgaz, or ade)"
    ]
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}

Valider cela de votre côté tient en une ligne, et transforme un aller-retour en une erreur de formulaire instantanée :

const SLOTS = [
  ["reference", "contractNumber", "aadlNumber", "electronic_payment_key"],
  ["phoneNumber", "phone_number"],
  ["sonelgaz"],
  ["ade"],
];

function hasExactlyOneIdentifier(account) {
  const filled = SLOTS.filter((slot) =>
    slot.some((field) => {
      const value = account[field];
      return value !== undefined && value !== null && value !== "";
    }),
  );

  return filled.length === 1;
}

`ERR_VALIDATION` ou `INVALID_ACCOUNT` ?

Les deux sont des 400, et ils signifient des choses très différentes.

	`ERR_VALIDATION`	`INVALID_ACCOUNT`
Cause	La requête ne correspond pas au schéma	L’identifiant est bien formé mais inutilisable
Exemples	Pas de `ref` ; deux identifiants ; un `electronic_payment_key` de 24 caractères ; un numéro mobile dans `phoneNumber`	Un numéro de compte que le facturier ne reconnaît pas
À qui la faute	À votre intégration	À la saisie de votre client
Montrer au client	Non — journalisez-la	Oui — « vérifiez le numéro sur votre facture »
Réessayer sans changement	Jamais	Uniquement après que le client a corrigé le numéro

N’affichez pas les messages ERR_VALIDATION aux clients finaux. Ils citent des noms de champs internes comme electronic_payment_key, ce qui ne signifie rien pour quelqu’un qui tient une facture papier.

Mettre la carte des partenaires en cache

La disponibilité change rarement, alors rafraîchissez-la sur un minuteur plutôt qu’avant chaque découverte — et continuez à servir la dernière copie valide si un rafraîchissement échoue. Une liste de facturiers vide est pire pour vos clients qu’une liste légèrement périmée.

let cache = { map: null, fetchedAt: 0 };
const TTL_MS = 5 * 60 * 1000;

async function getPartners() {
  if (cache.map && Date.now() - cache.fetchedAt < TTL_MS) return cache.map;

  try {
    const response = await fetch("https://billapi.oneclickdz.com/v3/partners", {
      headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
    });

    const body = await response.json();
    if (body.success) cache = { map: body.data, fetchedAt: Date.now() };
  } catch {
    // Serve the previous map rather than blocking the customer.
  }

  return cache.map ?? {};
}

Le cache ne dispense pas de gérer 503 PARTNER_UNAVAILABLE à la découverte. Un facturier peut tomber en panne entre votre dernier rafraîchissement et le moment où le client appuie sur le bouton.

Bonnes pratiques

Validez avant d'envoyer

Vérifiez la règle d’emplacement et le format du fixe côté client. Cela économise un aller-retour et donne un meilleur message d’erreur.

Mettez la carte en cache pour des minutes, pas des heures

Cinq minutes suffisent largement. Rafraîchissez en arrière-plan, jamais sur le chemin critique du client.

Gardez les facturiers indisponibles dans votre code

SEAAL et AADL reviendront. Pilotez l’interface depuis la carte, pas depuis une liste codée en dur.

Séparez les deux 400

INVALID_ACCOUNT est un message pour votre client. ERR_VALIDATION est un message pour vos logs.

Étape suivante

Étape 2 : Découverte des factures

Envoyez une découverte, interrogez-la jusqu’à READY, et lisez ce qui est payable

Pages liées

Lister les partenaires

La référence de l’endpoint

Découvrir les factures

Où l’objet account est envoyé

Vue d'ensemble du Paiement de Factures

La carte en cinq étapes

Tests en sandbox

Les identifiants qui produisent un résultat choisi

​Vue d’ensemble

​Vérifier la disponibilité

​L’identifiant de chaque facturier

​Numéros de téléphone fixe

​Les formes d’identifiant plus riches

​Exactement un identifiant

​ERR_VALIDATION ou INVALID_ACCOUNT ?

​Mettre la carte des partenaires en cache

​Bonnes pratiques

Validez avant d'envoyer

Mettez la carte en cache pour des minutes, pas des heures

Gardez les facturiers indisponibles dans votre code

Séparez les deux 400

​Étape suivante

Étape 2 : Découverte des factures

​Pages liées

Lister les partenaires

Découvrir les factures

Vue d'ensemble du Paiement de Factures

Tests en sandbox

Vue d’ensemble

Vérifier la disponibilité

L’identifiant de chaque facturier

Numéros de téléphone fixe

Les formes d’identifiant plus riches

Exactement un identifiant

`ERR_VALIDATION` ou `INVALID_ACCOUNT` ?

Mettre la carte des partenaires en cache

Bonnes pratiques

Étape suivante

Pages liées