API eFacture Connect

Intégrez la facture électronique tunisienne dans votre ERP en quelques minutes. Envoyez du JSON, recevez un XML TEIF v1.8.8 signé (XAdES) et un PDF avec QR code, prêts à être déposés chez TunisieTradeNet.

Premier appel en 30 secondes

Copiez la commande à droite dans votre terminal pour tester l'API en mode sandbox. Remplacez sk_test_xxx par votre clé reçue par email après inscription.

Vous recevrez en retour un XML réellement signé (environnement sandbox) et un PDF, exactement comme en production. Aucun crédit n'est consommé en mode test.

Authentification

L'API utilise des clés API passées dans le header X-Api-Key. Chaque requête doit inclure une clé valide.

Comptes et clients

Un compte développeur peut gérer plusieurs clients (une intégration par entreprise finale). Vous créez et configurez vos clients depuis votre espace développeur, section « Mes clients ».

Test vs Production

Passer en production ne nécessite aucun changement de code : remplacez simplement sk_test_xxx par sk_live_xxx.

SEAL vs DigiGo

Deux modes de signature selon votre cas d'usage. Vous pouvez basculer à la volée via le champ method dans la requête.

Gestion des erreurs

L'API utilise les codes HTTP standards et retourne un payload JSON normalisé. Toutes les erreurs ont la même forme :

Debug en mode test (sk_test_ / ck_test_)

En mode test uniquement, les erreurs SIGNING_FAILED retournent un champ error.details.debug contenant le message technique sous-jacent, et GET /einvoices/{id} inclut un bloc debug (état de la signature, erreur de vérification éventuelle) tant que la facture est en cours. Ces champs ne sont jamais présents en mode production (clés live), pour éviter toute fuite d'information.

{
  "success": false,
  "data": null,
  "error": {
    "code": "SIGNING_FAILED",
    "message": "La signature électronique a échoué. Veuillez réessayer.",
    "details": {
      "debug": "HTTP 401 Unauthorized"
    }
  }
}

Tableau de résolution des erreurs SIGNING_FAILED

Si vous rencontrez un SIGNING_FAILED, consultez ci-dessous le contenu de error.details.debug pour identifier la cause :

Valider un payload

Valide la structure du payload sans signer ni déposer chez TTN. Idéal pour debugger votre intégration. Aucun crédit consommé même en mode live.

Paramètres requis

Signer + déposer (mode SEAL)

Synchrone (~5 secondes). Signature automatique via cachet électronique serveur, dépôt immédiat chez TTN. La réponse contient directement le XML signé (base64), le PDF avec QR code (base64) et la référence TTN. Clé requise : celle du client concerné (ck_) - une clé développeur reçoit 403 DEVELOPER_KEY_NOT_ALLOWED.

Codes de réponse

Préparer une signature (mode DigiGo)

Asynchrone. Génère le TEIF, crée une transaction de signature et retourne une signing_url vers laquelle vous redirigez le client final (signature à distance ou clé USB locale). Celui-ci signe, puis est redirigé vers votre return_url. Clé requise : celle du client concerné (ck_) - une clé développeur reçoit 403 DEVELOPER_KEY_NOT_ALLOWED. Le signing_id retourné (format sg_...) sert au suivi via GET /einvoices/{signing_id}.

Récupérez le résultat final via :

• Polling : GET /einvoices/{signing_id} jusqu'à status: validated
• Webhook (recommandé) : nous appelons votre serveur dès que la signature est validée

Paramètres spécifiques DigiGo

Récupérer une e-facture

Retourne le statut et les fichiers d'une e-facture. Utilisé principalement pour le polling après POST /einvoices/prepare. Seuls le client propriétaire de la facture et son développeur parent peuvent la consulter : toute autre clé reçoit 403 PERMISSION_DENIED.

Cycle de vie

draft → teif_generated → pending_signature → signed → submitted_ttn → validated
                                                                                            ↘ rejected

Deux étages décrits séparément : signature et ttn

Le champ status est la synthèse globale du cycle. Un rejected peut signifier deux choses très différentes : signature refusée, ou facture signée mais dépôt TTN refusé. La réponse contient donc deux blocs dédiés :

{
  "status": "rejected",
  "signature": {
    "status": "signed",                  // pending | signed | rejected
    "signed_xml_available": true
  },
  "ttn": {
    "status": "rejected",                // not_reached | submitted | validated | rejected
    "reference": null,
    "error": { "code": "TTN_DEPOSIT_FAILED", "message": "Erreur TTN: ..." }
  }
}

