Suivi de Statut et Interrogation - OneClickDz Flexy API

Vue d’ensemble

Après avoir passé une commande, interrogez l’endpoint /checkOrder pour suivre le statut et récupérer les codes de carte lors de l’exécution. La plupart des commandes sont traitées en quelques secondes.

Interrogez toutes les 5-10 secondes jusqu’à ce que la commande atteigne un état final : FULFILLED, PARTIALLY_FILLED ou REFUNDED.

Référence API

GET /v3/gift-cards/checkOrder/{orderId}

Documentation complète de l’endpoint

Valeurs de Statut de Commande

HANDLING

La commande est en cours de traitement. Continuez l’interrogation. La plupart des commandes se résolvent en 30 secondes.

FULFILLED

Succès ! Toutes les cartes livrées. fulfilled_quantity === quantity. Cartes disponibles dans le tableau cards.

PARTIALLY_FILLED

Succès partiel. Certaines cartes livrées, le reste annulé. fulfilled_quantity < quantity. Remboursement partiel émis automatiquement.

REFUNDED

Échec. La commande a complètement échoué. fulfilled_quantity === 0. Remboursement intégral émis automatiquement.

Tests en mode Sandbox

Utilisez le mode sandbox pour tester sans dépenser de solde réel :

Tester une commande échouée

Utilisez TEST_REFUND comme type ID → Simule une commande échouée (statut REFUNDED)

Tester un succès partiel

Utilisez TEST_PARTIAL comme type ID → Simule une exécution à 50% (statut PARTIALLY_FILLED)

Sandbox Example

// Tester différents scénarios sans frais réels
const testScenarios = [
  {
    productId: "507f1f77bcf86cd799439011",
    typeId: "TEST_REFUND", // Will fail and refund
    quantity: 2,
  },
  {
    productId: "507f1f77bcf86cd799439011",
    typeId: "TEST_PARTIAL", // Will deliver 50% of cards
    quantity: 4,
  },
];

// Place test order
const order = await placeOrder(
  testScenarios[0].productId,
  testScenarios[0].typeId,
  testScenarios[0].quantity
);

// Poll for results
const result = await pollOrderUntilComplete(order.orderId);
console.log("Test result:", result.status);

Vérification de statut de base

async function checkOrderStatus(orderId) {
  const response = await fetch(
    `https://api.oneclickdz.com/v3/gift-cards/checkOrder/${orderId}`,
    {
      headers: {
        "X-Access-Token": process.env.API_KEY,
      },
    }
  );

  if (!response.ok) {
    throw new Error(`Failed to check order: ${response.status}`);
  }

  const result = await response.json();
  return result.data;
}

// Usage
const orderId = "6901616fe9e88196b4eb64b3";
const order = await checkOrderStatus(orderId);

console.log(`Status: ${order.status}`);
console.log(`Quantity: ${order.quantity}`);

if (order.cards) {
  console.log(`Cards delivered: ${order.cards.length}`);
}

import requests
import os

def check_order_status(order_id):
    response = requests.get(
        f'https://api.oneclickdz.com/v3/gift-cards/checkOrder/{order_id}',
        headers={'X-Access-Token': os.getenv('API_KEY')}
    )

    response.raise_for_status()
    return response.json()['data']

# Usage
order_id = '6901616fe9e88196b4eb64b3'
order = check_order_status(order_id)

print(f"Status: {order['status']}")
print(f"Quantity: {order['quantity']}")

if 'cards' in order:
    print(f"Cards delivered: {len(order['cards'])}")

<?php

function checkOrderStatus($orderId, $apiKey) {
    $url = "https://api.oneclickdz.com/v3/gift-cards/checkOrder/{$orderId}";

    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Access-Token: ' . $apiKey
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("Failed to check order: " . $httpCode);
    }

    $result = json_decode($response, true);
    return $result['data'];
}

// Usage
$orderId = '6901616fe9e88196b4eb64b3';
$order = checkOrderStatus($orderId, getenv('API_KEY'));

echo "Status: {$order['status']}\n";
echo "Quantity: {$order['quantity']}\n";

if (isset($order['cards'])) {
    echo "Cards delivered: " . count($order['cards']) . "\n";
}
?>

curl https://api.oneclickdz.com/v3/gift-cards/checkOrder/6901616fe9e88196b4eb64b3 \
  -H "X-Access-Token: YOUR_API_KEY"

Exemples de réponse

En cours de traitement

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b3",
    "status": "HANDLING",
    "quantity": 2,
    "product": "507f1f77bcf86cd799439011",
    "type": "type_001",
    "time": "2025-10-29T01:00:00.000Z"
  }
}

