Integration guide

eFacture Connect: from JSON to an e-invoice signed and submitted to TTN

View Swagger →

1. Choosing the right signing mode

Four modes are available depending on your use case. You can switch from one to another on each request with the method field (seal, digigo, usb or mobileid). The E-Houwiya (Mobile ID) mode is enabled by the signing service for each account: ask us for it.

DigiGo: PIN + OTP

Endpoint: POST /einvoices/prepare

  • Asynchronous (manual signature by the user)
  • Redirect to a secure page (PIN + SMS OTP)
  • Retrieved with GET /einvoices/{signing_id}
  • Ideal for personal signatures / low volumes
  • No seal to provision: user certificate
  • Signer address (signer_email) to set on the client

USB token: local signing

Endpoint: POST /einvoices/prepare

  • Asynchronous (signed on the signer's workstation)
  • Certificate on a physical token, it never leaves the workstation
  • The API prepares the TEIF and handles the TTN submission
  • Retrieved with GET /einvoices/{signing_id}
  • Ideal if you already hold your certification token

E-Houwiya: Mobile ID (mobileid)

Endpoint: POST /einvoices/prepare

  • Asynchronous (approval on the signer's smartphone)
  • Certificate tied to the mobile digital identity
  • No dedicated hardware: the smartphone is enough
  • Retrieved with GET /einvoices/{signing_id}
  • Option to enable for each account: contact us

2. Authentication

Every request requires an X-Api-Key header.

X-Api-Key: ck_test_xxxxxxxxxxxxxxxxxxxxxxxx

Three keys, each with its own role:

  • sk_dev_xxx, your developer key: it is used to manage your clients (create them, connect them). It issues no invoices.
  • ck_test_xxx, the sandbox key of each of your clients: real signing and submission on the TEST environments (no simulation), no credits consumed.
  • ck_live_xxx, the live key of the same client: real signing, real TTN submission, 1 credit deducted per signature.

Each invoice is issued with the key of the client concerned. To issue invoices on behalf of your own company, create a client for yourself.

3. SEAL flow: synchronous, automatic

3.1 Sequence diagram

sequenceDiagram autonumber participant ERP as Your ERP participant API as eFacture Connect participant SIG as Signing service participant TTN as TunisieTradeNet ERP->>API: POST /einvoices/process (JSON) API->>API: Payload validation API->>SIG: TEIF generation + SEAL signature SIG-->>API: Signed XML API->>TTN: Signed invoice submission TTN-->>API: ttn_reference API-->>ERP: 200 OK { xml_base64, pdf_base64, ttn_reference }

3.2 Request

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": "1234567RAM000",
    "address": "Avenue Habib Bourguiba",
    "city": "Tunis",
    "postal_code": "1000"
  },
  "buyer": {
    "name": "Client SARL",
    "tax_id": "7654321CAM000"
  },
  "items": [
    {
      "description": "Service de conseil",
      "quantity": 1,
      "unit_price": 500,
      "vat_rate": 19
    }
  ]
}

3.3 Response (success)

{
  "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 cURL example

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. DigiGo, USB token, E-Houwiya flow: asynchronous, user signature

All three modes follow the same path; only the value of method changes (digigo, usb or mobileid). For DigiGo and E-Houwiya, first set the signer address on the client (signer_email, in the portal or with PATCH /api/v1/clients/{id}): the address of the signer's certificate, to which the signing request is sent.

4.1 Diagram: polling version

sequenceDiagram autonumber participant ERP as Your ERP participant USER as End client participant API as eFacture Connect participant SIG as Signing page participant TTN as TunisieTradeNet ERP->>API: POST /einvoices/prepare (method=digigo, return_url) API-->>ERP: 200 { signing_id, signing_url } ERP-->>USER: Redirect to signing_url USER->>SIG: PIN + SMS OTP entry SIG->>API: Signature OK API->>TTN: Signed invoice submission SIG-->>USER: Redirect to return_url loop Polling every 5-30s ERP->>API: GET /einvoices/{signing_id} API-->>ERP: { status: "pending_signature" | "signed" | "validated" } end API-->>ERP: { status: "validated", xml_base64, pdf_base64, ttn_reference }

4.2 Step 1: Prepare the 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"
}

Response:

{
  "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 Step 2: Redirect the client

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

4.4 Step 3: Read the result

Recommended exponential backoff: 5s, 10s, 20s, 30s, 60s... Total timeout: 30 minutes.

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

When status: "validated", the response contains xml_base64 + pdf_base64 + ttn_reference.

4.5 Lost link or signature to stop

  • Lost link: send the same invoice again to POST /einvoices/prepare. While the signature is pending, you receive the same link ("resumed": true), with no second transaction and no extra credit. GET /einvoices/{signing_id} also returns it, in signing_url.
  • Stop the signature: POST /einvoices/{signing_id}/cancel. Nothing is charged, and the number can be prepared again immediately. If the signer signed in the meantime, the invoice is handled as signed, with a single credit.
  • With neither a signature nor a cancellation, the attempt abandons itself 30 minutes after it was opened (can_prepare_again_at).

5. Error codes

CodeHTTPDescriptionRecommended action
AUTH_INVALID_KEY401Invalid or inactive API keyCheck the key
RATE_LIMIT429Too many requestsExponential backoff, read X-RateLimit-*
INVALID_JSON400Body is not JSONFix the payload
VALIDATION_FAILED422Required fields missingRead error.details
INSUFFICIENT_CREDITS402Balance exhaustedBuy credits
SEAL_NOT_CONFIGURED412Seal not provisioned, or seal PIN code missingSet seal_passphrase_test / seal_passphrase_prod on the client
SIGNER_NOT_CONFIGURED412Client's signing account not created yetCreate it from the portal, or PATCH /api/v1/clients/{id} with "provision"
SIGNER_EMAIL_MISSING412DigiGo or E-Houwiya without a signer addressSet signer_email on the client
DEVELOPER_KEY_NOT_ALLOWED403Developer key used to issue an invoiceUse the client's key (ck_)
SELLER_MISMATCH422The seller sent is not the key holderFix seller.tax_id, or omit it
INVOICE_IN_PROGRESS409A signature is already pending on this number, with different contentComplete the signature (error.details.signing_url) or cancel it
INVOICE_NUMBER_ALREADY_ISSUED409Number already accepted by TTN for other contentIssue a credit note, or use a new number
METHOD_REQUIRES_PREPARE422DigiGo, USB token or E-Houwiya requested on /einvoices/processUse /einvoices/prepare
SIGNING_FAILED503Signing service downRetry in 1-2 min

5.1 Error response format

{
  "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. Moving from Test to Live

CriterionTest (ck_test_)Live (ck_live_)
SignatureReal XAdES, the provider's test environmentReal XAdES
TTN submissionReal, on the TTN test environmentReal submission
Credits consumedNone1 per signature
Signing accountSandbox, created from the portalLive, created from the portal
No code to change on the ERP side: to move one client to live mode, replace its ck_test_ key with its ck_live_ key. Your clients are independent: one can be live while another stays in test mode.
Try the endpoints on Swagger →

All error codes, optional fields and cancellation: full documentation.

Discuter sur WhatsApp