API et sandbox ACAPI
Cette architecture s’adresse aux éditeurs logiciels, intégrateurs, équipes ERP, grands comptes et responsables SI qui souhaitent détecter les écarts avant une transformation ou un échange avec un système cible.
Rôle de l’API
Une API de conformité reçoit une facture structurée, vérifie ses champs et applique des règles cohérentes. Elle retourne ensuite un résultat structuré que le logiciel peut afficher, journaliser ou utiliser dans un circuit de correction.
Le rapport doit distinguer les erreurs bloquantes des avertissements. Une erreur empêche la suite du flux ; un avertissement signale un point à revoir sans forcément bloquer. Les recommandations expliquent l’action attendue afin que les équipes métier et techniques partagent le même diagnostic.
Cette étape intervient avant une transformation ou transmission. Elle réduit les allers-retours, mais ne remplace ni le mapping métier, ni les validations comptables, ni la confirmation des modalités officielles applicables.
ACAPI applique le profil ma-2026-draft pour une validation préparatoire. Il retourne des erreurs structurées, avertissements et recommandations, puis indique si le document est prêt pour un exemple de transformation UBL. La transformation n’est demandée qu’en l’absence d’erreur bloquante.
Le profil ma-2026-draft est préparatoire et ne constitue pas une validation ou une acceptation officielle de la DGI.
L’entrée illustre quelques champs de facture. La réponse montre une erreur de total et bloque la préparation UBL. Ces exemples sont pédagogiques et ne constituent pas la documentation contractuelle définitive de l’API.
{
"documentType": "INVOICE",
"invoiceNumber": "FAC-2026-001",
"currency": "MAD",
"seller": { "ice": "001525255000083" },
"buyer": { "ice": "002345678000041" },
"totalsProvided": {
"taxExclusiveAmount": 1000,
"taxAmount": 200,
"taxInclusiveAmount": 1200
}
}{
"status": "FAIL",
"ruleset": "ma-2026-draft",
"errors": [
{
"code": "MA_INVALID_TOTAL_TTC",
"message": "Le total TTC ne correspond pas aux montants calculés."
}
],
"warnings": [],
"canGenerateUbl": false
}L’application cliente conserve son propre identifiant métier de facture et son mécanisme de traçabilité. Le contrôle ACAPI s’insère sans remplacer l’historique du système source.
Les systèmes nomment différemment les colonnes, stockent parfois les montants comme texte et mélangent les formats de date. Un taux peut apparaître comme 20, 0.20 ou 20 %, la devise rester implicite, les parties être inversées ou une formule Excel ne pas être exportée. Le contrat interne doit lever ces ambiguïtés avant l’appel.
| Donnée source | Risque | Normalisation recommandée |
|---|---|---|
| ICE Client | Espaces ou longueur incorrecte | Chaîne normalisée et contrôlée |
| TVA | Taux ou montant ambigu | Séparer taux et montant |
| Total TTC | Formule Excel non exportée | Exporter la valeur calculée |
| Date facture | Formats locaux différents | Format ISO dans le contrat interne |
| Devise | Valeur vide ou implicite | Valeur explicite contrôlée |
Ces exemples sont pédagogiques ; le mapping réel dépend du contrat de données et des outils du projet.
Un intégrateur ne doit pas se limiter à « facture invalide ». Un retour utile associe code, sévérité, champ, message utilisateur, valeur reçue, recommandation, version du ruleset et, si le système en dispose, identifiant de corrélation.
Le nom exact des champs et des codes peut évoluer selon le contrat réel de l’API. L’exemple ci-contre est uniquement pédagogique.
{
"code": "MA_BUYER_SELLER_ICE_MATCH",
"severity": "ERROR",
"field": "buyer.ice",
"message": "L’ICE acheteur ne doit pas être identique à l’ICE vendeur.",
"recommendation": "Vérifier le mapping des parties vendeur et acheteur."
}Générez un identifiant métier stable, conservez la version envoyée et journalisez chaque résultat avec le ruleset utilisé. Une correction doit produire une nouvelle tentative reliée à la précédente, sans écraser silencieusement l’ancien rapport ni doubler un traitement accidentel.
Cette recommandation d’architecture ne suppose pas qu’ACAPI expose actuellement une clé d’idempotence native.
Démarrez avec quelques factures, mesurez temps de réponse et taux d’erreur, limitez la concurrence et gérez les timeouts. Prévoyez les reprises, séparez erreurs techniques et métier, et ne relancez pas indéfiniment une facture invalide.
Surveillez quotas et rate limits selon le contrat de sandbox, puis augmentez progressivement le volume sans supposer une performance non mesurée.
Contrôler un échantillon avant de connecter le flux complet.
Mapper les colonnes disponibles vers une structure de facture cohérente.
Afficher des retours structurés dans le parcours utilisateur du logiciel.
Exécuter des scénarios valides, invalides et limites sans exposer de clé.
Détecter les écarts avant leur génération ou leur échange.
Transformer les codes techniques en actions compréhensibles et traçables.
Sécurité
Limites
FAQ technique
Non. La clé ACAPI reste côté serveur. Le navigateur appelle une route serveur Next.js, qui authentifie ensuite la demande vers ACAPI sans exposer le secret.
Non. Il s’agit d’un profil préparatoire destiné à tester les données et les flux. Il ne constitue pas une validation ou une acceptation officielle de la DGI.
Le serveur revalide la facture et ne demande une transformation que si aucune erreur bloquante ne subsiste. La valeur canGenerateUbl du navigateur n’est jamais considérée comme une autorisation.
Cette page ne promet pas de fonction batch publique. Les besoins de volume, de supervision et d’orchestration doivent être qualifiés pour chaque projet.
Non. Ils sont volontairement simplifiés et pédagogiques. Le contrat de données, l’authentification, les champs et les réponses définitives sont à cadrer dans la documentation du projet.
Non. Elle sert à qualifier les données et scénarios. Le mapping métier, la sécurité, la charge, les reprises et les paramètres réels doivent encore être validés.