Passer au contenu principal

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

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

La commande est en cours de traitement. Continuez l’interrogation. La plupart des commandes se résolvent en 30 secondes.
Succès ! Toutes les cartes livrées. fulfilled_quantity === quantity. Cartes disponibles dans le tableau cards.
Succès partiel. Certaines cartes livrées, le reste annulé. fulfilled_quantity < quantity. Remboursement partiel émis automatiquement.
É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}`);
}

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);
}

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;
  }
}

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