Accueil

Documentation API

FATOORATTN est un tunnel sécurisé entre votre ERP et la plateforme de signature tunisienne. Vous envoyez vos données de facture, nous les transférons pour signature, vous récupérez le XML signé et le PDF.

~300 ms

Temps de réponse

Zéro stockage

Aucune donnée persistée

1 ligne de code

Intégration instantanée

Vous utilisez votre propre clé API. FATOORATTN ne fait que la transférer — nous ne la stockons pas.

Concepts clés

Mode SEAL

Signature automatique via cachet électronique serveur. Synchrone (~5s). Aucune interaction utilisateur.

POST /process Recommandé ERP

Mode DigiGo

Signature manuelle à distance. Interaction utilisateur (PIN + OTP). Idéal pour petits volumes.

POST /prepare Signature personnelle

Mode Clé USB

Signature locale avec votre clé de certification USB sur le poste du signataire. Asynchrone.

POST /prepare Clé USB détenue

Zéro stockage

Aucune donnée métier n'est persistée. Pas de payload, pas de XML, pas de PDF en base de données.

Tunnel pur

Webhooks

Notifications en temps réel des changements de statut. Vérification HMAC-SHA256 incluse.

POST /webhooks

Authentification

Toutes les requêtes doivent inclure votre clé API dans le header X-Api-Key.

HEADER X-Api-Key

X-Api-Key: ck_test_votre_cle_ici

TEST Sandbox

ck_test_xxxxxxxxxxxx

0 crédit consommé

LIVE Production

ck_live_xxxxxxxxxxxx

1 crédit par signature

POST /api/v1/invoices/validate 0 crédit

Valider un payload

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

                                        
# POST /api/v1/invoices/validate
curl -X POST https://api.signttnapi.tn/api/v1/invoices/validate \
  -H "X-Api-Key: ck_test_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "F-2026-001",
    "date": "2026-07-15",
    "seller": {
        "name": "Mon Entreprise",
        "tax_id": "1234567MAM000",
        "address": "Tunis"
    },
    "buyer": {
        "name": "Client",
        "tax_id": "7654321XAM000"
    },
    "items": [
        {
            "description": "Prestation",
            "quantity": 1,
            "unit_price": 500,
            "vat_rate": 19
        }
    ]
}'

                                        
// POST /api/v1/invoices/validate
<?php

$client = new GuzzleHttp\Client();
$response = $client->post(
    'https://api.signttnapi.tn/api/v1/invoices/validate',
    [
        'headers' => [
            'X-Api-Key' => 'ck_test_votre_cle',
        ],
        'json' => [...],
    ]
);

$result = json_decode($response->getBody(), true);

                                        
// POST /api/v1/invoices/validate
const response = await fetch('https://api.signttnapi.tn/api/v1/invoices/validate', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'ck_test_votre_cle',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({...),
});

const result = await response.json();

                                        
# POST /api/v1/invoices/validate
import requests

response = requests.post(
    'https://api.signttnapi.tn/api/v1/invoices/validate',
    headers={
        'X-Api-Key': 'ck_test_votre_cle',
        'Content-Type': 'application/json',
    },
    json={...},
)

result = response.json()

POST /api/v1/invoices/process 1 crédit (live)

Signer (mode SEAL)

Signe automatiquement votre facture via cachet électronique serveur et dépose chez TTN. Synchrone — réponse en ~5 secondes. XML signé + PDF avec QR code.

                                        
# POST /api/v1/invoices/process
curl -X POST https://api.signttnapi.tn/api/v1/invoices/process \
  -H "X-Api-Key: ck_test_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "F-2026-001",
    "date": "2026-07-15",
    "seller": {
        "name": "Mon Entreprise",
        "tax_id": "1234567MAM000",
        "address": "Tunis"
    },
    "buyer": {
        "name": "Client",
        "tax_id": "7654321XAM000"
    },
    "items": [
        {
            "description": "Prestation",
            "quantity": 1,
            "unit_price": 500,
            "vat_rate": 19
        }
    ]
}'

                                        
// POST /api/v1/invoices/process
<?php

$client = new GuzzleHttp\Client();
$response = $client->post(
    'https://api.signttnapi.tn/api/v1/invoices/process',
    [
        'headers' => [
            'X-Api-Key' => 'ck_test_votre_cle',
        ],
        'json' => [...],
    ]
);

$result = json_decode($response->getBody(), true);

                                        
// POST /api/v1/invoices/process
const response = await fetch('https://api.signttnapi.tn/api/v1/invoices/process', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'ck_test_votre_cle',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({...),
});

