Guide d'intégration

1. Choisir le bon mode de signature

Quatre modes disponibles selon votre cas d'usage. Vous pouvez basculer de l'un à l'autre par requête via le champ method (seal, digigo, usb ou mobileid). Le mode E-Houwiya (Mobile ID) s'active chez le service de signature pour chaque compte : demandez-le nous.

2. Authentification

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

X-Api-Key: ck_test_xxxxxxxxxxxxxxxxxxxxxxxx

Trois clés, et chacune a un rôle :

• sk_dev_xxx, votre clé de développeur : elle sert à gérer vos clients (les créer, les raccorder). Elle n'émet aucune facture.
• ck_test_xxx, la clé sandbox de chacun de vos clients : signature et dépôt réels sur les environnements de TEST (aucune simulation), aucun crédit consommé.
• ck_live_xxx, la clé de production du même client : signature réelle, dépôt TTN réel, 1 crédit déduit par signature.

Chaque facture s'émet avec la clé du client concerné. Pour émettre au nom de votre propre société, créez-vous un client.

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: ck_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",
    "signing_id": "sg_3c9e1f7a2b4d6e8f0a1b2c3d",
    "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: ck_test_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d @facture.json

4. Flux DigiGo, clé USB, E-Houwiya : asynchrone, signature utilisateur

Les trois modes suivent le même parcours ; seule la valeur de method change (digigo, usb ou mobileid). Pour DigiGo et E-Houwiya, renseignez d'abord sur le client l'adresse du signataire (signer_email, dans le portail ou par PATCH /api/v1/clients/{id}) : celle de son certificat, à laquelle part la demande de signature.

4.1 Diagramme : version polling

4.2 Étape 1 : Préparer la signature

POST https://efacturetn.com/api/v1/einvoices/prepare
X-Api-Key: ck_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.3 Étape 2 : Rediriger le client

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

4.4 Étape 3 : Lire le résultat

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

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

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

4.5 Lien perdu ou signature à arrêter

• Lien perdu : renvoyez la même facture à POST /einvoices/prepare. Tant que la signature attend, vous recevez le même lien ("resumed": true), sans seconde transaction ni crédit. GET /einvoices/{signing_id} le donne aussi, dans signing_url.
• Arrêter la signature : POST /einvoices/{signing_id}/cancel. Rien n'est débité, et le numéro se prépare de nouveau aussitôt. Si le signataire a signé entre-temps, la facture est traitée comme signée, avec un seul crédit.
• Sans signature ni annulation, la tentative s'abandonne d'elle-même 30 minutes après son ouverture (can_prepare_again_at).

5. Codes d'erreur

5.1 Format de réponse d'erreur

{
  "success": false,
  "data": null,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invoice validation failed.",
    "details": [
      "buyer.tax_id or buyer.id_number is required.",
      "item 1: vat_rate is required (set the line vat_rate, a document default_vat_rate, or \"exonerated\": true)."
    ]
  }
}

6. Passer de Test à Production