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

# Format de Réponse

> Comprendre la structure de réponse standardisée

## Structure Standardisée

Tous les endpoints de l'API OneClickDz Flexy v3 suivent une structure de réponse cohérente, ce qui facilite la gestion des réponses dans votre application.

## Réponse de Succès

Lorsqu'une requête réussit, la réponse suit cette structure :

```json theme={null}
{
  "success": true,
  "data": {
    // données spécifiques à l'endpoint
  },
  "meta": {
    "timestamp": "2025-10-29T00:00:00.000Z"
    // métadonnées supplémentaires (pagination, etc.)
  },
  "requestId": "req_1234567890_abc123"
}
```

### Champs

<ResponseField name="success" type="boolean" required>
  Toujours `true` pour les réponses de succès
</ResponseField>

<ResponseField name="data" type="object" required>
  Contient le contenu de la réponse. La structure varie selon l'endpoint.
</ResponseField>

<ResponseField name="meta" type="object">
  Métadonnées supplémentaires sur la réponse

  <Expandable title="properties">
    <ResponseField name="timestamp" type="string">
      Horodatage ISO 8601 indiquant quand la réponse a été générée
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Détails de pagination (pour les endpoints de liste)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="requestId" type="string">
  Identifiant unique pour cette requête. Utilisez-le lors des contacts avec le support.
</ResponseField>

## Réponse d'Erreur