const result = await response.json();

                                        
# POST /api/v1/invoices/process
import requests

response = requests.post(
    'https://api.signttnapi.tn/api/v1/invoices/process',
    headers={
        'X-Api-Key': 'ck_test_votre_cle',
        'Content-Type': 'application/json',
    },
    json={...},
)

result = response.json()

POST /api/v1/invoices/prepare 1 crédit (live)

Préparer (DigiGo / Clé USB)

Prépare une signature manuelle (à distance PIN + OTP, ou locale avec clé USB via "method": "usb"). Retourne une URL de redirection vers le service de signature. Suivi par polling ou webhook.

                                        
# POST /api/v1/invoices/prepare
curl -X POST https://api.signttnapi.tn/api/v1/invoices/prepare \
  -H "X-Api-Key: ck_test_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "usb",
    "return_url": "https:\/\/mon-erp.tn\/retour",
    "invoice_number": "F-2026-001",
    "date": "2026-07-15",
    "seller": {
        "name": "Mon Entreprise",
        "tax_id": "1234567MAM000",
        "address": "Tunis"
    },
    "buyer": {
        "name": "Client",
        "tax_id": "7654321XAM000"
    },
    "items": [
        {
            "description": "Prestation",
            "quantity": 1,
            "unit_price": 500,
            "vat_rate": 19
        }
    ]
}'

                                        
// POST /api/v1/invoices/prepare
<?php

$client = new GuzzleHttp\Client();
$response = $client->post(
    'https://api.signttnapi.tn/api/v1/invoices/prepare',
    [
        'headers' => [
            'X-Api-Key' => 'ck_test_votre_cle',
        ],
        'json' => [...],
    ]
);

$result = json_decode($response->getBody(), true);

                                        
// POST /api/v1/invoices/prepare
const response = await fetch('https://api.signttnapi.tn/api/v1/invoices/prepare', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'ck_test_votre_cle',
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({...),
});

const result = await response.json();

                                        
# POST /api/v1/invoices/prepare
import requests

response = requests.post(
    'https://api.signttnapi.tn/api/v1/invoices/prepare',
    headers={
        'X-Api-Key': 'ck_test_votre_cle',
        'Content-Type': 'application/json',
    },
    json={...},
)

result = response.json()

GET /api/v1/invoices/{id} 0 crédit

Statut facture

Récupère le statut et les fichiers d'une facture. Utilisé pour le polling après un /prepare. Retourne le statut, le XML signé et le PDF une fois validée.

                                        
# GET /api/v1/invoices/{id}
curl -X GET https://api.signttnapi.tn/api/v1/invoices/{id} \
  -H "X-Api-Key: ck_test_votre_cle" \
  -H "Content-Type: application/json" \

                                        
// GET /api/v1/invoices/{id}
<?php

$client = new GuzzleHttp\Client();
$response = $client->get(
    'https://api.signttnapi.tn/api/v1/invoices/{id}',
    [
        'headers' => [
            'X-Api-Key' => 'ck_test_votre_cle',
        ],
    ]
);

$result = json_decode($response->getBody(), true);

                                        
// GET /api/v1/invoices/{id}
const response = await fetch('https://api.signttnapi.tn/api/v1/invoices/{id}', {
    method: 'GET',
    headers: {
        'X-Api-Key': 'ck_test_votre_cle',
        'Content-Type': 'application/json',
    },
});

const result = await response.json();

                                        
# GET /api/v1/invoices/{id}
import requests

response = requests.get(
    'https://api.signttnapi.tn/api/v1/invoices/{id}',
    headers={
        'X-Api-Key': 'ck_test_votre_cle',
        'Content-Type': 'application/json',
    },
)

result = response.json()

GET /api/v1/credits/balance 0 crédit

Solde crédits

Consultez votre solde de crédits restants, le total utilisé et le total acheté.

                                        
# GET /api/v1/credits/balance
curl -X GET https://api.signttnapi.tn/api/v1/credits/balance \
  -H "X-Api-Key: ck_test_votre_cle" \
  -H "Content-Type: application/json" \

                                        
// GET /api/v1/credits/balance
<?php

$client = new GuzzleHttp\Client();
$response = $client->get(
    'https://api.signttnapi.tn/api/v1/credits/balance',
    [
        'headers' => [
            'X-Api-Key' => 'ck_test_votre_cle',
        ],
    ]
);

