Deux façons d'intégrer Flowmerce à votre site e-commerce custom. Choisissez celle qui correspond à votre besoin.
Toutes les requêtes API Flowmerce sont authentifiées via une clé API serveur. Deux formats sont acceptés selon l'endpoint :
# Format Bearer (recommandé)
Authorization: Bearer flk_votre_cle_api
# OU format x-api-key (compatible /api/claims/create)
x-api-key: flk_votre_cle_apiFLOWMERCE_API_KEY). Aucun préfixe NEXT_PUBLIC_,VITE_, etc.Générez et gérez vos clés depuis votre tableau de bord. Maximum 5 clés actives par compte. La valeur brute n'est affichée qu'une seule fois — copiez-la immédiatement.
Deux scénarios selon que vous voulez garder la main sur le formulaire de retour ou que Flowmerce héberge tout pour vous.
Le client remplit votre propre formulaire (sur votre site). Votre backend reçoit la demande, vérifie qu'elle est légitime, puis appelle Flowmerce. La clé API reste toujours côté serveur.
[Navigateur client]
│ POST /api/orders/return (votre endpoint local)
▼
[Votre backend]
│ 1. Vérifie que la commande appartient bien à l'utilisateur
│ 2. Évite les doublons (claim déjà existant ?)
│ 3. Mappe les champs vers le format Flowmerce
│
│ POST /api/claims/create
│ x-api-key: flk_xxx
▼
[Flowmerce]
│ 4. Validation, rate limit, vérification policy
│ 5. Création du claim + appel ML synchrone
│ 6. Auto-approve / auto-reject / pending
│ 7. Email automatique au client
│
│ 201 { claim_id, status, message }
▼
[Votre backend]
│ 8. Sauvegarde claim_id pour traçabilité
│
│ 200 OK
▼
[Navigateur client]
9. Affiche "Demande enregistrée" au clienthttps://flowmerce.app/api/claims/create| Champ | Type | Description |
|---|---|---|
shop_idrequis | string | Identifiant unique de votre boutique (libre, ex: ma-boutique) |
order_idrequis | string | Identifiant de la commande dans votre système |
customer_namerequis | string | Nom complet du client |
customer_emailrequis | string | Email du client (format vérifié) |
product_namerequis | string | Nom du produit concerné |
reasonrequis | enum | DEFECTIVE | WRONG_ITEM | DESCRIPTION | CHANGE_MIND |
desired_resolutionrequis | enum | EXCHANGE | REFUND | REPAIR (choix du client) |
descriptionrequis | string | Description du problème (10–2000 caractères, pas de HTML) |
customer_phone | string | Téléphone client (renforce la détection de fraude) |
customer_age | number | Âge du client |
customer_gender | string | Genre du client |
customer_wilaya | string | Wilaya (région) du client |
product_category | string | Catégorie produit (ex: Electronics, Clothing) |
product_price | number | Prix unitaire en DA |
product_quantity | number | Quantité commandée |
order_total | number | Montant total de la commande en DA |
shipping_cost | number | Frais de livraison en DA |
payment_method | string | Mode de paiement (Cash on Delivery, Card…) |
shipping_method | string | Mode de livraison (Home Delivery, Standard…) |
order_date | string | Date de commande ISO-8601 (calcule les jours écoulés) |
order_address | string | Adresse de livraison |
source | string | Marquer la source ("hosted_page" si tunnel hébergé) |
{
"success": true,
"claim_id": "clxxxxxxxxxxxxxx",
"status": "APPROVED", // ou PENDING / REJECTED
"customer_past_returns": 2,
"message": "Votre demande de retour a été enregistrée et approuvée automatiquement."
}# Appelé depuis VOTRE backend (jamais depuis le navigateur du client)
curl -X POST https://flowmerce.app/api/claims/create \
-H "x-api-key: flk_votre_cle_api" \
-H "Content-Type: application/json" \
-d '{
"shop_id": "ma-boutique",
"order_id": "CMD-123",
"customer_name": "Ahmed Benali",
"customer_email": "ahmed@exemple.com",
"product_name": "Nike Air Max",
"reason": "DEFECTIVE",
"desired_resolution": "REFUND",
"description": "Produit reçu avec un défaut visible sur la semelle."
}'| Status | Code | Quand | Action recommandée |
|---|---|---|---|
| 400 | VALIDATION | Champ requis manquant, email invalide, HTML détecté, raison/résolution non reconnue | Corriger le payload côté votre backend |
| 401 | AUTH | Clé API invalide, désactivée, ou vendor non APPROVED | Vérifier la clé dans /dashboard/api-keys |
| 409 | DUPLICATE | Un claim existe déjà pour (vendorId, order_id) | Afficher "un retour existe déjà" au client |
| 422 | DELAY_EXCEEDED | Délai de retour dépassé (selon return policy vendor) | Afficher la raison au client (champ `extra.policy_days`) |
| 422 | NON_REFUNDABLE_CATEGORY | Catégorie produit configurée comme non remboursable | Proposer un échange à la place |
| 429 | RATE_LIMIT | 3 demandes/client/jour ou trop de tentatives pour la même commande | Demander au client de réessayer plus tard |
| 503 | ML_DOWN | Serveur ML temporairement indisponible (claim créé en PENDING) | Le claim sera rejoué automatiquement par le cron |
✓ FLOWMERCE_API_KEY uniquement dans vos variables d'env serveur
✓ Vérifier que la commande appartient à l'utilisateur connecté avant d'appeler Flowmerce
✓ Échapper / valider les inputs (longueur, pas de HTML — Flowmerce le fait aussi)
✓ Sauvegarder claim_id côté votre BDD pour le suivi
✓ Tester avec une clé de dev avant la prod ; révoquer si compromise
Un plugin Shopify officiel Flowmerce est en cours de développement. Il permettra d'intégrer Flowmerce en un clic, sans écrire une seule ligne de code.
Créez votre compte et générez votre première clé API en moins de 2 minutes. Aucune carte bancaire requise.