Guide d'intégration

1. Choisir le bon mode de signature

Deux modes disponibles selon votre cas d'usage. Vous pouvez basculer de l'un à l'autre par requête via le champ method.

2. Authentification

Toutes les requêtes nécessitent un header X-Api-Key.

X-Api-Key: sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

Deux types de clés :

• sk_test_xxx en mode test : signature mockée, ttn_reference au format TTN-TEST-XXXXX, aucun crédit consommé. Idéal pour intégration.
• sk_live_xxx en production : signature réelle, dépôt TTN réel, 1 crédit déduit par signature.

3. Flux SEAL : synchrone, automatique

3.1 Diagramme de séquence

3.2 Requête

POST https://efacturetn.com/api/v1/einvoices/process
X-Api-Key: sk_test_xxxxxxxxxxxx
Content-Type: application/json

{
  "invoice_number": "F-2026-001",
  "date": "2026-06-13",
  "seller": {
    "name": "Mon Entreprise SARL",
    "tax_id": "1234567MAM000",
    "address": "Tunis"
  },
  "buyer": {
    "name": "Client SARL",
    "tax_id": "7654321XAM000"
  },
  "items": [
    { "description": "Service de conseil", "quantity": 1, "unit_price": 500, "vat_rate": 19 }
  ]
}

3.3 Réponse (succès)

{
  "success": true,
  "data": {
    "status": "signed",
    "invoice_number": "F-2026-001",
    "ttn_reference": "TTN-2026-XXXXX",
    "xml_base64": "PD94bWwgdmVyc2lvbj0iMS4wIi...",
    "pdf_base64": "JVBERi0xLjQKJaqrrK0K...",
    "test_mode": true,
    "credits_remaining": null
  },
  "error": null
}

3.4 Exemple cURL

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

4. Flux DigiGo : asynchrone, signature utilisateur

4.1 Diagramme : version polling

4.2 Diagramme : version webhook (recommandé)

4.3 Étape 1 : Préparer la signature

POST https://efacturetn.com/api/v1/einvoices/prepare
X-Api-Key: sk_test_xxxxxxxxxxxx
Content-Type: application/json

{
  "invoice_number": "F-2026-001",
  "date": "2026-06-13",
  "seller": { ... },
  "buyer": { ... },
  "items": [ ... ],
  "method": "digigo",
  "return_url": "https://votre-erp.tn/factures/F-2026-001/retour-signature"
}

Réponse :

{
  "success": true,
  "data": {
    "status": "pending_signature",
    "signing_id": "sg_a7f9c21b3e4d8f6a9b2c1d4e",
    "signing_url": "https://signature-securisee.tn/sign/xa7f9c21",
    "method": "digigo",
    "invoice_number": "F-2026-001"
  },
  "error": null
}

4.4 Étape 2 : Rediriger le client

HTTP/1.1 302 Found
Location: https://signature-securisee.tn/sign/xa7f9c21

4.5 Étape 3a : Polling (option simple)

Backoff exponentiel recommandé : 5s, 10s, 20s, 30s, 60s... Timeout total : 30 minutes.

GET https://efacturetn.com/api/v1/einvoices/sg_a7f9c21b3e4d8f6a9b2c1d4e
X-Api-Key: sk_test_xxxxxxxxxxxx

Quand status: "validated", la réponse contient xml_base64 + pdf_base64 + ttn_reference.

4.6 Étape 3b : Webhook (option recommandée)

Configurez votre URL HTTPS avec notre support. Vous recevrez un POST quand la signature passe à validated ou rejected.

Voir section 5. Webhook pour les détails de vérification HMAC.

5. Webhook : détails techniques

5.1 Payload reçu

POST https://votre-erp.tn/webhooks/efacture
X-Efacture-Signature: sha256=a3f1b2...
Content-Type: application/json

{
  "event": "einvoice.validated",
  "signing_id": "sg_a7f9c21b3e4d8f6a9b2c1d4e",
  "invoice_number": "F-2026-001",
  "status": "validated",
  "ttn_reference": "TTN-2026-XXXXX",
  "timestamp": "2026-06-13T14:30:00Z"
}

5.2 Vérification de la signature HMAC (PHP)

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_EFACTURE_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $rawBody, $webhookSecret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$payload = json_decode($rawBody, true);
// Traiter selon $payload['event'] et $payload['status']
http_response_code(200);

5.3 Politique de retry

• 3 tentatives : immédiat, +1 min, +5 min
• Succès si vous renvoyez 2xx
• Échec persistant : pas de re-essai automatique : vous pouvez récupérer via GET /einvoices/{signing_id}

6. Codes d'erreur

Code	HTTP	Description	Action recommandée
AUTH_INVALID_KEY	401	Clé API invalide ou inactive	Vérifier la clé
RATE_LIMIT	429	Trop de requêtes	Backoff exponentiel, lire X-RateLimit-*
INVALID_JSON	400	Corps non JSON	Corriger le payload
VALIDATION_FAILED	422	Champs requis manquants	Lire error.details
INSUFFICIENT_CREDITS	402	Solde épuisé	Acheter des crédits
SEAL_NOT_CONFIGURED	412	Cachet non provisionné	Contacter le support
SIGNING_FAILED	503	Service signature down	Réessayer dans 1-2 min

6.1 Format de réponse d'erreur

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invoice validation failed.",
    "details": [
      "Field \"buyer.tax_id\" is required.",
      "Item 0: vat_rate must be one of 0, 7, 13, 19."
    ]
  }
}

7. Passer de Test à Production

Critère	Test (sk_test_)	Production (sk_live_)
Signature	Mockée (TEIF placeholder)	XAdES réelle
Dépôt TTN	Aucun (référence fictive)	Dépôt réel
ttn_reference	TTN-TEST-XXXXX	TTN-2026-XXXXX
Crédits consommés	Aucun	1 par signature
Cachet/Certificat requis	Non	Oui (SEAL ou DigiGo)