> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lister les Transactions

> Parcourir vos découvertes et paiements de factures page par page

## Vue d'Ensemble

Retourne vos transactions Bill Payment, les plus récentes en premier. Utilisez-le pour la réconciliation, pour un écran d'historique, et pour retrouver une transaction lorsque vous avez perdu son identifiant et sa référence.

La liste est limitée à votre propre compte et à l'environnement de la clé que vous envoyez : une clé sandbox ne voit jamais les transactions de production, et inversement.

<Note>
  `data` est un **tableau simple** d'objets transaction. Les compteurs se trouvent dans `meta` : `total`, `limit` et `offset`.
</Note>

## Paramètres de Requête

<ParamField query="status" type="string">
  Filtrer par statut. L'une des valeurs `PENDING`, `READY`, `PROCESSING`, `SUCCESS`, `FAILED`, `REFUNDED`, `UNKNOWN`.
</ParamField>

<ParamField query="partner" type="string">
  Filtrer par facturier. L'une des valeurs `ADE`, `SONELGAZ`, `SEAAL`, `AADL`, `Algérie Télécom`.
</ParamField>

<ParamField query="from" type="string">
  Uniquement les transactions créées à cet instant ou après. Une date ou date-heure ISO 8601, par exemple `2026-08-01` ou `2026-08-01T00:00:00Z`.
</ParamField>

<ParamField query="to" type="string">
  Uniquement les transactions créées à cet instant ou avant. Même format que `from`.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Taille de page, entre 1 et 100.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Combien de transactions ignorer. Zéro ou plus.
</ParamField>

<Warning>
  Il n'y a pas de filtre `ref` sur cet endpoint. Pour retrouver une transaction par votre propre référence, utilisez [Obtenir une Transaction par Référence](/fr/api-reference/bill-payment/check-by-ref).
</Warning>

## Réponse

<ResponseField name="success" type="boolean" required>
  `true` lorsque la page a été retournée.
</ResponseField>

<ResponseField name="data" type="array" required>
  Un tableau d'objets transaction, les plus récents en premier. Chaque entrée a exactement la forme documentée sur [Obtenir une Transaction par ID](/fr/api-reference/bill-payment/check-by-id#response) — y compris la règle selon laquelle `bills`, `selectedBill`, `receiptUrl`, `operationId` et `error` n'apparaissent que dans les statuts où ils ont un sens.

  Un tableau vide signifie qu'aucune transaction ne correspond.
</ResponseField>

<ResponseField name="meta" type="object" required>
  <Expandable title="properties">
    <ResponseField name="timestamp" type="string" required>
      Heure de la réponse, ISO 8601 UTC.
    </ResponseField>

    <ResponseField name="total" type="integer" required>
      Combien de transactions correspondent aux filtres au total, en ignorant `limit` et `offset`.
    </ResponseField>

    <ResponseField name="limit" type="integer" required>
      La taille de page qui a été appliquée.
    </ResponseField>

    <ResponseField name="offset" type="integer" required>
      Le décalage qui a été appliqué.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="requestId" type="string" required>
  Identifiant de corrélation, également envoyé dans l'en-tête de réponse `X-Request-Id`.
</ResponseField>

