eFacture Connect: from JSON to an e-invoice signed and submitted to TTN
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.
Endpoint: POST /einvoices/process
Endpoint: POST /einvoices/prepare
GET /einvoices/{signing_id}signer_email) to set on the clientEndpoint: POST /einvoices/prepare
GET /einvoices/{signing_id}mobileid)Endpoint: POST /einvoices/prepare
GET /einvoices/{signing_id}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.
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
}
]
}
{
"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
}
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
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.
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
}
HTTP/1.1 302 Found
Location: https://signature-securisee.tn/sign/xa7f9c21
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.
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.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.can_prepare_again_at).| Code | HTTP | Description | Recommended action |
|---|---|---|---|
AUTH_INVALID_KEY | 401 | Invalid or inactive API key | Check the key |
RATE_LIMIT | 429 | Too many requests | Exponential backoff, read X-RateLimit-* |
INVALID_JSON | 400 | Body is not JSON | Fix the payload |
VALIDATION_FAILED | 422 | Required fields missing | Read error.details |
INSUFFICIENT_CREDITS | 402 | Balance exhausted | Buy credits |
SEAL_NOT_CONFIGURED | 412 | Seal not provisioned, or seal PIN code missing | Set seal_passphrase_test / seal_passphrase_prod on the client |
SIGNER_NOT_CONFIGURED | 412 | Client's signing account not created yet | Create it from the portal, or PATCH /api/v1/clients/{id} with "provision" |
SIGNER_EMAIL_MISSING | 412 | DigiGo or E-Houwiya without a signer address | Set signer_email on the client |
DEVELOPER_KEY_NOT_ALLOWED | 403 | Developer key used to issue an invoice | Use the client's key (ck_) |
SELLER_MISMATCH | 422 | The seller sent is not the key holder | Fix seller.tax_id, or omit it |
INVOICE_IN_PROGRESS | 409 | A signature is already pending on this number, with different content | Complete the signature (error.details.signing_url) or cancel it |
INVOICE_NUMBER_ALREADY_ISSUED | 409 | Number already accepted by TTN for other content | Issue a credit note, or use a new number |
METHOD_REQUIRES_PREPARE | 422 | DigiGo, USB token or E-Houwiya requested on /einvoices/process | Use /einvoices/prepare |
SIGNING_FAILED | 503 | Signing service down | Retry in 1-2 min |
{
"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)."
]
}
}
| Criterion | Test (ck_test_) | Live (ck_live_) |
|---|---|---|
| Signature | Real XAdES, the provider's test environment | Real XAdES |
| TTN submission | Real, on the TTN test environment | Real submission |
| Credits consumed | None | 1 per signature |
| Signing account | Sandbox, created from the portal | Live, created from the portal |
ck_test_ key with its ck_live_ key. Your clients are independent: one can be live while another stays in test mode.
All error codes, optional fields and cancellation: full documentation.