> ## 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.

# Obtenir une Transaction par Référence

> Retrouvez une transaction grâce à la référence que vous avez fournie

## Vue d'ensemble

Retrouve une transaction à partir du `ref` que vous avez envoyé au démarrage de la découverte. Elle retourne exactement le même objet que [Obtenir une Transaction par ID](/fr/api-reference/bill-payment/check-by-id).

C'est le chemin de récupération. Lorsqu'une réponse est perdue à cause d'un timeout, d'un plantage ou d'un redéploiement, recherchez le `ref` — ne renvoyez jamais l'écriture.

<Note>
  Un `ref` est unique par partenaire, pas globalement. Si vous réutilisez la même chaîne `ref` pour deux partenaires différents, transmettez également `partner` afin que la recherche soit sans ambiguïté.
</Note>

## Paramètres de requête

<ParamField query="ref" type="string" required>
  La référence que vous avez fournie lors de la création de la découverte. 100 caractères maximum.
</ParamField>

<ParamField query="partner" type="string">
  Facultatif. Une valeur parmi `ADE`, `SONELGAZ`, `SEAAL`, `AADL`, `Algérie Télécom`. Restreint la recherche à ce facturier.
</ParamField>

## Réponse

Identique à [Obtenir une Transaction par ID](/fr/api-reference/bill-payment/check-by-id#response) — l'objet transaction complet, encapsulé dans l'enveloppe standard. Consultez cette page pour la référence champ par champ et pour savoir quels champs apparaissent dans quel statut.

<ResponseField name="success" type="boolean" required>
  `true` lorsqu'une transaction a été trouvée.
</ResponseField>

<ResponseField name="data" type="object" required>
  L'objet transaction. [Référence complète des champs →](/fr/api-reference/bill-payment/check-by-id#response)
</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>
  </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/by-ref \
    --data-urlencode "ref=disc-inv-2026-0042" \
    --data-urlencode "partner=ADE" \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const url = new URL(
    "https://billapi.oneclickdz.com/v3/bills/transactions/by-ref",
  );
  url.searchParams.set("ref", "disc-inv-2026-0042");
  url.searchParams.set("partner", "ADE");

  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.transactionId, body.data.status);
  ```

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

  response = requests.get(
      'https://billapi.oneclickdz.com/v3/bills/transactions/by-ref',
      headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')},
      params={'ref': 'disc-inv-2026-0042', 'partner': 'ADE'}
  )

  body = response.json()

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

  print(body['data']['transactionId'], body['data']['status'])
  ```

  ```php PHP theme={null}
  <?php
  $query = http_build_query([
      'ref'     => 'disc-inv-2026-0042',
      'partner' => 'ADE'
  ]);

  $ch = curl_init("https://billapi.oneclickdz.com/v3/bills/transactions/by-ref?$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 $body['data']['transactionId'] . ' ' . $body['data']['status'];
  ?>
  ```
</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-31T10:16:03.771Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}
```

## Réponses d'erreur

<AccordionGroup>
  <Accordion title="400 — Erreur de Validation">
    **Le `ref` était manquant, trop long, ou `partner` n'était pas une valeur connue.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "ERR_VALIDATION",
        "message": "ref is required."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **Que faire :** envoyez `ref` en paramètre de requête, encodé pour URL, avec 100 caractères au maximum.
  </Accordion>

  <Accordion title="401 — Token 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="404 — Transaction Introuvable">
    **Aucune transaction portant ce `ref` n'appartient à votre compte dans cet environnement.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "NOT_FOUND",
        "message": "Transaction not found."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **Que faire :** après une écriture échouée, un `404` ici est la preuve que la requête n'est jamais arrivée — vous pouvez l'envoyer à nouveau avec le même `ref` en toute sécurité. Vérifiez aussi que vous utilisez la clé de l'environnement dans lequel la transaction a été créée.
  </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": "AUTH_UNAVAILABLE",
        "message": "Authentication is temporarily unavailable. Please retry shortly."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

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

## Récupérer après une réponse perdue

Le schéma est le même pour une découverte et pour un paiement : si l'écriture a échoué d'une manière que vous ne pouvez pas expliquer, demandez à quoi le `ref` correspond avant de renvoyer quoi que ce soit.

```javascript theme={null}
async function resolveRef(ref, partner) {
  const url = new URL(
    "https://billapi.oneclickdz.com/v3/bills/transactions/by-ref",
  );
  url.searchParams.set("ref", ref);
  if (partner) url.searchParams.set("partner", partner);

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

  const body = await response.json();

  if (body.success) {
    return body.data; // The write landed. Continue from data.status.
  }

  if (body.error.code === "NOT_FOUND") {
    return null; // The write never landed. Safe to send it again.
  }

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

<Warning>
  Un `404` renvoyé par cet endpoint n'a de sens que si vous interrogez un `ref` que vous avez réellement envoyé. Ne vous en servez jamais pour conclure qu'un *paiement* n'a pas eu lieu alors que c'est le `ref` de la découverte que vous avez recherché — un paiement vit sur la même transaction que sa découverte, sous le `ref` de la découverte.
</Warning>

## Bonnes pratiques

<CardGroup cols={2}>
  <Card title="Rechercher, Ne Pas Renvoyer" icon="magnifying-glass">
    Chaque timeout et chaque `DUPLICATED_REF` trouve sa réponse ici, pas dans une seconde écriture.
  </Card>

  <Card title="Transmettre le Partenaire" icon="building-columns">
    Cela ne coûte rien et lève toute ambiguïté lorsque la même chaîne `ref` existe pour deux facturiers.
  </Card>

  <Card title="Stocker le Ref avec Votre Commande" icon="database">
    Un `ref` que vous ne pouvez pas reconstituer est une transaction que vous ne pouvez pas récupérer.
  </Card>

  <Card title="Interroger par ID une Fois Obtenu" icon="id-card">
    Utilisez cet endpoint pour récupérer, puis interrogez par `transactionId` — un paramètre de moins à se tromper.
  </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="Lister les Transactions" icon="list" href="/fr/api-reference/bill-payment/list-transactions">
    Filtrez et paginez l'historique
  </Card>

  <Card title="Découvrir les Factures" icon="magnifying-glass-dollar" href="/fr/api-reference/bill-payment/discover-bills">
    Là où un `ref` est créé
  </Card>

  <Card title="Interrogation du Statut" icon="arrows-rotate" href="/fr/bill-payment-guides/4-status-polling">
    Un système d'interrogation de qualité production
  </Card>
</CardGroup>