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

# Valider la Clé API

> Confirmez qu'une clé Bill Payment fonctionne et à quel environnement elle est rattachée

## Vue d'ensemble

Vérifie votre clé API Bill Payment et vous renvoie qui vous êtes ainsi que l'environnement auquel la clé est rattachée. C'est le premier appel à effectuer dans une nouvelle intégration, et le moyen le plus sûr de prouver, avant de déplacer le moindre argent, que vous pointez bien vers le sandbox et non vers la production.

<Note>
  Chaque clé est rattachée à exactement un environnement — `SANDBOX` ou `PRODUCTION`. L'environnement est une propriété de la clé que nous vous délivrons. **Ne le déduisez jamais du texte ni du préfixe de la clé** ; lisez `key.type` depuis cet endpoint.
</Note>

Bill Payment est hébergé sur `https://billapi.oneclickdz.com`, et non sur l'URL de base utilisée par le reste de la plateforme. L'en-tête est le même que celui que vous utilisez déjà : `X-Access-Token`.

## Réponse

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

<ResponseField name="data" type="object" required>
  <Expandable title="properties">
    <ResponseField name="account" type="object" required>
      <Expandable title="properties">
        <ResponseField name="id" type="string" required>
          L'identifiant de votre compte partenaire.
        </ResponseField>

        <ResponseField name="status" type="string" required>
          `ACTIVE` pour une clé qui a passé la vérification.
        </ResponseField>

        <ResponseField name="currency" type="string" required>
          Toujours `DZD`.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="key" type="object" required>
      <Expandable title="properties">
        <ResponseField name="type" type="string" required>
          `SANDBOX` ou `PRODUCTION`. La seule indication fiable de l'environnement dans lequel cette clé agit.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</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 https://billapi.oneclickdz.com/v3/validate \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://billapi.oneclickdz.com/v3/validate", {
    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(`Account ${body.data.account.id} — ${body.data.key.type}`);
  ```

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

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

  body = response.json()

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

  print(f"Account {body['data']['account']['id']} — {body['data']['key']['type']}")
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://billapi.oneclickdz.com/v3/validate');
  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 "Account {$body['data']['account']['id']} — {$body['data']['key']['type']}";
  ?>
  ```
</CodeGroup>

### Réponse de succès

```json theme={null}
{
  "success": true,
  "data": {
    "account": {
      "id": "partner_7f21",
      "status": "ACTIVE",
      "currency": "DZD"
    },
    "key": {
      "type": "SANDBOX"
    }
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:32.194Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}
```

## Réponses d'erreur

<AccordionGroup>
  <Accordion title="401 — Token d'Accès Manquant">
    **L'en-tête `X-Access-Token` n'a pas été envoyé.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "MISSING_ACCESS_TOKEN",
        "message": "X-Access-Token header is required."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **Que faire :** ajoutez l'en-tête. Bill Payment n'accepte la clé que dans cet en-tête — jamais dans une chaîne de requête ni dans un corps de requête.
  </Accordion>

  <Accordion title="401 — Token d'Accès Invalide">
    **La clé 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 :** cherchez une erreur de copier-coller, puis contactez le support. Réessayer avec la même clé ne changera pas la réponse.
  </Accordion>

  <Accordion title="503 — Authentification Indisponible">
    **Nous n'avons pas pu vérifier votre clé à temps. Votre clé n'est pas en cause.**

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

    **Que faire :** attendez le délai de l'en-tête `Retry-After` (5 secondes) puis réessayez. Ne présentez jamais cette erreur à votre client comme une erreur d'identifiants invalides, et ne désactivez jamais la clé pour cette raison.
  </Accordion>

  <Accordion title="503 — Service Indisponible">
    **L'API Bill Payment 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 `Retry-After` et réessayez.
  </Accordion>
</AccordionGroup>

## Confirmer votre environnement avant la mise en production

Exécutez cette vérification au démarrage, puis à nouveau dans votre pipeline de déploiement. Une seule ligne de sortie vous indique si la clé présente dans la configuration de cet environnement est bien celle que vous vouliez livrer.

```javascript theme={null}
async function assertEnvironment(expected) {
  const response = await fetch("https://billapi.oneclickdz.com/v3/validate", {
    headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
  });

  const body = await response.json();

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

  if (body.data.key.type !== expected) {
    throw new Error(
      `Wrong key: expected ${expected}, got ${body.data.key.type}`,
    );
  }

  return body.data.account.id;
}

// In your sandbox deployment
await assertEnvironment("SANDBOX");
```

<Warning>
  Une clé sandbox et une clé de production ont la même forme, mais pas le même effet. Une clé de production déplace de l'argent réel dès le premier paiement réussi. Vérifiez `key.type` avant d'activer le chemin de paiement.
</Warning>

## Ce que cet endpoint ne retourne pas

Les clés Bill Payment n'ont ni portées, ni champ d'expiration, ni solde par clé : rien de tout cela n'apparaît ici. `account`, `key.type`, `meta` et `requestId` constituent l'intégralité de la réponse.

## Bonnes pratiques

<CardGroup cols={2}>
  <Card title="Appeler au Démarrage" icon="power-off">
    Un seul appel au démarrage prouve que la clé fonctionne et nomme l'environnement, avant que le moindre trafic client n'atteigne le chemin de paiement.
  </Card>

  <Card title="Ne Jamais Journaliser la Clé" icon="key">
    Journalisez plutôt `account.id` et `key.type`. La clé elle-même a sa place dans un coffre à secrets, jamais dans les journaux applicatifs.
  </Card>

  <Card title="Séparer les Deux Clés" icon="code-compare">
    Conservez les clés sandbox et production dans des espaces de configuration différents, afin qu'aucune ne soit accessible depuis l'autre environnement.
  </Card>

  <Card title="Traiter le 503 comme Transitoire" icon="clock-rotate-left">
    `AUTH_UNAVAILABLE` signifie que nous n'avons pas pu répondre à temps. Réessayez après `Retry-After` ; ne changez pas la clé.
  </Card>
</CardGroup>

## Endpoints associés

<CardGroup cols={2}>
  <Card title="Lister les Partenaires" icon="building-columns" href="/fr/api-reference/bill-payment/list-partners">
    Vérifiez quels partenaires sont disponibles
  </Card>

  <Card title="Découvrir les Factures" icon="magnifying-glass-dollar" href="/fr/api-reference/bill-payment/discover-bills">
    Lancez une découverte de factures
  </Card>

  <Card title="Vue d'ensemble Bill Payment" icon="file-invoice-dollar" href="/fr/bill-payment-guides/overview">
    Comment tout le flux s'articule
  </Card>

  <Card title="Tests en Sandbox" icon="flask" href="/fr/bill-payment-guides/6-sandbox-testing">
    Testez chaque issue avant la mise en production
  </Card>
</CardGroup>