$result = json_decode($response->getBody(), true);

                                        
// GET /api/v1/credits/balance
const response = await fetch('https://api.signttnapi.tn/api/v1/credits/balance', {
    method: 'GET',
    headers: {
        'X-Api-Key': 'ck_test_votre_cle',
        'Content-Type': 'application/json',
    },
});

const result = await response.json();

                                        
# GET /api/v1/credits/balance
import requests

response = requests.get(
    'https://api.signttnapi.tn/api/v1/credits/balance',
    headers={
        'X-Api-Key': 'ck_test_votre_cle',
        'Content-Type': 'application/json',
    },
)

result = response.json()

Objet Invoice

Structure complète du payload JSON attendu par l'API.

Champ	Type	Requis	Description
method	string	Optionnel	seal, digigo ou usb (défaut: config client)
invoice_number	string	Requis	Numéro de facture côté ERP
date	date	Requis	Date d'émission (YYYY-MM-DD)
due_date	date	Optionnel	Date d'échéance
currency	string	Optionnel	Devise ISO 4217 (défaut: TND)
default_vat_rate	int	Optionnel	TVA par défaut: 0, 7, 13, 19
stamp_duty	bool \| number	Optionnel	Timbre fiscal (défaut: true, ou montant)
withholding_tax_rate	number	Optionnel	Retenue à la source %
seller.name	string	Requis	Raison sociale du vendeur
seller.tax_id	string	Requis	Matricule fiscal vendeur
seller.address	string	Optionnel	Adresse du vendeur
buyer.name	string	Requis	Raison sociale acheteur
buyer.tax_id	string	Conditionnel	MF ou id_number (CIN)
items[].description	string	Requis	Description de la ligne
items[].quantity	number	Requis	Quantité
items[].unit_price	number	Requis	Prix unitaire HT
items[].vat_rate	int	Conditionnel	0, 7, 13, 19 (ou exonerated)
items[].exonerated	bool	Optionnel	Ligne exonérée de TVA
items[].fodec	bool	Optionnel	FODEC 1%
pdf_base64	string	Optionnel	Votre PDF en base64
return_url	url	Conditionnel	HTTPS requis (DigiGo / clé USB)

Gestion des erreurs

Toutes les erreurs retournent un format JSON normalisé :

// Format d'erreur standard
{
    "success": false,
    "data": null,
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "La validation de la facture a échoué.",
        "details": [
            "seller.name est requis."
        ]
    }
}

Code	HTTP	Description
AUTH_INVALID_KEY	401	Clé API invalide, inactive ou non autorisée
VALIDATION_FAILED	422	Champs requis manquants ou invalides
INVALID_JSON	400	Corps de requête non JSON valide
INSUFFICIENT_CREDITS	402	Crédits insuffisants
DEVELOPER_KEY_NOT_ALLOWED	403	Clé développeur utilisée pour émettre
PERMISSION_DENIED	403	Ressource d'un autre compte
SIGNER_UNAVAILABLE	400	Méthode inconnue (seal, digigo, usb)
SEAL_NOT_CONFIGURED	412	Cachet SEAL non provisionné ou passphrase manquante
SIGNER_NOT_CONFIGURED	412	Service DigiGo/USB non configuré
SIGNER_EMAIL_MISSING	412	Signature à distance sans email signataire
SIGNER_CIRCUIT_OPEN	503	Service de signature indisponible (réessayer 30-60s)
SIGNING_FAILED	503	Échec technique de la signature
TTN_DEPOSIT_FAILED	—	Signée mais dépôt TTN échoué (bloc ttn.error)
USER_CANCELLED	—	Signature annulée par le signataire
RATE_LIMIT	429	Trop de requêtes (60/min)
UPSTREAM_ERROR	502	Erreur de l'API de signature

Webhooks

Recevez des notifications en temps réel lorsque le statut de votre facture change.

einvoice.validated

Facture validée par TTN

einvoice.rejected

Facture rejetée (signature ou dépôt)

einvoice.submitted

Déposée, en attente réponse TTN (SFTP)

// Payload webhook
{
    "event": "einvoice.validated",
    "signing_id": "sg_a7f9c21b3e4d8f6a",
    "invoice_number": "F-2026-001",
    "ttn_reference": "TTN-2026-XXXXX",
    "timestamp": "2026-07-15T14:30:00Z"
}

Vérification HMAC : Chaque webhook inclut un header X-Efacture-Signature: sha256=<hex>. Vérifiez la signature avec HMAC-SHA256 et votre secret. Répondez 2xx rapidement (3 nouvelles tentatives sinon).