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 ck_test_xxx par la clé de test d'un de vos clients, affichée dans le portail développeur à sa création (Comptes et clients). Votre clé développeur sk_dev_ n'émet pas de facture.

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 un client en production ne nécessite aucun changement de code : dans son ERP, remplacez simplement sa clé ck_test_xxx par sa clé ck_live_xxx. C'est le préfixe qui décide de l'environnement, il n'y a aucun réglage à changer ailleurs.

Vos clients sont indépendants les uns des autres : l'un peut être en production pendant qu'un autre reste en test. Il n'existe aucun interrupteur global, et votre clé développeur ne change jamais.

Banc d'essai : intégrer avant d'avoir les accès TTN

Obtenir un compte El Fatoora et un certificat prend souvent plusieurs semaines. Sans banc d'essai, aucun appel n'aboutit avant leur arrivée : vous ne pouvez ni tester vos écrans, ni lire nos réponses, ni préparer la gestion des erreurs. Avec le banc d'essai, vous livrez une intégration déjà rodée, et le premier appel réel réussit du premier coup.

L'obtenir

Le banc d'essai s'ouvre sur demande, client par client : écrivez au support en indiquant le client concerné. Il s'applique uniquement aux appels faits avec la clé ck_test_ de ce client. Une clé ck_live_ n'est jamais simulée, quel que soit le réglage : une facture de production ne peut pas sortir d'une simulation.

Ce qui change dans votre code : rien

Mêmes adresses, mêmes corps de requête, mêmes champs de réponse, mêmes codes d'erreur : POST /einvoices/process, POST /einvoices/prepare, GET /einvoices/{signing_id}, POST /einvoices/{signing_id}/resubmit-ttn et POST /einvoices/{signing_id}/cancel. Le jour où les accès de votre client arrivent, nous fermons le banc d'essai : sa clé ck_test_ repart vers le vrai mode test, puis vous passez à sa clé ck_live_. Aucune ligne de votre code ne change.

Pour savoir qu'une réponse vient du banc d'essai, deux marques s'ajoutent, qu'un code existant ignore sans rien casser :

• le champ "simulation": true dans data ;
• l'en-tête HTTP X-eFactureTN-Simulation: 1.

Ne faites dépendre aucune logique métier de ces marques : elles servent à afficher un bandeau « simulation » dans votre interface, pas à suivre un autre chemin. Sinon, votre code de production n'aurait jamais été éprouvé.

Ce que vous recevez