En cas de dépôt refusé (ttn.status: rejected) : le XML signé reste disponible, corrigez la cause (ex. identifiants TTN du client) puis ré-émettez la facture (nouveau /prepare ou /process). Un rejet est final pour ce signing_id.

Solde de crédits

Retourne le solde courant de crédits, le total utilisé et le total acheté.

Gestion des clients (API)

Un compte développeur peut gérer ses clients directement depuis son ERP, via l'API. Chaque client possède sa configuration TTN (sandbox et production), sa méthode de signature, son plafond de crédits et ses propres clés API.

Confidentialité des secrets

Les mots de passe TTN et SFTP ne sont jamais renvoyés en clair. En lecture, ils sont masqués par des astérisques dont le nombre correspond à la longueur enregistrée (ex. "password": "********"). Vous pouvez les écrire (création / modification) mais jamais les relire.

Champs d'un client

En lecture, chaque client renvoie aussi son suivi : credits (cap, used, remaining) et stats (total, validated, rejected). De quoi afficher un mini tableau de bord par client dans votre ERP.

Creer un client

Crée un client et retourne ses clés API (ck_test_ / ck_live_). Ces clés restent récupérables à tout moment via GET /clients/{id}. Ajoutez "provision": "sandbox" (ou production / both) pour créer en même temps le compte de signature du client.

POST /api/v1/clients
X-Api-Key: sk_live_VOTRE_CLE_DEVELOPPEUR
Content-Type: application/json

{
  "name": "Societe ABC",
  "matricule": "1234567AAM000",
  "signer_method": "seal",
  "signer_email": "signataire@societe-abc.tn",
  "submission_channel": "soap",
  "credit_cap": 500,
  "ttn": {
    "sandbox": { "login": "abc_test", "password": "secret1" },
    "prod":    { "login": "abc_prod", "password": "secret2" }
  }
}

Reponse (201) :

{
  "success": true,
  "data": {
    "id": "018f...-....",
    "name": "Societe ABC",
    "matricule": "1234567AAM000",
    "signer_method": "seal",
    "signer_email": "signataire@societe-abc.tn",
    "submission_channel": "soap",
    "active": true,
    "live_enabled": true,
    "credits": { "cap": 500, "used": 0, "remaining": 500 },
    "stats": { "total": 0, "validated": 0, "rejected": 0 },
    "ttn": {
      "sandbox": { "login": "abc_test", "password": "*******" },
      "prod":    { "login": "abc_prod", "password": "*******" }
    },
    "keys": { "test": "ck_test_...", "live": "ck_live_..." }
  }
}

Si vous avez demandé un provision, la réponse contient un bloc provisioning par environnement :

"provisioning": {
  "sandbox": { "success": true,  "message": "Compte de signature cree (environnement test)." },
  "production": { "success": false, "message": "L'organisation existe deja chez le prestataire..." }
}

La création du client réussit même si le provisioning échoue : corrigez les accès puis relancez via PATCH avec provision. Utilisez ensuite la clé du client (keys.live / keys.test) pour émettre ses e-factures via /einvoices/process ou /einvoices/prepare.

Lister les clients

Retourne tous vos clients (secrets masqués) avec leurs crédits et statistiques, plus le solde de votre portefeuille partagé.

{
  "success": true,
  "data": {
    "clients": [
      { "id": "...", "name": "Societe ABC",
        "credits": { "cap": 500, "used": 180, "remaining": 320 },
        "stats": { "total": 200, "validated": 190, "rejected": 10 }, ... }
    ],
    "wallet": { "balance": 4200, "total_purchased": 5000 }
  }
}

Lire un client

Retourne un client : configuration, crédits, statistiques et ses clés API (keys.test / keys.live, préfixe ck_). Les mots de passe TTN/SFTP restent masqués, mais les clés API du client sont renvoyées en clair pour vous permettre de les récupérer à tout moment.

Modifier un client

Mise à jour partielle : seuls les champs envoyés sont modifiés. Envoyez uniquement un mot de passe TTN/SFTP pour le remplacer ; omettez-le pour le conserver. Ajoutez "provision" pour recréer ou mettre à jour le compte de signature.

PATCH /api/v1/clients/018f...
X-Api-Key: sk_live_VOTRE_CLE_DEVELOPPEUR

{ "credit_cap": 800, "submission_channel": "sftp",
  "sftp": { "prod": { "host": "sftp.ttn.tn", "port": 22, "username": "abc",
                      "password": "xxx", "in_dir": "/in", "out_dir": "/out" } } }

Supprimer un client • Régénérer les clés

Supprime le client.

Régénère les clés API du client (les anciennes cessent immédiatement de fonctionner). Les nouvelles clés sont retournées, et restent récupérables via GET /clients/{id}.

Webhooks