Exécuté (Succès)

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b3",
    "status": "FULFILLED",
    "quantity": 2,
    "fulfilled_quantity": 2,
    "fulfilled_amount": 980,
    "price_per_card": 490,
    "cards": [
      {
        "value": "XXXX-XXXX-XXXX-XXXX",
        "serial": "123456789"
      },
      {
        "value": "YYYY-YYYY-YYYY-YYYY",
        "serial": "987654321"
      }
    ],
    "time": "2025-10-29T01:00:00.000Z"
  }
}

Partiellement exécuté

{
  "success": true,
  "data": {
    "_id": "6901616fe9e88196b4eb64b3",
    "status": "PARTIALLY_FILLED",
    "quantity": 5,
    "fulfilled_quantity": 3,
    "fulfilled_amount": 1470,
    "price_per_card": 490,
    "cards": [
      {
        "value": "AAAA-AAAA-AAAA-AAAA",
        "serial": "111111111"
      },
      {
        "value": "BBBB-BBBB-BBBB-BBBB",
        "serial": "222222222"
      },
      {
        "value": "CCCC-CCCC-CCCC-CCCC",
        "serial": "333333333"
      }
    ],
    "time": "2025-10-29T01:00:00.000Z"
  }
}

Implémentation de l’interrogation simple

async function pollOrderUntilComplete(orderId, maxAttempts = 60) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    console.log(`Checking order status (${attempt}/${maxAttempts})...`);

    const order = await checkOrderStatus(orderId);

    // Order is complete
    if (["FULFILLED", "PARTIALLY_FILLED", "REFUNDED"].includes(order.status)) {
      console.log(`Order completed: ${order.status}`);
      return order;
    }

    // Wait 5 seconds before next check
    if (attempt < maxAttempts) {
      await new Promise((resolve) => setTimeout(resolve, 5000));
    }
  }

  throw new Error("Order still processing after timeout");
}

// Usage
try {
  const order = await pollOrderUntilComplete("6901616fe9e88196b4eb64b3");

  if (order.status === "FULFILLED") {
    console.log("Success! Cards:", order.cards);
  } else if (order.status === "PARTIALLY_FILLED") {
    console.log(
      `Partial delivery: ${order.fulfilled_quantity}/${order.quantity}`
    );
  } else {
    console.log("Order failed and refunded");
  }
} catch (error) {
  console.error("Error:", error.message);
}

import time

def poll_order_until_complete(order_id, max_attempts=60):
    for attempt in range(1, max_attempts + 1):
        print(f"Checking order status ({attempt}/{max_attempts})...")

        order = check_order_status(order_id)

        # Order is complete
        if order['status'] in ['FULFILLED', 'PARTIALLY_FILLED', 'REFUNDED']:
            print(f"Order completed: {order['status']}")
            return order

        # Wait 5 seconds before next check
        if attempt < max_attempts:
            time.sleep(5)

    raise Exception('Order still processing after timeout')

# Usage
try:
    order = poll_order_until_complete('6901616fe9e88196b4eb64b3')

    if order['status'] == 'FULFILLED':
        print(f"Success! Cards: {len(order['cards'])}")
    elif order['status'] == 'PARTIALLY_FILLED':
        print(f"Partial delivery: {order['fulfilled_quantity']}/{order['quantity']}")
    else:
        print('Order failed and refunded')
except Exception as e:
    print(f"Error: {e}")

<?php

function pollOrderUntilComplete($orderId, $apiKey, $maxAttempts = 60) {
    for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
        echo "Checking order status ({$attempt}/{$maxAttempts})...\n";

        $order = checkOrderStatus($orderId, $apiKey);

        // Order is complete
        $finalStates = ['FULFILLED', 'PARTIALLY_FILLED', 'REFUNDED'];
        if (in_array($order['status'], $finalStates)) {
            echo "Order completed: {$order['status']}\n";
            return $order;
        }

        // Wait 5 seconds before next check
        if ($attempt < $maxAttempts) {
            sleep(5);
        }
    }

    throw new Exception('Order still processing after timeout');
}

