# KoriFlow — Documentation Complète pour Agents IA & Développeurs

> Version : 1.0.0
> Spécification OpenAPI : https://koriflow.com/openapi.json
> Documentation LLMs courte : https://koriflow.com/llms.txt
> Portail Développeur : https://koriflow.com/developers

## 1. Vue d'ensemble de la plateforme

KoriFlow est une infrastructure logicielle e-commerce intégrée (SaaS e-commerce) conçue pour résoudre les défis structurels du commerce électronique en Afrique subsaharienne :
- **Fragmentations de paiement** : Agrégation native des portefeuilles Mobile Money (Wave, Orange Money, MTN MoMo, Moov Money) et cartes bancaires avec reversements automatisés.
- **Cash on Delivery (COD)** : Prise en charge du paiement à la livraison avec processus de vérification et de confirmation téléphonique/WhatsApp via l'agent IA Kori pour limiter les refus de colis.
- **Marketing & Publicité Meta** : Automatisation du cycle publicitaire Meta Ads (création de visuels et accroches publicitaires par IA, publication via l'API Marketing Meta, suivi des conversions Pixel/CAPI, synchronisation quotidienne des dépenses).
- **Ressources numériques** : Vente et livraison sécurisée de fichiers numériques (formations, ebooks, templates) avec liens de téléchargement horodatés et uniques.

## 2. Négociation de contenu pour agents (acceptmarkdown.com)

KoriFlow respecte le protocole acceptmarkdown.com :
- Tout agent ou robot formulant une requête avec `Accept: text/markdown` sur la page d'accueil reçoit une version Markdown structurée, propre et directement traitable par les LLMs.
- En-tête de variation : chaque réponse inclut systématiquement `Vary: Accept` pour garantir une mise en cache respectueuse du format demandé.
- Pages d'erreur 404 : lorsqu'une URL inexistante est requise avec `Accept: text/markdown`, le serveur répond avec un code HTTP 404 strict et un corps de texte en Markdown détaillant l'erreur et listant les liens d'orientation (sitemap, documentation, OpenAPI).

## 3. Format des réponses d'erreur (JSON)

Toutes les requêtes adressées aux endpoints système ou non trouvées renvoient des erreurs normalisées en JSON :
```json
{
  "error": {
    "code": "STRING_IDENTIFIER",
    "message": "Human readable message explaining what went wrong.",
    "hint": "Actionable resolution steps for the agent or developer."
  }
}
```

Codes d'erreur usuels :
- `ENDPOINT_NOT_FOUND` (404) : La ressource demandée n'existe pas.
- `UNAUTHORIZED` (401) : Authentification requise.
- `RATE_LIMITED` (429) : Trop de requêtes par adresse IP.
- `SERVICE_UNAVAILABLE` (503) : Maintenance ou indisponibilité temporaire.

## 4. Politique d'accès API & Intégrations

KoriFlow est une plateforme logicielle propriétaire sans API publique ouverte aux développeurs tiers.
- Toutes les opérations (création de boutique, gestion de catalogue, soumission de commandes, encaissements et retraits) s'effectuent exclusivement via les boutiques en ligne hébergées et le tableau de bord vendeur sécurisé.
- Seul le contrôle de santé opérationnel (`GET /api/sante`) est documenté publiquement pour les sondes de disponibilité.
- Toute requête sur un point d'entrée non reconnu renvoie une réponse JSON 404 explicite.

## 5. Couverture géographique et devises

KoriFlow traite nativement les paiements en Franc CFA (XOF / XAF) dans les pays suivants :
- **Côte d'Ivoire (CI)** : Wave, Orange Money, MTN MoMo, Moov Money.
- **Sénégal (SN)** : Wave, Orange Money, Free Money.
- **Cameroun (CM)** : Orange Money, MTN MoMo.
- **Bénin (BJ)** : MTN MoMo, Moov Money.
- **Togo (TG)** : Mixx by Yas, Moov Flooz.
- **Burkina Faso (BF)** : Orange Money, Moov Money.