Configurez une URL HTTPS et nous vous notifions dès qu'une e-facture passe à validated ou rejected. Évite le polling.

Événements envoyés : einvoice.validated, einvoice.rejected, et pour le canal SFTP l'événement intermédiaire einvoice.submitted (facture déposée, en attente de la réponse TTN).

Vérification HMAC

Chaque webhook inclut un header X-Efacture-Signature au format sha256=<hex>. Calculez l'HMAC-SHA256 du body brut avec votre webhook secret et comparez avec le header.

Politique de retry

• Livraison asynchrone, jusqu'à 3 nouvelles tentatives avec backoff exponentiel en cas d'échec
• Considéré réussi si vous répondez 2xx (tout autre code déclenche un retry)
• Timeout de 10 s par tentative ; répondez vite et traitez en tâche de fond si besoin
• Idempotence : le même signing_id peut être notifié plusieurs fois

Rate limits

Par défaut : 60 requêtes par minute par clé API. Sliding window, comptage atomique. Configurable sur demande pour les volumes élevés.

En cas de dépassement : réponse 429 RATE_LIMIT. Implémentez un backoff exponentiel côté client.

Objet Invoice

Exemple complet (tous les champs)

Payload de référence regroupant l'ensemble des champs supportés : coordonnées structurées vendeur/client (MF, adresse, ville, code postal, gouvernorat, pays, téléphone, e-mail), TVA multi-taux par ligne, taux par défaut, ligne exonérée, timbre fiscal, retenue à la source et couleur du PDF. Ce payload passe la validation sans erreur.

Notes :

• method : seal pour /einvoices/process (signature automatique), digigo pour /einvoices/prepare (signature par le client).
• Particulier : remplacez buyer.tax_id par buyer.id_number (CIN/passeport) → le PDF affiche « CIN » au lieu de « MF ».
• default_vat_rate s'applique aux lignes sans vat_rate ; chaque ligne peut le surcharger (TVA différente par ligne). Un récap TVA par taux est généré automatiquement.
• stamp_duty est présent par défaut (1,000 TND) - mettez false pour le retirer.
• brand_color et les coordonnées ne servent au rendu que pour le PDF généré (mode B). En mode A (pdf_base64), c'est votre PDF qui fait foi.
• Validez d'abord via POST /einvoices/validate (0 crédit) : tout champ manquant/invalide est retourné dans error.details.
• Alias de champs acceptés (vendeur/client) : name=nom/raison_sociale, tax_id=matricule_fiscal/mf, address=adresse/rue, postal_code=code_postal/cp, city=ville, governorate=gouvernorat, country=pays, phone=tel. L'address peut aussi être un objet { street, city, postal_code }.

Récap TVA produit pour cet exemple :

Retenue à la source (RS)

La retenue à la source est l'impôt que l'acheteur retient sur le paiement et reverse à l'État pour le compte du vendeur. Elle ne modifie ni le HT, ni la TVA, ni le Total TTC : elle réduit seulement le Net à payer.

• Optionnelle : envoyez withholding_tax_rate uniquement quand il y a une retenue. Omettez le champ (ou mettez 0) pour ne pas en appliquer - la ligne « Retenue à la source » n'apparaît alors pas et le Net à payer = Total TTC. Aucun autre indicateur n'est requis.
• Base de calcul = TTC hors timbre (HT + TVA).
• Taux courants : 1.5 (achats biens/services > 1000 DT TTC), 3 (honoraires régime réel), 10 (honoraires/loyers/commissions), 15, 20…

Exemple 1 - avec retenue à la source (1,5 %)

Exemple 2 - sans retenue à la source

Il suffit de ne pas envoyer withholding_tax_rate (ou de mettre 0) :

PDF de la facture

Le PDF est le document visuel présenté au signataire et archivé après signature (le QR de signature y est apposé automatiquement). Deux modes sont possibles :

Recommandation : si votre ERP produit déjà des factures PDF, envoyez-les via pdf_base64 pour conserver votre charte graphique. Contraintes :

• Encodage base64 du contenu binaire du PDF (préfixe data:application/pdf;base64, toléré mais optionnel).
• Doit être un PDF valide (commence par %PDF).
• Taille maximale : 10 Mo (avant encodage).
• Si le PDF fourni est invalide ou absent, le mode B (génération) prend automatiquement le relais - aucun échec de signature.

Objet Error

Format normalisé pour toutes les erreurs :

Payload Webhook

Envoyé par notre serveur à votre URL configurée lorsqu'une e-facture change de statut final :

Header de signature : X-Efacture-Signature: sha256=<hex> calculé en HMAC-SHA256 du body brut avec votre webhook secret.