// Usage
try {
    $order = pollOrderUntilComplete('6901616fe9e88196b4eb64b3', getenv('API_KEY'));

    if ($order['status'] === 'FULFILLED') {
        echo "Success! Cards: " . count($order['cards']) . "\n";
    } elseif ($order['status'] === 'PARTIALLY_FILLED') {
        echo "Partial delivery: {$order['fulfilled_quantity']}/{$order['quantity']}\n";
    } else {
        echo "Order failed and refunded\n";
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

Gestion des différents résultats

function handleOrderResult(order) {
  switch (order.status) {
    case "FULFILLED":
      console.log(`✅ Success: ${order.fulfilled_quantity} cards delivered`);
      console.log(`Cost: ${order.fulfilled_amount} DA`);

      // Process each card
      order.cards.forEach((card, index) => {
        console.log(`Card ${index + 1}: ${card.value}`);
        // Encrypt and deliver to customer
      });
      break;

    case "PARTIALLY_FILLED":
      console.log(
        `⚠️ Partial: ${order.fulfilled_quantity}/${order.quantity} cards`
      );
      console.log(`Charged: ${order.fulfilled_amount} DA`);

      const refund =
        (order.quantity - order.fulfilled_quantity) * order.price_per_card;
      console.log(`Refunded: ${refund} DA`);

      // Deliver available cards
      order.cards.forEach((card) => {
        console.log(`Delivered: ${card.value}`);
      });
      break;

    case "REFUNDED":
      console.log("❌ Order failed - full refund issued");
      break;
  }
}

def handle_order_result(order):
    if order['status'] == 'FULFILLED':
        print(f"✅ Success: {order['fulfilled_quantity']} cards delivered")
        print(f"Cost: {order['fulfilled_amount']} DA")

        # Process each card
        for i, card in enumerate(order['cards']):
            print(f"Card {i + 1}: {card['value']}")
            # Encrypt and deliver to customer

    elif order['status'] == 'PARTIALLY_FILLED':
        print(f"⚠️ Partial: {order['fulfilled_quantity']}/{order['quantity']} cards")
        print(f"Charged: {order['fulfilled_amount']} DA")

        refund = (order['quantity'] - order['fulfilled_quantity']) * order['price_per_card']
        print(f"Refunded: {refund} DA")

        # Deliver available cards
        for card in order['cards']:
            print(f"Delivered: {card['value']}")

    elif order['status'] == 'REFUNDED':
        print('❌ Order failed - full refund issued')

<?php

function handleOrderResult($order) {
    switch ($order['status']) {
        case 'FULFILLED':
            echo "✅ Success: {$order['fulfilled_quantity']} cards delivered\n";
            echo "Cost: {$order['fulfilled_amount']} DA\n";

            // Process each card
            foreach ($order['cards'] as $index => $card) {
                echo "Card " . ($index + 1) . ": {$card['value']}\n";
                // Encrypt and deliver to customer
            }
            break;

        case 'PARTIALLY_FILLED':
            echo "⚠️ Partial: {$order['fulfilled_quantity']}/{$order['quantity']} cards\n";
            echo "Charged: {$order['fulfilled_amount']} DA\n";

            $refund = ($order['quantity'] - $order['fulfilled_quantity']) * $order['price_per_card'];
            echo "Refunded: {$refund} DA\n";

            // Deliver available cards
            foreach ($order['cards'] as $card) {
                echo "Delivered: {$card['value']}\n";
            }
            break;

        case 'REFUNDED':
            echo "❌ Order failed - full refund issued\n";
            break;
    }
}
?>

Exemple complet d’interrogation

async function processOrder(productId, typeId, quantity) {
  try {
    // 1. Passer la commande
    console.log("Placing order...");
    const order = await placeOrder(productId, typeId, quantity);
    console.log(`Order placed: ${order.orderId}`);

    // 2. Interroger jusqu'à l'achèvement
    console.log("Waiting for fulfillment...");
    const result = await pollOrderUntilComplete(order.orderId);

    // 3. Traiter le résultat
    handleOrderResult(result);

    return result;
  } catch (error) {
    console.error("Order processing failed:", error.message);
    throw error;
  }
}

// Usage
await processOrder("507f1f77bcf86cd799439011", "type_001", 2);

Bonnes pratiques

Interroger toutes les 5 secondes

Équilibre entre réactivité et charge API

Définir un délai d'expiration

Arrêter l’interrogation après 5 minutes (60 tentatives)

Gérer tous les états

Traiter FULFILLED, PARTIALLY_FILLED et REFUNDED

Tester d'abord

Utiliser le mode sandbox avec TEST_REFUND et TEST_PARTIAL

Étapes suivantes

Livraison sécurisée

Chiffrer et livrer les cartes aux clients

Passer des commandes

Soumettre des commandes avec validation

Référence API

Documentation complète de l’endpoint

​Vue d’ensemble

​Référence API

GET /v3/gift-cards/checkOrder/{orderId}

​Valeurs de Statut de Commande

​Tests en mode Sandbox

Tester une commande échouée

Tester un succès partiel

​Vérification de statut de base

​Exemples de réponse

​En cours de traitement

​Exécuté (Succès)

​Partiellement exécuté

​Implémentation de l’interrogation simple

​Gestion des différents résultats

​Exemple complet d’interrogation

​Bonnes pratiques

Interroger toutes les 5 secondes

Définir un délai d'expiration

Gérer tous les états

Tester d'abord

​Étapes suivantes

Livraison sécurisée

Passer des commandes

Référence API

Vue d’ensemble

Référence API

Valeurs de Statut de Commande

Tests en mode Sandbox

Vérification de statut de base

Exemples de réponse

En cours de traitement

Exécuté (Succès)

Partiellement exécuté

Implémentation de l’interrogation simple

Gestion des différents résultats

Exemple complet d’interrogation

Bonnes pratiques

Étapes suivantes