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)
// 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