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

# Vue d'ensemble de l'intégration des cartes cadeaux

> Apprenez à intégrer la commande de cartes cadeaux et de produits numériques

## Introduction

Intégrez la vente de cartes cadeaux et de produits numériques en 5 étapes simples. Cette vue d'ensemble explique le flux de travail-l'implémentation détaillée avec des exemples de code se trouve dans les guides étape par étape ci-dessous.

<Info>
  Les commandes de cartes cadeaux sont traitées en quelques secondes et les codes de carte sont livrés numériquement via l'API.
</Info>

## Comment ça fonctionne

```mermaid theme={null}
sequenceDiagram
    participant User
    participant YourApp
    participant API as OneClickDz API

    YourApp->>API: 1. Load product catalog
    API-->>YourApp: Categories & products

    User->>YourApp: Select product
    YourApp->>API: 2. Check product details
    API-->>YourApp: Types, pricing, stock

    User->>YourApp: Choose type & quantity
    YourApp->>API: 3. Place order
    API-->>YourApp: Order ID

    loop Until Complete
        YourApp->>API: 4. Check order status
        API-->>YourApp: Status update
    end

    YourApp->>User: 5. Deliver card codes
```

## Processus d'intégration en 5 étapes

<Steps>
  <Step title="Charger le catalogue">
    Récupérez les produits disponibles organisés par catégories (Gaming, Streaming, etc.).
    → [Voir Étape 1 : Chargement du catalogue](/fr/gift-card-guides/1-loading-catalog)
  </Step>

  <Step title="Vérifier le produit">
    Obtenez les dénominations, les tarifs et le stock en temps réel pour un produit spécifique. →
    [Voir Étape 2 : Vérification des produits](/fr/gift-card-guides/2-checking-products)
  </Step>

  <Step title="Passer une commande">
    Soumettez la commande avec l'ID produit, l'ID type (dénomination) et la quantité. → [Voir
    Étape 3 : Passage de commandes](/fr/gift-card-guides/3-placing-orders)
  </Step>

  <Step title="Suivre le statut">
    Interrogez le statut de la commande toutes les 5 à 10 secondes jusqu'à la complétion. → [Voir Étape 4 : Suivi du statut](/fr/gift-card-guides/4-status-tracking)
  </Step>

  <Step title="Livrer les cartes">
    Récupérez les codes/numéros de série et livrez-les en toute sécurité au client. → [Voir Étape 5 :
    Livraison sécurisée](/fr/gift-card-guides/5-secure-delivery)
  </Step>
</Steps>

## Ce que vous devez savoir

### Structure des produits

* **Catalogue** → Catégories (Gaming, Streaming, etc.)
* **Produits** → Articles individuels (PUBG, Netflix, etc.)
* **Types** → Dénominations (500 DA, 1000 DA, etc.)

→ [Structure du catalogue à l'Étape 1](/fr/gift-card-guides/1-loading-catalog)

### Statut de commande

* `HANDLING` → Continuez à interroger
* `FULFILLED` → Toutes les cartes livrées ✅
* `PARTIALLY_FILLED` → Certaines cartes livrées, le reste remboursé ⚠️
* `REFUNDED` → Commande échouée, remboursement émis ❌

→ [Gestion des statuts à l'Étape 4](/fr/gift-card-guides/4-status-tracking)

### Exécution partielle

Si vous commandez 5 cartes mais seulement 3 sont disponibles, vous recevrez :

* 3 cartes livrées
* Facturé uniquement pour 3
* Remboursé pour 2 automatiquement

Vérifiez toujours `fulfilled_quantity` par rapport à `quantity`.

→ [Gestion des partiels à l'Étape 4](/fr/gift-card-guides/4-status-tracking)

### Tarification

Appliquez votre marge sur les prix de gros avant d'afficher aux clients.

Exemple : 490 DA en gros → Vendez à 515 DA (5% de marge) → Profit : 25 DA

→ [Tarification à l'Étape 2](/fr/gift-card-guides/2-checking-products)

## Points clés

<CardGroup cols={2}>
  <Card title="Vérifier le stock" icon="warehouse">
    Vérifiez `available: true` avant d'afficher les produits → [Étape
    2](/fr/gift-card-guides/2-checking-products)
  </Card>

  <Card title="Mettre en cache le catalogue" icon="database">
    Mettez en cache le catalogue pendant +24 heures pour réduire les appels API → [Étape
    1](/fr/gift-card-guides/1-loading-catalog)
  </Card>

  <Card title="Gérer les partiels" icon="triangle-exclamation">
    Vérifiez la quantité exécutée par rapport à la quantité demandée → [Étape
    4](/fr/gift-card-guides/4-status-tracking)
  </Card>

  <Card title="Chiffrer les cartes" icon="lock">
    Ne stockez jamais les codes de carte en texte clair → [Étape
    5](/fr/gift-card-guides/5-secure-delivery)
  </Card>
</CardGroup>

## Référence API

<CardGroup cols={2}>
  <Card title="Obtenir le catalogue" icon="list" href="/fr/api-reference/gift-cards/get-catalog">
    GET /v3/gift-cards/catalog
  </Card>

  <Card title="Vérifier le produit" icon="magnifying-glass" href="/fr/api-reference/gift-cards/check-product">
    GET /v3/gift-cards/checkProduct/:id
  </Card>

  <Card title="Passer une commande" icon="cart-shopping" href="/fr/api-reference/gift-cards/place-order">
    POST /v3/gift-cards/placeOrder
  </Card>

  <Card title="Vérifier la commande" icon="file-circle-check" href="/fr/api-reference/gift-cards/check-order">
    GET /v3/gift-cards/checkOrder/:id
  </Card>
</CardGroup>

## Tests

Utilisez le **mode sandbox** pour tester sans dépenser de balance réelle :

* `TEST_REFUND` (type ID) → Simule une commande échouée
* `TEST_PARTIAL` (type ID) → Simule une exécution à 50%

Activez le sandbox dans les [paramètres du tableau de bord](https://app.oneclickdz.com/#/settings).

## Commencer l'intégration

<Card title="Commencer avec l'Étape 1 : Chargement du catalogue" icon="play" href="/fr/gift-card-guides/1-loading-catalog" color="#0D9373">
  Commencez par charger le catalogue de produits avec des exemples de code
</Card>

## Ressources supplémentaires

<CardGroup cols={2}>
  <Card title="Guide de démarrage rapide" icon="rocket" href="/fr/quickstart">
    Démarrez en 5 minutes
  </Card>

  <Card title="Authentification" icon="key" href="/fr/authentication">
    Apprenez à authentifier les requêtes
  </Card>

  <Card title="Meilleures pratiques de sécurité" icon="shield" href="/fr/security-best-practices">
    Sécurisez votre intégration
  </Card>

  <Card title="Contacter le support" icon="headset" href="/fr/contact">
    Obtenez l'aide de notre équipe
  </Card>
</CardGroup>