Lorsqu'une requête échoue, la réponse suit cette structure :

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      // additional error context
    }
  },
  "requestId": "req_1234567890_abc123"
}
```

### Champs

<ResponseField name="success" type="boolean" required>
  Toujours `false` pour les réponses d'erreur
</ResponseField>

<ResponseField name="error" type="object" required>
  Contient les informations d'erreur

  <Expandable title="properties">
    <ResponseField name="code" type="string">
      Code d'erreur lisible par la machine (ex. : `NO_BALANCE`, `INVALID_PHONE`)
    </ResponseField>

    <ResponseField name="message" type="string">
      Description de l'erreur lisible par l'humain
    </ResponseField>

    <ResponseField name="details" type="object">
      Contexte supplémentaire sur l'erreur (optionnel)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="requestId" type="string">
  Identifiant unique pour cette requête. Incluez-le lors du signalement de problèmes.
</ResponseField>

## Exemples de Réponse

### Solde du Compte

```json theme={null}
{
  "success": true,
  "data": {
    "balance": 1326.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.710Z"
  }
}
```

### Envoi d'une Recharge Mobile

```json theme={null}
{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "my-order-123",
    "newBalance": 826.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:59.454Z"
  }
}
```

### Liste des Transactions (avec Pagination)

```json theme={null}
{
  "success": true,
  "data": {
    "items": [
      {
        "type": "FLEXY",
        "amount": 500,
        "time": "2025-10-29T00:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 10,
      "totalResults": 195
    }
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.852Z"
  }
}
```

## Pagination

Les endpoints de liste incluent la pagination dans la réponse :

```json theme={null}
{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalPages": 10,
      "totalResults": 195
    }
  }
}
```

### Champs de Pagination

<ResponseField name="page" type="integer">
  Numéro de page actuel (indexé à partir de 1)
</ResponseField>

<ResponseField name="pageSize" type="integer">
  Nombre d'éléments par page
</ResponseField>

<ResponseField name="totalPages" type="integer">
  Nombre total de pages disponibles
</ResponseField>

<ResponseField name="totalResults" type="integer">
  Nombre total d'éléments sur toutes les pages
</ResponseField>

### Paramètres de Requête pour la Pagination

Contrôlez la pagination à l'aide de ces paramètres de requête :

| Paramètre  | Type    | Défaut | Description                            |
| ---------- | ------- | ------ | -------------------------------------- |
| `page`     | integer | 1      | Numéro de page (minimum : 1)           |
| `pageSize` | integer | 20     | Éléments par page (min : 1, max : 100) |

<Tip>Vérifiez toujours `totalPages` pour savoir quand arrêter la pagination.</Tip>

## Codes de Statut HTTP

L'API utilise les codes de statut HTTP conventionnels :

| Code de Statut | Signification                                                     |
| -------------- | ----------------------------------------------------------------- |
| `200`          | Succès - Requête complétée avec succès                            |
| `400`          | Requête Incorrecte - Paramètres invalides ou erreur de validation |
| `401`          | Non Autorisé - Clé API invalide ou manquante                      |
| `403`          | Interdit - Solde ou permissions insuffisants                      |
| `404`          | Non Trouvé - La ressource n'existe pas                            |
| `429`          | Trop de Requêtes - Limite de taux dépassée                        |
| `500`          | Erreur Interne du Serveur - Un problème est survenu de notre côté |
| `503`          | Service Indisponible - Interruption temporaire du service         |

<Note>
  Même pour les codes de statut non-200, la réponse suit le format d'erreur standard.
</Note>

## ID de Requête

Chaque réponse inclut un `requestId` unique :

```json theme={null}
{
  "success": true,
  "data": {...},
  "requestId": "req_1761698159_abc123xyz"
}
```

### Utilisations du Request ID

<CardGroup cols={2}>
  <Card title="Débogage" icon="bug">
    Suivre les requêtes dans les journaux et identifier les problèmes
  </Card>

  {" "}

  <Card title="Support" icon="life-ring">
    Inclure dans les tickets de support pour une résolution plus rapide
  </Card>

  {" "}

  <Card title="Audit" icon="clipboard-check">
    Corréler les requêtes avec les transactions
  </Card>

  <Card title="Surveillance" icon="chart-line">
    Suivre le flux des requêtes entre les systèmes
  </Card>
</CardGroup>

<Tip>
  Enregistrez toujours le `requestId` pour chaque appel API que vous effectuez. Il est indispensable pour le débogage.
</Tip>

## Type de Contenu

Toutes les requêtes et réponses utilisent JSON :

### En-têtes de Requête

```http theme={null}
Content-Type: application/json
X-Access-Token: YOUR_API_KEY
```

### En-têtes de Réponse

```http theme={null}
Content-Type: application/json; charset=utf-8
X-Request-ID: req_1761698159_abc123xyz
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1761698219
```

## Traitement des Réponses

### Bonnes Pratiques

<AccordionGroup>
  <Accordion title="Vérifier toujours le champ success" icon="check-circle">
    ```javascript theme={null}
    const response = await fetch(url, options);
    const data = await response.json();

    if (data.success) {
      console.log(data.data);
    } else {
      console.error(data.error.code, data.error.message);
    }
    ```
  </Accordion>

  <Accordion title="Enregistrer les Request IDs" icon="file-lines">
    ```javascript theme={null}
    console.log(`Request ${data.requestId}: ${data.success ? 'Success' : 'Failed'}`);

    if (!data.success) {
      console.error(`Error ${data.error.code}: ${data.error.message}`);
    }
    ```
  </Accordion>

  <Accordion title="Gérer la pagination" icon="list">
    ```javascript theme={null}
    let page = 1;
    let allItems = [];

    while (true) {
      const response = await fetch(`${url}?page=${page}&pageSize=100`);
      const data = await response.json();
      
      if (!data.success) break;
      
      allItems.push(...data.data.items);
      
      if (page >= data.data.pagination.totalPages) break;
      page++;
    }
    ```
  </Accordion>

  <Accordion title="Analyser les timestamps" icon="clock">
    ```javascript theme={null}
    const timestamp = new Date(data.meta.timestamp);
    console.log(`Response generated at: ${timestamp.toLocaleString()}`);
    ```
  </Accordion>
</AccordionGroup>

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Gestion des erreurs" icon="triangle-exclamation" href="/fr/api-reference/error-handling">
    Apprendre à gérer les erreurs efficacement
  </Card>

  <Card title="Endpoints principaux" icon="code" href="/fr/api-reference/core/health-check">
    Explorer tous les endpoints disponibles
  </Card>
</CardGroup>