• Le même TEIF que la production : il sort de notre générateur réel. Une erreur dans votre corps de requête se découvre donc au banc d'essai, pas en production.
• xml_base64 : le TEIF avec un bloc de signature Id="SigFrs" construit comme le vrai, mais dont la valeur est le mot SIMULATION. Aucune vérification cryptographique ne l'acceptera.
• pdf_base64 : le PDF de la production, barré sur chaque page de la mention « SIMULATION - SANS VALEUR LÉGALE ».
• Le cachet arrive plus tard, comme chez TTN. Le dépôt ne rend que la référence. Environ 20 secondes après, GET /einvoices/{signing_id} rend ttn.reference_confirmee: true, ttn.qr_png_base64 (QR marqué SIMULATION) et xml_validettn_base64 (le document avec RefTtnVal puis la signature SigTTN, dans l'ordre de TTN). Si votre code lit le QR dans la réponse du dépôt, il ne le trouvera pas au banc d'essai, et il ne le trouverait pas non plus en production : c'est voulu.

La page de signature (DigiGo, clé USB, E-Houwiya)

POST /einvoices/prepare rend une signing_url vers une page de signature simulée. Redirigez-y votre utilisateur comme vous le ferez en production :

• le code PIN est toujours 0000, et aucun SMS n'est envoyé ;
• un autre code affiche « Code PIN incorrect » ; au bout de 3 codes erronés, la signature est bloquée ;
• le bouton « Refuser de signer » simule le refus du signataire : le statut passe à rejected avec le code SIGNATURE_REFUSED ;
• après la signature ou le refus, l'utilisateur revient sur votre return_url, avec efacture_invoice et signing_id, comme en production. Vérifiez ensuite le statut par GET /einvoices/{signing_id} : la redirection ramène, elle n'annonce rien ;
• le lien sert une seule fois et expire au bout de 30 minutes.

Éprouver les erreurs

Les erreurs de votre requête sont refusées comme en production, avec les mêmes codes : un corps invalide rend 422 VALIDATION_FAILED, un matricule mal formé est refusé comme TTN le refuserait. Utilisez aussi POST /einvoices/validate, qui est le même au banc d'essai et en production.

Les pannes que vous ne savez pas provoquer se demandent par l'en-tête X-Simulation-Scenario, sur /process, /prepare ou /resubmit-ttn. Il ne vaut que pour l'appel qui le porte : un renvoi sans l'en-tête suit le parcours normal, ce qui vous permet de dérouler le cas « TTN était indisponible, je renvoie ».

curl -X POST https://efacturetn.com/api/v1/einvoices/process \
  -H "X-Api-Key: ck_test_xxxxxxxxxxxx" \
  -H "X-Simulation-Scenario: ttn_indisponible" \
  -H "Content-Type: application/json" \
  -d @facture.json

Une valeur inconnue est refusée en 422 INVALID_SIMULATION_SCENARIO, avec la liste des valeurs acceptées : la taire vous ferait croire que vous éprouvez un cas alors que vous suivez le parcours normal. Sur une clé qui n'est pas au banc d'essai, l'en-tête est ignoré.

Limites

• Aucune valeur légale. Ne transmettez jamais un PDF ou un XML du banc d'essai à un client final : ce n'est pas une facture.
• 300 factures par période de 24 heures et par client, au-delà : 429 SANDBOX_DAILY_LIMIT.
• Envoyer deux fois le même numéro crée deux factures au banc d'essai, alors qu'en production le second envoi vous rend la première (voir Renvoyer la même facture). Éprouvez ce cas en mode test ou en production.
• Les documents du banc d'essai ne se lisent qu'avec la clé ck_test_ du client, ou avec votre clé développeur.

Modes de signature

Quatre modes de signature selon votre cas d'usage : Entreprise ID (cachet serveur SEAL), DigiGo (PIN + OTP), clé USB (signature locale) et E-Houwiya (Mobile ID). Vous pouvez basculer à la volée via le champ method (seal, digigo, usb ou mobileid) dans la requête.

E-Houwiya (Mobile ID) : le signataire valide depuis son smartphone avec son identité numérique mobile. L'option s'active chez le service de signature pour chaque compte : demandez-la nous avant le premier essai, sans quoi la page de signature ne la propose pas.

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 (clés 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.

Corps de la requête

Le même corps pour /einvoices/validate, /einvoices/process et /einvoices/prepare. Ci-dessous l'essentiel ; tous les champs facultatifs (remises, FODEC, devise, retenue, mentions du PDF…) sont décrits dans Objet Invoice, et un exemple avec tous les champs dans Exemple complet.

Réponse

La réponse porte deux listes. errors : ce qui empêcherait l'émission, et rend valid faux. warnings : des alertes non bloquantes, qui ne changent ni valid ni le comportement de /einvoices/process et /einvoices/prepare. Affichez-les à l'utilisateur, par exemple dans votre bouton « Vérifier la conformité ».

{
  "success": true,
  "data": {
    "valid": true,
    "errors": [],
    "warnings": [
      "suspension.authorization_number : le numéro de l'attestation d'achat en suspension de TVA manque. C'est la pièce qui justifie la suspension en cas de contrôle."
    ]
  }
}

Avertissements rendus aujourd'hui, pour une vente en suspension de TVA :

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.

Corps de la requête

Le même corps pour /einvoices/validate, /einvoices/process et /einvoices/prepare. Ci-dessous l'essentiel ; tous les champs facultatifs (remises, FODEC, devise, retenue, mentions du PDF…) sont décrits dans Objet Invoice, et un exemple avec tous les champs dans Exemple complet.

Codes de réponse

Préparer une signature (DigiGo, clé USB, E-Houwiya)

C'est le point d'entrée de DigiGo, de la clé USB et d'E-Houwiya. POST /einvoices/process ne signe que par cachet serveur : y envoyer "method": "digigo" ou "usb" rend 422 METHOD_REQUIRES_PREPARE.

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

Corps de la requête

Le même corps pour /einvoices/validate, /einvoices/process et /einvoices/prepare. Ci-dessous l'essentiel ; tous les champs facultatifs (remises, FODEC, devise, retenue, mentions du PDF…) sont décrits dans Objet Invoice, et un exemple avec tous les champs dans Exemple complet.

En plus, pour une signature à la main (DigiGo, clé USB, E-Houwiya)

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.

Chaque clé ne lit que son propre environnement. Un document émis en test se consulte avec ck_test_, un document émis en production avec ck_live_ ; l'autre sens répond 403 WRONG_ENVIRONMENT, et il en va de même pour POST /einvoices/{id}/resubmit-ttn. Ce n'est pas une restriction de propriété, le document est bien le vôtre : c'est une séparation des environnements, parce qu'une clé de test se distribue plus largement qu'une clé de production et ne doit pas ouvrir vos documents fiscaux réels. Votre clé développeur sk_dev_ ne désigne aucun environnement et voit les deux, chez tous vos clients.

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.

Après un refus TTN : renvoyer ou re-signer

Quand status = rejected et qu'un document signé existe, l'API dit ce qu'il faut faire, dans ttn.next_action (GET), dans next_action (réponses de /process et /prepare en signed_ttn_rejected). Deux valeurs, pas plus : votre module n'a pas à lire le texte de TTN.

Renvoyer chez TTN sans re-signer

Pour le bouton « Renvoyer TTN » de votre ERP. Quand le dépôt a échoué parce que TTN était indisponible, ou qu'il a été refusé pour une cause extérieure au document, cet appel redépose le document signé tel qu'il a été signé, sans nouvelle signature et sans consommer de crédit.

Quand l'utiliser

Réponse

{
  "success": true,
  "data": {
    "signing_id": "sg_146c4253ea74656dbedc5b57",
    "invoice_number": "FACT-2026-0012",
    "status": "validated",
    "ttn": { "status": "validated", "reference": "TTN-SOAP-1234567", "reference_confirmee": false },
    "ttn_reference": "TTN-SOAP-1234567",
    "resigned": false,
    "credits_consumed": 0,
    "message": "Document signé renvoyé chez TTN, sans nouvelle signature."
  },
  "error": null
}

Annuler une signature en attente

Arrête une signature ouverte par POST /einvoices/prepare (DigiGo, clé USB, E-Houwiya) et pas encore faite. Clé requise : celle du client concerné, sur l'environnement de la facture. Aucun corps de requête.

Aucun crédit n'est consommé par une annulation, et une facture ne peut pas être débitée deux fois : le crédit n'est pris qu'au moment où une signature réelle revient. Si votre utilisateur signe à l'instant même où vous annulez, nous relisons le statut chez le service de signature avant de répondre : la facture est alors traitée comme signée, avec un seul crédit, et le document vous est conservé.

Réponses

Avoirs et notes de débit

Un avoir s’envoie par les mêmes endpoints qu’une facture. Rien de séparé : seuls deux champs changent dans le corps.

{
  "type": "credit_note",
  "original_invoice_number": "F-2026-0042",
  "invoice_number": "AV-2026-0007",
  "date": "2026-09-18",
  "seller": { "name": "MA SOCIETE", "tax_id": "1234567ABM000", "address": "Rue X, Tunis" },
  "buyer":  { "name": "MON CLIENT", "tax_id": "7654321ABM000", "address": "Rue Y, Sfax" },
  "items": [
    { "description": "Retour marchandise", "quantity": 2, "unit_price": 150.000, "vat_rate": 19 }
  ],
  "stamp_duty": false
}

Timbre fiscal et retenue à la source sur un avoir

Ils ne sont jamais répliqués automatiquement depuis la facture d’origine : l’API ne connaît que le corps que vous envoyez. Si votre avoir doit les porter, envoyez-les explicitement (stamp_duty, champs de retenue). Sinon, laissez-les absents.

Documents finaux & QR code

Une e-facture produit quatre documents, et ils n'arrivent pas tous en même temps. C'est la source de confusion la plus fréquente : ne pas confondre ce que vous avez signé avec ce que TTN a validé.

Le QR ne se fabrique pas

Le QR d'une facture El Fatoora est le Cachet Électronique Visible. C'est TTN qui le produit, sous forme d'image PNG, et il est vérifiable par les outils officiels. Un QR reconstruit de votre côté aura la même allure mais échouera à la vérification : l'empreinte et la clé qu'il contient sont calculées par TTN.

Vous n'avez donc rien à calculer. Soit vous utilisez notre pdf_base64, soit vous apposez ttn.qr_png_base64 telle quelle sur votre propre document, sans ré-encodage ni retouche.

Le QR arrive en différé

TTN remplit le bloc <RefTtnVal> après le dépôt : ce bloc est exclu de votre signature, c'est pourquoi TTN peut y écrire sans l'invalider. Nous ré-interrogeons TTN toutes les cinq minutes pour le récupérer.

"ttn": {
  "status": "validated",
  "reference": "073620200053562920196810312",
  "reference_confirmee": true,          // false = accusé de dépôt, pas encore la référence définitive
  "confirmed_at": "2026-09-01T14:32:07+00:00",
  "qr_png_base64": "iVBORw0KGgo..."     // null tant que reference_confirmee vaut false
}

Comment récupérer la confirmation

Rappelez GET /einvoices/{id} jusqu'à ce que reference_confirmee passe à true. Comptez quelques minutes ; un intervalle de 5 minutes suffit, plus court ne sert à rien.

Deux étapes de dépôt, pas une

Combien de temps nous gardons ces documents

90 jours, et pas un de plus. Passé ce délai, les quatre documents et le corps de votre requête sont effacés de nos serveurs, ainsi que les journaux d'appels et de transactions correspondants. Nous conservons la ligne de la facture, c'est-à-dire son numéro, ses dates, son statut et sa référence TTN : un signing_id continue donc de répondre, en indiquant la date d'effacement dans documents_purged_at.

Pourquoi nous effaçons. Deux raisons, et aucune n'est une limitation de service :

• La confidentialité. Les factures de vos clients contiennent leurs montants, leurs partenaires et leurs adresses. Ce sont leurs affaires, pas les nôtres. Garder sans fin ce que nous n'avons plus de raison de garder serait une décision par défaut, et nous préférons ne pas la prendre à leur place.
• La performance. Une base qui ne fait que grossir finit par ralentir tout le monde, y compris vos appels. Effacer ce qui a servi garde nos temps de réponse là où ils sont.

Si vous préférez que nous gardions vos archives

Archiver dix ans de factures signées, les mettre à l'abri et savoir les retrouver n'est pas le métier d'un intégrateur. Nous proposons de le faire à votre place, en option, pour chaque client que vous passez en production.

L'option se commande depuis votre portail développeur, client par client, au moment de la mise en production ou à son renouvellement.

Une copie dans le Google Drive de votre client

Votre client veut garder lui-même un exemplaire de ses factures, dans un espace qui lui appartient. Nous déposons pour lui, dans un compte Google Drive, une archive par e-facture validée, sans que votre intégration n'ait rien à appeler.

Solde de crédits

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

Statut de la plateforme

Retourne l'état global de la plateforme. Aucune authentification requise, aucun crédit consommé. Utilisez-le comme sonde depuis votre ERP ou votre supervision.

curl https://efacturetn.com/api/v1/status

Réponse

{
  "success": true,
  "data": {
    "status": "operational",
    "version": "1.0.0",
    "teif_version": "1.8.8",
    "all_operational": true,
    "last_check": "17/07/2026 09:00"
  },
  "error": null
}

Champs

Disponibilité par service

Détail service par service : statut, latence mesurée et taux de disponibilité. Nécessite une clé API. Aucun crédit consommé, en test comme en live.

Paramètres

curl "https://efacturetn.com/api/v1/status/services?days=30" \
  -H "X-Api-Key: ck_test_xxxxxxxxxxxx"

Réponse

{
  "success": true,
  "data": {
    "status": "degraded",
    "all_operational": false,
    "last_check": "17/07/2026 09:00",
    "uptime_window_days": 30,
    "services": [
      {
        "slug": "signature",
        "name": "Signature électronique",
        "description": "Service de signature",
        "status": "operational",
        "status_label": "Operationnel",
        "operational": true,
        "latency_ms": 214,
        "detail": null,
        "uptime_percent": 99.86
      },
      {
        "slug": "ttn_prod",
        "name": "TTN production (El Fatoora)",
        "description": "Envoi e-factures (production)",
        "status": "partial_outage",
        "status_label": "Panne partielle",
        "operational": false,
        "latency_ms": null,
        "detail": "Perturbations en cours",
        "uptime_percent": 98.40
      },
      {
        "slug": "ttn_sandbox",
        "name": "TTN sandbox (test)",
        "description": "Environnement de test",
        "status": "operational",
        "status_label": "Operationnel",
        "operational": true,
        "latency_ms": 187,
        "detail": null,
        "uptime_percent": 99.90
      }
    ]
  },
  "error": null
}

Champs d'un service

Exemple : couper la file d'envoi quand TTN tombe

$res = json_decode(file_get_contents('https://efacturetn.com/api/v1/status'), true);

if ($res['data']['status'] !== 'operational') {
    // Ne pas envoyer maintenant : reprendre le lot plus tard
    $this->queue->pause('Plateforme e-facture indisponible');
}

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.

Créer 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_dev_VOTRE_CLE_DEVELOPPEUR
Content-Type: application/json

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

Réponse (201) :

{
  "success": true,
  "data": {
    "id": "018f...-....",
    "name": "Société 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 créé (environnement test)." },
  "production": { "success": false, "message": "L'organisation existe déjà 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": "Société 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_dev_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}.

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

Règles de forme du document

Ces règles s'appliquent aux trois portes, POST /einvoices/validate, POST /einvoices/process et POST /einvoices/prepare, avec les mêmes messages. Elles refusent avant la signature ce que TTN refuserait après, quand le crédit est déjà consommé. Validez à blanc avec /einvoices/validate : l'appel est gratuit et rend la liste complète des erreurs dans data.errors.

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, usb ou mobileid 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 ».
• Client étranger : même champ, buyer.id_number, et surtout buyer.country. Voir l'exemple export ci-dessous.
• 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 :

Facture export : un client qui n'a pas de matricule tunisien

Un client étranger n'a pas de matricule fiscal tunisien, et son numéro d'entreprise (SIREN, SIRET, numéro de TVA intracommunautaire, NIF) ne se met pas dans buyer.tax_id : ce champ n'accepte que la forme tunisienne et le refuse. Il se met dans buyer.id_number, seul, avec le pays du client.

Ce que l'export change, et rien d'autre :

• buyer.id_number porte le numéro, et buyer.tax_id est absent. Les espaces sont retirés avant l'envoi : 552 100 554 devient 552100554.
• buyer.country porte le code du pays du client. C'est lui qui fait accepter un numéro qui n'a pas la forme tunisienne.
• currency en devise étrangère : 2 décimales, aucune conversion, les montants sont conservés tels quels.
• Ni TVA, ni timbre fiscal : vat_rate: 0 sur les lignes, ou exonerated: true, et stamp_duty: false.
• Le vendeur, lui, ne change pas : c'est toujours le titulaire de votre clé, et son matricule tunisien complet part dans le document.

Ce cas figure en entier dans votre portail, deuxième document du jeu de test TTN, prêt à être envoyé tel quel.

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

Vos totaux et les nôtres : line_total_ht

Par défaut, nous calculons le total de chaque ligne nous-mêmes : quantité × prix unitaire, remise déduite. Dans la très grande majorité des cas, c'est exactement ce que vous voulez et vous n'avez rien à faire.

Quand vous en avez besoin

Quand votre logiciel arrive à un total légèrement différent du nôtre. Cela arrive avec des prix unitaires à beaucoup de décimales, et pour deux raisons qui n'ont rien à voir avec un défaut :

• La précision conservée. Nous gardons six décimales sur un prix unitaire. Un prix comme 8.40336134454 est donc stocké 8.403361. Sur 7 006 unités, ces quelques millionièmes font environ 3 millimes.
• L'ordre des arrondis. Beaucoup de logiciels arrondissent le total une seule fois, à la fin. Nous arrondissons chaque ligne puis nous sommons, parce qu'une ligne imprimée doit être un vrai montant et que le total doit être la somme de ce qui est imprimé. Cela vaut encore un millime ou deux, parfois dans l'autre sens.

Aucune précision supplémentaire ne supprime le second point : ce n'est pas une question de décimales, c'est une convention. D'où ce champ : envoyez-nous le montant que vous avez calculé, et nous imprimons le même.

Comment l'utiliser

Ajoutez line_total_ht sur la ligne, hors taxes, remise déjà déduite. Il remplace le produit quantité × prix ; la TVA et le FODEC s'en déduisent ensuite normalement.

La seule ligne ajoutée est line_total_ht. Tout le reste est votre facture habituelle.

Pour que le total de la FACTURE tombe juste aussi

Le total HT du document est la somme des lignes que vous envoyez. Si votre logiciel arrondit le total une seule fois, la somme de vos lignes arrondies peut dépasser votre propre total d'un millime. Dans ce cas, reportez ce reliquat sur une ligne, comme votre logiciel le fait déjà pour imprimer votre propre document, et nos deux totaux seront identiques au millime.

Exemple complet, prêt à envoyer

Une facture de trois lignes, avec des prix unitaires à onze décimales - exactement le cas qui fait diverger les totaux. Chaque ligne porte son line_total_ht.

Ce que vous obtenez, et ce sont les montants que cet envoi produit réellement :

Avec le champ, le total est exactement celui de votre logiciel. Ici la TVA tombe juste des deux côtés : c’est le HT, et donc le net à payer, qui portent l’écart. Sans lui, trois millimes d'écart, assez pour qu'un rapprochement comptable automatique signale la facture.

Ici, la somme des trois lignes tombe pile sur votre total. Quand ce n'est pas le cas, reportez le reliquat sur une ligne, comme expliqué juste au-dessus.

Ce que nous contrôlons

Nous prenons votre montant : c'est votre facture, vous en êtes l'émetteur. Nous refusons seulement un écart de plus de 1 % avec notre propre calcul, parce qu'aucun arrondi ne produit cela et que la facture part signée chez l'administration. Ce garde-fou attrape les trois erreurs réelles : un TTC envoyé à la place d'un HT (+19 %), une virgule déplacée (×10), une ligne mal appariée. Le refus est un 422 qui nomme les trois montants en cause.

Deux pièges à éviter

• Envoyez un montant HORS TAXES. Le TTC est l'erreur la plus fréquente, et elle est refusée.
• Ne l'envoyez pas « au cas où ». Si vos totaux correspondent déjà aux nôtres, omettez le champ : le calcul normal reste la règle, et une ligne de moins est une ligne qui ne peut pas diverger.

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 :