## Exemples

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://billapi.oneclickdz.com/v3/bills/transactions \
    --data-urlencode "status=SUCCESS" \
    --data-urlencode "partner=ADE" \
    --data-urlencode "from=2026-08-01" \
    --data-urlencode "to=2026-08-31" \
    --data-urlencode "limit=50" \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const url = new URL("https://billapi.oneclickdz.com/v3/bills/transactions");
  url.searchParams.set("status", "SUCCESS");
  url.searchParams.set("partner", "ADE");
  url.searchParams.set("from", "2026-08-01");
  url.searchParams.set("to", "2026-08-31");
  url.searchParams.set("limit", "50");

  const response = await fetch(url, {
    headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
  });

  const body = await response.json();

  if (!body.success) {
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }

  console.log(`${body.data.length} of ${body.meta.total}`);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      'https://billapi.oneclickdz.com/v3/bills/transactions',
      headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')},
      params={
          'status': 'SUCCESS',
          'partner': 'ADE',
          'from': '2026-08-01',
          'to': '2026-08-31',
          'limit': 50
      }
  )

  body = response.json()

  if not body['success']:
      raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

  print(f"{len(body['data'])} of {body['meta']['total']}")
  ```

  ```php PHP theme={null}
  <?php
  $query = http_build_query([
      'status'  => 'SUCCESS',
      'partner' => 'ADE',
      'from'    => '2026-08-01',
      'to'      => '2026-08-31',
      'limit'   => 50
  ]);

  $ch = curl_init("https://billapi.oneclickdz.com/v3/bills/transactions?$query");
  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'] . ': ' . $body['error']['message']);
  }

  echo count($body['data']) . ' of ' . $body['meta']['total'];
  ?>
  ```
</CodeGroup>

### Réponse de Succès

```json theme={null}
{
  "success": true,
  "data": [
    {
      "transactionId": "68b2f4c1a7d3e9f204c81a55",
      "ref": "disc-inv-2026-0042",
      "type": "payment",
      "status": "SUCCESS",
      "partner": "ADE",
      "account": { "reference": "0123456789012345678901234" },
      "selectedBill": {
        "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
        "amount": 443.39,
        "fee": 30.00,
        "label": "Facture ADE"
      },
      "total": 473.39,
      "currency": "DZD",
      "receiptUrl": "https://billapi.oneclickdz.com/v3/bills/transactions/68b2f4c1a7d3e9f204c81a55/receipt",
      "operationId": "op_7726351904",
      "createdAt": "2026-08-31T10:15:32.194Z",
      "updatedAt": "2026-08-31T10:15:41.902Z",
      "completedAt": "2026-08-31T10:15:41.902Z"
    }
  ],
  "meta": {
    "timestamp": "2026-08-31T11:02:14.508Z",
    "total": 137,
    "limit": 50,
    "offset": 0
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}
```

## Réponses d'Erreur

<AccordionGroup>
  <Accordion title="400 — Erreur de validation">
    **Une valeur de filtre n'a pas été acceptée.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "ERR_VALIDATION",
        "message": "status must be one of: PENDING, READY, PROCESSING, UNKNOWN, SUCCESS, FAILED, REFUNDED",
        "details": [
          "status must be one of: PENDING, READY, PROCESSING, UNKNOWN, SUCCESS, FAILED, REFUNDED"
        ]
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    Causes courantes : un statut ou un partenaire en dehors de l'ensemble autorisé, un `from` ou un `to` qui n'est pas une date ISO 8601, un `limit` supérieur à 100 ou inférieur à 1, un `offset` négatif.

    **Que faire :** corrigez la chaîne de requête. Les valeurs sont sensibles à la casse.
  </Accordion>

  <Accordion title="401 — Jeton d'accès manquant ou invalide">
    **La clé était absente ou a été rejetée.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "INVALID_ACCESS_TOKEN",
        "message": "The provided access token is invalid."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **Que faire :** vérifiez la clé avec [Valider la Clé API](/fr/api-reference/bill-payment/validate-key).
  </Accordion>

  <Accordion title="503 — Authentification ou service indisponible">
    **Nous n'avons pas pu vérifier votre clé à temps, ou l'API est en maintenance planifiée.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "SERVICE_UNAVAILABLE",
        "message": "The service is temporarily unavailable. Please retry shortly."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **Que faire :** respectez l'en-tête `Retry-After` (5 secondes) et réessayez. Le listage peut toujours être répété sans risque.
  </Accordion>
</AccordionGroup>

## Parcourir une période page par page

`meta.total` est le nombre correspondant aux filtres que vous avez envoyés, vous pouvez donc paginer jusqu'à avoir tout vu. Gardez une taille de page modeste et une fenêtre bornée.

```javascript theme={null}
async function* eachTransaction(filters) {
  let offset = 0;
  const limit = 100;

  for (;;) {
    const url = new URL("https://billapi.oneclickdz.com/v3/bills/transactions");
    for (const [key, value] of Object.entries(filters)) {
      url.searchParams.set(key, value);
    }
    url.searchParams.set("limit", String(limit));
    url.searchParams.set("offset", String(offset));

    const response = await fetch(url, {
      headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
    });

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

    for (const transaction of body.data) yield transaction;

    offset += body.data.length;
    if (offset >= body.meta.total || body.data.length === 0) return;
  }
}

// Every successful ADE payment in August
for await (const transaction of eachTransaction({
  status: "SUCCESS",
  partner: "ADE",
  from: "2026-08-01",
  to: "2026-08-31",
})) {
  console.log(transaction.transactionId, transaction.total);
}
```

<Note>
  De nouvelles transactions sont créées pendant que vous paginez. Pour la réconciliation, bornez toujours la fenêtre avec `from` et `to` afin que l'ensemble des résultats ne puisse pas grossir sous vos pieds.
</Note>

## Ce que contient la liste

Les découvertes comme les paiements apparaissent ici. `type` les distingue :

* `type: "discovery"` — une recherche qui n'a pas été payée. Son `status` est `PENDING`, `READY` ou `FAILED`.
* `type: "payment"` — une découverte contre laquelle un paiement a été soumis. Son `status` est `PROCESSING`, `SUCCESS`, `FAILED`, `REFUNDED` ou `UNKNOWN`.

Une transaction devient un `payment` sur place, en conservant son `transactionId` et sa `ref` d'origine.

## Bonnes Pratiques

<CardGroup cols={2}>
  <Card title="Bornez chaque requête" icon="calendar">
    Envoyez toujours `from` et `to` pour la réconciliation. Une liste non bornée grandit avec votre activité.
  </Card>

  <Card title="Réconciliez sur SUCCESS et REFUNDED" icon="scale-balanced">
    Ces deux statuts sont ceux où l'argent a bougé. `FAILED` n'en a jamais déplacé.
  </Card>

  <Card title="N'interrogez pas cet endpoint en boucle" icon="ban">
    Pour suivre une seule transaction, interrogez-la par identifiant. Lister de façon répétée est plus lent et plus lourd des deux côtés.
  </Card>

  <Card title="Lisez meta.total" icon="list-ol">
    C'est le nombre correspondant à vos filtres, et le seul moyen de savoir si une autre page existe.
  </Card>
</CardGroup>

## Endpoints Associés

<CardGroup cols={2}>
  <Card title="Obtenir une Transaction par ID" icon="id-card" href="/fr/api-reference/bill-payment/check-by-id">
    L'objet transaction complet
  </Card>

  <Card title="Obtenir une Transaction par Référence" icon="tag" href="/fr/api-reference/bill-payment/check-by-ref">
    Rechercher par votre propre `ref`
  </Card>

  <Card title="Télécharger le Reçu" icon="file-arrow-down" href="/fr/api-reference/bill-payment/get-receipt">
    Preuve pour une transaction payée
  </Card>

  <Card title="Reçus et Réconciliation" icon="scale-balanced" href="/fr/bill-payment-guides/5-receipts-and-reconciliation">
    Une routine de réconciliation quotidienne
  </Card>
</CardGroup>