{
    "openapi": "3.0.3",
    "info": {
        "title": "eFacture Connect API",
        "version": "1.1.0",
        "description": "## Overview\n\nREST API to integrate Tunisian e-invoicing into your ERP. Send JSON, receive a signed XML (TEIF v1.8.9 + XAdES) and a PDF with a QR code.\n\n## Four signing modes\n\n| Mode | `method` | Endpoint | Synchronous? | User interaction |\n|---|---|---|---|---|\n| **Entreprise ID** (server seal) | `seal` | `POST /einvoices/process` | Yes (~5 s) | None |\n| **DigiGo** (PIN + OTP) | `digigo` | `POST /einvoices/prepare` | No | Signing page |\n| **USB key** (local signature) | `usb` | `POST /einvoices/prepare` | No | Token on the signer's computer |\n| **E-Houwiya** (Mobile ID) | `mobileid` | `POST /einvoices/prepare` | No | Approval on a smartphone (option enabled per account) |\n\nSee the [integration guide](/en/documentation-api/guide) for sequence diagrams, and the [full documentation](/en/documentation-api) for every field and error code.\n\n## Authentication\n\nEvery request carries the `X-Api-Key` header. Each invoice is issued with the key of the **client** concerned: `ck_test_xxx` (real signing and submission on the TEST environments, no credit consumed) or `ck_live_xxx` (live, 1 credit per signature). Your developer key `sk_dev_xxx` manages your clients (**Clients** section) and issues no invoice (`403 DEVELOPER_KEY_NOT_ALLOWED`).\n\n## Test bench (simulation): this is not test mode\n\n**Test mode** (`ck_test_xxx`) **really** signs and submits, on the test environments: it requires an El Fatoora account and a certificate. The **test bench** **simulates** signing and TTN, for one reason only: to let you integrate the API **while your client is waiting for their TTN access and certificate**. Nothing is signed or submitted, and no document has legal value.\n\n- It is opened **on request to support, client by client**, and only applies to that client's `ck_test_` key. A `ck_live_` key is **never** simulated.\n- **Same routes, same bodies, same responses** as test mode and live: not a single line of your code changes when the test bench closes.\n- A test bench response carries `\"simulation\": true` and the `X-eFactureTN-Simulation: 1` header. **Informational only**: do not make any logic depend on it.\n- The `X-Simulation-Scenario` header triggers a simulated failure to exercise your error handling. **For your tests only**: do not add it to your integration's calls.\n\nDetails: [documentation, Test bench section](/en/documentation-api#banc-essai).\n\n## Main error codes\n\n| Code | HTTP | Description |\n|---|---|---|\n| `AUTH_INVALID_KEY` | 401 | Invalid or inactive API key |\n| `DEVELOPER_KEY_NOT_ALLOWED` | 403 | Developer key used to issue: use the client's key |\n| `INVALID_JSON` | 400 | Request body is not JSON |\n| `VALIDATION_FAILED` | 422 | Required fields missing or invalid (see `error.details`) |\n| `SELLER_MISMATCH` | 422 | The seller sent is not the key holder |\n| `METHOD_REQUIRES_PREPARE` | 422 | DigiGo, USB key or E-Houwiya requested on `/einvoices/process` |\n| `INSUFFICIENT_CREDITS` | 402 | Wallet empty or client cap reached |\n| `SEAL_NOT_CONFIGURED` | 412 | Seal not provisioned, or seal PIN missing |\n| `SIGNER_NOT_CONFIGURED` | 412 | Client's signing account not created yet |\n| `SIGNER_EMAIL_MISSING` | 412 | DigiGo or E-Houwiya without a signer address (`signer_email`) |\n| `INVOICE_IN_PROGRESS` | 409 | A signature is already pending on this number, with different content |\n| `INVOICE_NUMBER_ALREADY_ISSUED` | 409 | Number already accepted by TTN for different content |\n| `RATE_LIMIT` | 429 | Too many requests (`X-RateLimit-*` headers) |\n| `INVALID_SIMULATION_SCENARIO` | 422 | Test bench only: unknown `X-Simulation-Scenario` value |\n| `SANDBOX_DAILY_LIMIT` | 429 | Test bench only: cap on simulated invoices per 24 hours reached |\n| `SIGNING_FAILED` | 503 | Signing service unavailable |\n\n## Errors\n\nEvery error returns JSON: `{\"success\": false, \"error\": {\"code\", \"message\"}}`, including an internal error (`500 INTERNAL_ERROR`). A temporarily unavailable service responds `503 SERVICE_UNAVAILABLE` with the `Retry-After` header: retry after that delay. Every response carries the `X-Request-Id` header; send it to us so we can find a call."
    },
    "servers": [
        {
            "url": "https://efacturetn.com",
            "description": "Production"
        }
    ],
    "security": [
        {
            "ApiKeyAuth": []
        }
    ],
    "components": {
        "securitySchemes": {
            "ApiKeyAuth": {
                "type": "apiKey",
                "in": "header",
                "name": "X-Api-Key",
                "description": "Client key (ck_test_xxx in test mode, ck_live_xxx in live) to issue invoices; developer key (sk_dev_xxx) for the Clients section."
            }
        },
        "parameters": {
            "SimulationScenario": {
                "name": "X-Simulation-Scenario",
                "in": "header",
                "required": false,
                "description": "TEST BENCH ONLY (simulation, distinct from test mode). Triggers a simulated failure to exercise your error handling. No effect on a key that is not on the test bench, and never on a ck_live_ key. For your tests only: do not add it to your integration's calls. ttn_indisponible and ttn_compte_desactive return next_action resubmit; ttn_rejet_contrl05 and ttn_rejet_contrl02 return next_action resign; signature_echouee returns 503 SIGNING_FAILED. An unknown value returns 422 INVALID_SIMULATION_SCENARIO.",
                "schema": {
                    "type": "string",
                    "enum": [
                        "ttn_indisponible",
                        "ttn_compte_desactive",
                        "ttn_rejet_contrl05",
                        "ttn_rejet_contrl02",
                        "signature_echouee"
                    ]
                }
            }
        },
        "schemas": {
            "InvoiceItem": {
                "type": "object",
                "required": [
                    "description",
                    "quantity",
                    "unit_price"
                ],
                "properties": {
                    "description": {
                        "type": "string",
                        "example": "Service de conseil"
                    },
                    "quantity": {
                        "type": "number",
                        "example": 1.0
                    },
                    "unit_price": {
                        "type": "number",
                        "example": 500.0,
                        "description": "Unit price excluding VAT."
                    },
                    "vat_rate": {
                        "type": "integer",
                        "enum": [
                            0,
                            7,
                            13,
                            19
                        ],
                        "example": 19,
                        "description": "VAT rate. Optional if default_vat_rate is given on the invoice, or if the line carries exonerated: true."
                    }
                }
            },
            "SignRequest": {
                "type": "object",
                "required": [
                    "invoice_number",
                    "date",
                    "seller",
                    "buyer",
                    "items"
                ],
                "properties": {
                    "invoice_number": {
                        "type": "string",
                        "example": "F-2026-001",
                        "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,29}$",
                        "maxLength": 30,
                        "description": "Invoice number on the ERP side, 30 characters at most: letters, digits, hyphen, underscore, starting with a letter or a digit. No period, space or slash (TTN business rule 7). Echoed in the response."
                    },
                    "date": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-06-13",
                        "description": "Issue date, never in the future."
                    },
                    "due_date": {
                        "type": "string",
                        "format": "date",
                        "example": "2026-07-13",
                        "description": "Optional: due date."
                    },
                    "currency": {
                        "type": "string",
                        "enum": ["TND", "EUR", "USD"],
                        "example": "TND",
                        "description": "Invoice currency. Default TND."
                    },
                    "exchange_rate": {
                        "type": "number",
                        "example": 3.385,
                        "description": "Invoice in EUR or USD: dinars per unit of currency. TTN also requires the total including VAT in dinars (business rule 14): your rate, or our rate of the day if you omit it. Alias: taux_de_change."
                    },
                    "seller": {
                        "type": "object",
                        "required": [
                            "name",
                            "address",
                            "city",
                            "postal_code"
                        ],
                        "properties": {
                            "name": {
                                "type": "string",
                                "example": "Mon Entreprise SARL"
                            },
                            "tax_id": {
                                "type": "string",
                                "example": "1234567RAM000",
                                "description": "Optional: the key already identifies the seller. If you send it, only the first 8 characters are compared (1234567R and 1234567RAM000 are equivalent); a different taxpayer is rejected with SELLER_MISMATCH."
                            },
                            "address": {
                                "type": "string",
                                "example": "Avenue Habib Bourguiba"
                            },
                            "city": {
                                "type": "string",
                                "example": "Tunis",
                                "description": "Required by TTN (business rule 5: complete supplier address)."
                            },
                            "postal_code": {
                                "type": "string",
                                "example": "1000",
                                "description": "Required by TTN (business rule 5)."
                            },
                            "rib": {
                                "type": "string",
                                "example": "04103003004813770791",
                                "description": "20-digit bank or postal account. Required when the buyer belongs to the public sector (business rule 13); otherwise read from bank_details."
                            },
                            "country": {
                                "type": "string",
                                "example": "TN",
                                "description": "Default TN."
                            }
                        }
                    },
                    "buyer": {
                        "type": "object",
                        "required": [
                            "name"
                        ],
                        "properties": {
                            "name": {
                                "type": "string",
                                "example": "Client SARL"
                            },
                            "tax_id": {
                                "type": "string",
                                "example": "7654321CAM000",
                                "description": "Tunisian tax ID, long form (13 characters) or short form (8), with a correct check letter (sum of the 7 digits weighted from 7 to 1, modulo 23, position in ABCDEFGHJKLMNPQRSTVWXYZ: 1234567 gives R). A foreign number goes in id_number."
                            },
                            "id_number": {
                                "type": "string",
                                "example": "552100554",
                                "description": "Instead of tax_id: national ID card number (CIN) of a Tunisian individual (exactly 8 digits), or company number of a foreign client (1 to 30 letters and digits)."
                            },
                            "country": {
                                "type": "string",
                                "example": "TN",
                                "description": "ISO country code. Required in practice for a foreign client: it determines the type of identifier sent to TTN."
                            },
                            "public_entity": {
                                "type": "boolean",
                                "example": false,
                                "description": "true for the State, a local authority or a public institution. TTN then requires tax_id, the full address (address, city, postal_code) and seller.rib (rules 11 to 13)."
                            }
                        },
                        "description": "tax_id (Tunisian tax ID) OR id_number (CIN, foreign company number, with country)."
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/components/schemas/InvoiceItem"
                        }
                    },
                    "stamp_duty": {
                        "oneOf": [
                            {
                                "type": "boolean"
                            },
                            {
                                "type": "number"
                            }
                        ],
                        "default": true,
                        "description": "Stamp duty: present by default (1.000 TND). false to remove it, or an amount."
                    },
                    "withholding_tax_rate": {
                        "type": "number",
                        "nullable": true,
                        "description": "Withholding tax rate (1.5, 3, 10, 15, 20). Base: amount excluding VAT + VAT."
                    },
                    "method": {
                        "type": "string",
                        "enum": [
                            "seal",
                            "digigo",
                            "usb",
                            "mobileid"
                        ],
                        "description": "Optional: the signing mode for this request. Defaults to the one configured on the client. seal on /process; digigo, usb or mobileid on /prepare."
                    },
                    "return_url": {
                        "type": "string",
                        "format": "uri",
                        "example": "https://votre-erp.tn/factures/F-2026-001",
                        "description": "Required for digigo, usb and mobileid: HTTPS URL of your ERP, where the user returns after signing."
                    },
                    "type": {
                        "type": "string",
                        "enum": [
                            "facture",
                            "credit_note",
                            "debit_note"
                        ],
                        "default": "facture",
                        "description": "Document type. A credit note (credit_note) requires original_invoice_number."
                    },
                    "original_invoice_number": {
                        "type": "string",
                        "description": "Number of the original invoice, required for a credit note or a debit note."
                    },
                    "pdf_base64": {
                        "type": "string",
                        "description": "Optional: your PDF encoded in base64. Without it, we generate one."
                    }
                }
            },
            "SignResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": true
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "status": {
                                "type": "string",
                                "example": "signed"
                            },
                            "invoice_number": {
                                "type": "string",
                                "example": "F-2026-001"
                            },
                            "ttn_reference": {
                                "type": "string",
                                "example": "TTN-2026-XXXXX"
                            },
                            "xml_base64": {
                                "type": "string",
                                "description": "Signed TEIF XML, base64-encoded."
                            },
                            "pdf_base64": {
                                "type": "string",
                                "description": "PDF with QR code, base64-encoded."
                            },
                            "test_mode": {
                                "type": "boolean"
                            },
                            "signing_id": {
                                "type": "string",
                                "example": "sg_3c9e1f7a2b4d6e8f0a1b2c3d",
                                "description": "Invoice identifier, for GET /einvoices/{id}, /resubmit-ttn and /cancel."
                            }
                        }
                    },
                    "error": {
                        "type": "object",
                        "nullable": true
                    }
                }
            },
            "ErrorResponse": {
                "type": "object",
                "properties": {
                    "success": {
                        "type": "boolean",
                        "example": false
                    },
                    "data": {
                        "type": "object",
                        "nullable": true
                    },
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string",
                                "example": "VALIDATION_FAILED"
                            },
                            "message": {
                                "type": "string",
                                "example": "Invoice validation failed."
                            },
                            "details": {
                                "description": "Details: list of validation errors, or useful information (signing_id, signing_url…).",
                                "oneOf": [
                                    {
                                        "type": "array",
                                        "items": {
                                            "type": "string"
                                        }
                                    },
                                    {
                                        "type": "object"
                                    }
                                ]
                            }
                        }
                    }
                }
            }
        }
    },
    "paths": {
        "/api/v1/status": {
            "get": {
                "tags": [
                    "General"
                ],
                "summary": "Overall platform status",
                "description": "Overall availability of the services. No authentication required. The status is computed from the real checks run every hour: it is that of the most degraded service.",
                "security": [],
                "responses": {
                    "200": {
                        "description": "Overall status",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "operational",
                                                        "degraded",
                                                        "partial_outage",
                                                        "major_outage",
                                                        "maintenance"
                                                    ],
                                                    "example": "operational"
                                                },
                                                "version": {
                                                    "type": "string",
                                                    "example": "1.0.0"
                                                },
                                                "teif_version": {
                                                    "type": "string",
                                                    "example": "1.8.9"
                                                },
                                                "all_operational": {
                                                    "type": "boolean",
                                                    "example": true
                                                },
                                                "last_check": {
                                                    "type": "string",
                                                    "example": "17/07/2026 09:00"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/status/services": {
            "get": {
                "tags": [
                    "General"
                ],
                "summary": "Detailed availability per service",
                "description": "Details per service: status, latency and availability rate. Requires an API key. Each service's slug is stable and can be used as an identifier.",
                "parameters": [
                    {
                        "name": "days",
                        "in": "query",
                        "required": false,
                        "description": "Availability rate window, in days (1 to 180). Default: 90.",
                        "schema": {
                            "type": "integer",
                            "default": 90,
                            "minimum": 1,
                            "maximum": 180
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Details per service",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "string",
                                                    "example": "operational"
                                                },
                                                "all_operational": {
                                                    "type": "boolean",
                                                    "example": true
                                                },
                                                "last_check": {
                                                    "type": "string",
                                                    "example": "17/07/2026 09:00"
                                                },
                                                "uptime_window_days": {
                                                    "type": "integer",
                                                    "example": 90
                                                },
                                                "services": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "slug": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "platform",
                                                                    "signature",
                                                                    "ttn_prod",
                                                                    "ttn_sandbox",
                                                                    "api",
                                                                    "tej",
                                                                    "email"
                                                                ],
                                                                "example": "signature"
                                                            },
                                                            "name": {
                                                                "type": "string",
                                                                "example": "Signature electronique"
                                                            },
                                                            "description": {
                                                                "type": "string",
                                                                "example": "Service de signature"
                                                            },
                                                            "status": {
                                                                "type": "string",
                                                                "enum": [
                                                                    "operational",
                                                                    "degraded",
                                                                    "partial_outage",
                                                                    "major_outage",
                                                                    "maintenance"
                                                                ],
                                                                "example": "operational"
                                                            },
                                                            "status_label": {
                                                                "type": "string",
                                                                "example": "Operationnel"
                                                            },
                                                            "operational": {
                                                                "type": "boolean",
                                                                "example": true
                                                            },
                                                            "latency_ms": {
                                                                "type": "integer",
                                                                "nullable": true,
                                                                "description": "Measured latency, only for services probed over the network.",
                                                                "example": 214
                                                            },
                                                            "detail": {
                                                                "type": "string",
                                                                "nullable": true,
                                                                "description": "Reason, filled only when the service is not operational.",
                                                                "example": null
                                                            },
                                                            "uptime_percent": {
                                                                "type": "number",
                                                                "nullable": true,
                                                                "description": "Availability rate over the window. null until history is available.",
                                                                "example": 99.86
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid API key (AUTH_INVALID_KEY)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "429": {
                        "description": "Too many requests (RATE_LIMIT)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/einvoices/validate": {
            "post": {
                "tags": [
                    "Issue: server seal (synchronous)"
                ],
                "summary": "Validate an invoice without signing it",
                "description": "Checks the invoice body with the same rules as /process and /prepare, without signing or submitting. Free, even in live. Errors are listed in data.errors.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SignRequest"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Validation result",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "valid": {
                                                    "type": "boolean"
                                                },
                                                "errors": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "string"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid API key (AUTH_INVALID_KEY)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/einvoices/process": {
            "post": {
                "tags": [
                    "Issue: server seal (synchronous)"
                ],
                "summary": "Sign with the server seal and submit to TTN (synchronous)",
                "description": "## Server seal (Entreprise ID)\n\n**Synchronous** (~5 seconds), **no user interaction**: ideal for high volumes and back-office ERPs.\n\n### Flow\n1. Body validation\n2. TEIF v1.8.9 generation\n3. XAdES signature with the company's electronic seal\n4. Submission to TTN\n5. Response: signed XML (base64) + PDF (base64) + TTN reference\n\n### Test and live\n- `ck_test_xxx` key: real signing and submission on the TEST environments, no credit consumed\n- `ck_live_xxx` key: real signing and submission, 1 credit per signature\n\n### Prerequisites\n- Seal provisioned and PIN set for the key's environment (otherwise `SEAL_NOT_CONFIGURED`)\n- DigiGo, USB key and E-Houwiya go through `/einvoices/prepare` (otherwise `METHOD_REQUIRES_PREPARE`)\n- Sending the same invoice again does not sign it twice: the existing document is returned (`\"replayed\": true`)",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SimulationScenario"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SignRequest"
                            },
                            "examples": {
                                "Basique": {
                                    "summary": "Minimal invoice",
                                    "value": {
                                        "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
                                            }
                                        ]
                                    }
                                },
                                "Complete avec timbre + RS": {
                                    "summary": "Invoice with stamp duty and 1.5% withholding tax",
                                    "value": {
                                        "invoice_number": "F-2026-042",
                                        "date": "2026-06-13",
                                        "due_date": "2026-07-13",
                                        "seller": {
                                            "name": "Cabinet Conseil & Co",
                                            "tax_id": "1234567RAM000",
                                            "address": "Avenue Habib Bourguiba",
                                            "city": "Tunis",
                                            "postal_code": "1000"
                                        },
                                        "buyer": {
                                            "name": "Societe Industrielle Tunisie SA",
                                            "tax_id": "7654321CAM000"
                                        },
                                        "items": [
                                            {
                                                "description": "Audit comptable 2026",
                                                "quantity": 1,
                                                "unit_price": 3500,
                                                "vat_rate": 19
                                            },
                                            {
                                                "description": "Formation équipe (3 jours)",
                                                "quantity": 3,
                                                "unit_price": 800,
                                                "vat_rate": 19
                                            }
                                        ],
                                        "stamp_duty": true,
                                        "withholding_tax_rate": 1.5
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Invoice signed and submitted",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SignResponse"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Invalid request body (INVALID_JSON)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid API key (AUTH_INVALID_KEY)"
                    },
                    "402": {
                        "description": "Insufficient credits (INSUFFICIENT_CREDITS)"
                    },
                    "412": {
                        "description": "Seal not provisioned or PIN missing (SEAL_NOT_CONFIGURED)"
                    },
                    "422": {
                        "description": "Validation failed (VALIDATION_FAILED, SELLER_MISMATCH, METHOD_REQUIRES_PREPARE): see error.details"
                    },
                    "429": {
                        "description": "Too many requests (RATE_LIMIT)"
                    },
                    "503": {
                        "description": "Signing service unavailable (SIGNING_FAILED)"
                    },
                    "403": {
                        "description": "Developer key used to issue (DEVELOPER_KEY_NOT_ALLOWED)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Number already issued for different content, or signature in progress (INVOICE_NUMBER_ALREADY_ISSUED, INVOICE_IN_PROGRESS), or number already used by the same issuer on another channel (INVOICE_NUMBER_USED_BY_ISSUER)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/einvoices/prepare": {
            "post": {
                "tags": [
                    "Issue: user signature (asynchronous)"
                ],
                "summary": "Prepare a DigiGo, USB key or E-Houwiya signature (asynchronous)",
                "description": "## User signature\n\n**Asynchronous**: the signer approves it personally, on the signing page (DigiGo: PIN + OTP; USB key: token on their computer; E-Houwiya: smartphone).\n\n### Flow\n1. Your ERP calls `POST /einvoices/prepare` with `method` (`digigo`, `usb` or `mobileid`) and `return_url`\n2. Response: `signing_id` + `signing_url`\n3. Your ERP redirects the user to `signing_url`, without parsing it\n4. The user signs; the signed invoice is submitted to TTN\n5. The user comes back to your `return_url`\n6. You read the result with `GET /einvoices/{signing_id}` until `status: validated`\n\n### Good to know\n- DigiGo and E-Houwiya require the signer's email address on the client (`signer_email`), otherwise `SIGNER_EMAIL_MISSING`\n- Lost link: send the same invoice again and you get the same link (`\"resumed\": true`)\n- To stop: `POST /einvoices/{id}/cancel`, no credit consumed\n- Without a signature, the attempt is abandoned automatically after 30 minutes",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SimulationScenario"
                    }
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/SignRequest"
                            },
                            "examples": {
                                "DigiGo (PIN + OTP)": {
                                    "summary": "DigiGo signature with redirect",
                                    "value": {
                                        "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
                                            }
                                        ],
                                        "method": "digigo",
                                        "return_url": "https://votre-erp.tn/factures/F-2026-001/retour-signature"
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Signature prepared: redirect the user to signing_url",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "status": {
                                                    "type": "string",
                                                    "example": "pending_signature"
                                                },
                                                "signing_id": {
                                                    "type": "string",
                                                    "example": "sg_a7f9c21b3e4d8f6a9b2c1d4e",
                                                    "description": "Unique identifier to track this signature with GET /einvoices/{signing_id}."
                                                },
                                                "signing_url": {
                                                    "type": "string",
                                                    "example": "https://signature-securisee.tn/sign/xa7f9c21",
                                                    "description": "Opaque URL to redirect the user to."
                                                },
                                                "method": {
                                                    "type": "string",
                                                    "example": "digigo"
                                                },
                                                "invoice_number": {
                                                    "type": "string",
                                                    "example": "F-2026-001"
                                                },
                                                "resumed": {
                                                    "type": "boolean",
                                                    "description": "Present and true when a signature was already pending on the same invoice: the link returned is the one already open."
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid API key (AUTH_INVALID_KEY)"
                    },
                    "422": {
                        "description": "Validation failed (VALIDATION_FAILED, INVALID_METHOD): return_url required for digigo, usb and mobileid"
                    },
                    "429": {
                        "description": "Too many requests (RATE_LIMIT)"
                    },
                    "503": {
                        "description": "Signing service unavailable (SIGNING_FAILED)"
                    },
                    "403": {
                        "description": "Developer key used to issue (DEVELOPER_KEY_NOT_ALLOWED)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Signature in progress with different content (INVOICE_IN_PROGRESS): error.details carries signing_url and can_prepare_again_at",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "412": {
                        "description": "Signing account not created yet, or signer email address missing (SIGNER_NOT_CONFIGURED, SIGNER_EMAIL_MISSING)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/einvoices/prepare-batch": {
            "post": {
                "tags": [
                    "Issue: user signature (asynchronous)"
                ],
                "summary": "Prepare signing for a batch (DigiGo, USB key) with a single code",
                "description": "## Batch signing\n\nUp to 20 invoices in a single transaction: the user opens **a single** `signing_url` and enters their code only once. Each invoice keeps its own signature and receives its own `signing_id`, then tracked like a single invoice (`GET /einvoices/{signing_id}`).\n\n### Rules\n- **All or nothing before signing**: one invalid invoice and nothing is sent (`422 BATCH_VALIDATION_FAILED`, details per invoice in `error.details.errors`).\n- `invoice_number` required and unique within the batch.\n- Methods: `digigo` or `usb`.\n- The balance must cover the whole batch; one credit is debited per invoice actually signed.\n- Key attached to a company: Jugurtha plan or higher (`403 PLAN_REQUIRED`).",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "required": ["invoices", "return_url"],
                                "properties": {
                                    "method": {
                                        "type": "string",
                                        "enum": ["digigo", "usb"],
                                        "description": "Default: the mode configured on the client."
                                    },
                                    "return_url": {
                                        "type": "string",
                                        "format": "uri",
                                        "description": "HTTPS return URL after the batch is signed. We append `?efacture_batch={batch_id}` to it."
                                    },
                                    "invoices": {
                                        "type": "array",
                                        "minItems": 1,
                                        "maxItems": 20,
                                        "items": {
                                            "$ref": "#/components/schemas/SignRequest"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "Batch prepared: one signing link, one signing_id per invoice.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {"type": "boolean", "example": true},
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "status": {"type": "string", "example": "pending_signature"},
                                                "batch_id": {"type": "string", "example": "lot_8f3c2a91d0e4b7c6a5f1"},
                                                "signing_url": {"type": "string"},
                                                "method": {"type": "string", "example": "digigo"},
                                                "count": {"type": "integer", "example": 2},
                                                "invoices": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object",
                                                        "properties": {
                                                            "invoice_number": {"type": "string"},
                                                            "signing_id": {"type": "string"},
                                                            "tracking": {"type": "string", "enum": ["available", "unavailable"]}
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "PLAN_REQUIRED or DEVELOPER_KEY_NOT_ALLOWED",
                        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}
                    },
                    "422": {
                        "description": "BATCH_VALIDATION_FAILED, BATCH_TOO_LARGE, BATCH_METHOD_NOT_SUPPORTED, BATCH_NOT_AVAILABLE, VALIDATION_FAILED, INVALID_METHOD",
                        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}
                    },
                    "402": {
                        "description": "INSUFFICIENT_CREDITS: the balance does not cover the whole batch",
                        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ErrorResponse"}}}
                    }
                }
            }
        },
        "/api/v1/einvoices/{id}": {
            "get": {
                "tags": [
                    "Issue: user signature (asynchronous)"
                ],
                "summary": "Read an e-invoice: status and documents (polling)",
                "description": "## Read the result\n\nFor **polling** after `POST /einvoices/prepare`, or to read an invoice again.\n\n| Status | Description |\n|---|---|\n| `pending_signature` | Waiting for the signer; `signing_url` gives the link |\n| `signed` | Signature received, TTN submission in progress |\n| `submitted_ttn` | Submitted to TTN, awaiting confirmation |\n| `validated` | Accepted by TTN: `xml_base64`, `pdf_base64` and reference available |\n| `rejected` | Cancelled or refused: see `signature`, `ttn` and `ttn.next_action` |\n\nThe final reference and the TTN QR code (visible electronic seal, CEV) arrive a few minutes after submission: `ttn.reference_confirmee` then switches to `true`.\n\nEach key only reads its own environment (otherwise `WRONG_ENVIRONMENT`); the developer key sees both.\n\n### Recommended polling\n- First call 5 seconds after `/prepare`, then 10 s, 20 s, 30 s, 60 s…\n- **Stop polling** as soon as `status` is `rejected`, or `validated` with `ttn.reference_confirmee: true`.\n- A signature not completed within 7 days switches to `rejected` on its own, `error.code = SIGNATURE_EXPIRED`, with no credit debited. Restart it with a new `POST /einvoices/prepare` for the same number, and track the **new** `signing_id`.\n- The signing service is queried at most once every 30 seconds per invoice: polling more often returns the same status.\n\n### Which message to display\n`error` (at the root) carries the reason for any rejection. `ttn.error` is only filled if TTN refused an **already signed** document; it then carries the same code and the same message. Display `error.message`.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "The signing_id returned at issuance (format sg_...)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Current status, and documents when they exist",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean"
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "signing_id": {
                                                    "type": "string"
                                                },
                                                "invoice_number": {
                                                    "type": "string",
                                                    "example": "F-2026-001"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "enum": [
                                                        "pending_signature",
                                                        "signed",
                                                        "submitted_ttn",
                                                        "validated",
                                                        "rejected"
                                                    ],
                                                    "example": "validated"
                                                },
                                                "ttn_reference": {
                                                    "type": "string",
                                                    "example": "TTN-2026-XXXXX"
                                                },
                                                "xml_base64": {
                                                    "type": "string",
                                                    "description": "Signed XML, available once signed."
                                                },
                                                "pdf_base64": {
                                                    "type": "string",
                                                    "description": "PDF, available once signed; the TTN QR code is affixed on confirmation."
                                                },
                                                "method": {
                                                    "type": "string",
                                                    "example": "digigo"
                                                },
                                                "signing_url": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "description": "Signing link, while the signature is pending."
                                                },
                                                "documents_purged_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true,
                                                    "description": "Documents (XML, PDF) are kept for 90 days. After that, they are deleted: the XML and PDF fields return null and this date says so."
                                                },
                                                "error": {
                                                    "type": "object",
                                                    "nullable": true,
                                                    "description": "The invoice error, whichever stage failed. When the refusal comes from TTN after signing, ttn.error carries the same error.",
                                                    "properties": {
                                                        "code": {
                                                            "type": "string",
                                                            "example": "SIGNATURE_EXPIRED"
                                                        },
                                                        "message": {
                                                            "type": "string"
                                                        }
                                                    },
                                                    "description": "Reason for the rejection when status = rejected (SIGNATURE_EXPIRED, ABANDONED_ATTEMPT, TTN_REJECTED…). Null otherwise. This is the one to display."
                                                },
                                                "signature": {
                                                    "type": "object",
                                                    "properties": {
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "pending",
                                                                "signed",
                                                                "rejected",
                                                                "unknown"
                                                            ]
                                                        },
                                                        "signed_xml_available": {
                                                            "type": "boolean"
                                                        }
                                                    }
                                                },
                                                "ttn": {
                                                    "type": "object",
                                                    "properties": {
                                                        "status": {
                                                            "type": "string",
                                                            "enum": [
                                                                "not_reached",
                                                                "submitted",
                                                                "validated",
                                                                "rejected"
                                                            ]
                                                        },
                                                        "reference": {
                                                            "type": "string",
                                                            "nullable": true
                                                        },
                                                        "reference_confirmee": {
                                                            "type": "boolean",
                                                            "description": "True once the final reference and the QR code from TTN have been received."
                                                        },
                                                        "confirmed_at": {
                                                            "type": "string",
                                                            "format": "date-time",
                                                            "nullable": true
                                                        },
                                                        "qr_png_base64": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "description": "The QR code (visible electronic seal, CEV) produced by TTN, as a PNG image."
                                                        },
                                                        "error": {
                                                            "type": "object",
                                                            "nullable": true,
                                                            "properties": {
                                                                "code": {
                                                                    "type": "string",
                                                                    "example": "SIGNATURE_EXPIRED"
                                                                },
                                                                "message": {
                                                                    "type": "string"
                                                                }
                                                            },
                                                            "description": "Filled only if TTN refused an already signed document: same code and same message as error."
                                                        },
                                                        "next_action": {
                                                            "type": "string",
                                                            "nullable": true,
                                                            "enum": [
                                                                "resubmit",
                                                                "resign"
                                                            ],
                                                            "description": "After a TTN refusal: resubmit as is, or sign again."
                                                        }
                                                    }
                                                },
                                                "xml_validettn_base64": {
                                                    "type": "string",
                                                    "nullable": true,
                                                    "description": "The final document validated by TTN (with its reference and seal): the one to archive."
                                                },
                                                "can_prepare_again_at": {
                                                    "type": "string",
                                                    "format": "date-time",
                                                    "nullable": true,
                                                    "description": "While a signature is pending: time at which the number can be prepared again."
                                                },
                                                "test_mode": {
                                                    "type": "boolean"
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "401": {
                        "description": "Invalid API key (AUTH_INVALID_KEY)"
                    },
                    "404": {
                        "description": "No invoice has this signing_id (NOT_FOUND)"
                    },
                    "403": {
                        "description": "Invoice belonging to another account or another environment (PERMISSION_DENIED, WRONG_ENVIRONMENT)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/einvoices/{id}/resubmit-ttn": {
            "post": {
                "tags": [
                    "Track an invoice"
                ],
                "summary": "Resubmit to TTN without signing again",
                "description": "Resubmits the signed document as is, with no new signature and no credit, when the submission failed for a reason external to the document (ttn.next_action = resubmit). Empty body.",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/SimulationScenario"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "The signing_id returned at issuance (format sg_...)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Document resubmitted: status validated or submitted_ttn",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "signing_id": {
                                                    "type": "string"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "example": "validated"
                                                },
                                                "ttn_reference": {
                                                    "type": "string"
                                                },
                                                "credits_consumed": {
                                                    "type": "integer",
                                                    "example": 0
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Developer key, or invoice belonging to another account or another environment",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No invoice has this signing_id (NOT_FOUND)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Nothing to resend, or resending is pointless (NOT_SIGNED, AWAITING_TTN, ALREADY_VALIDATED, DEPOSIT_DELEGATED, RESIGN_REQUIRED, DOCUMENTS_PURGED)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "TTN refuses or does not respond (TTN_DEPOSIT_FAILED)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/einvoices/{id}/cancel": {
            "post": {
                "tags": [
                    "Track an invoice"
                ],
                "summary": "Cancel a pending signature",
                "description": "Stops a signature opened by /prepare and not yet completed. No credit is consumed; if the user signs at the same moment, the invoice is treated as signed, with a single credit. Empty body.",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "The signing_id returned at issuance (format sg_...)."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Signature cancelled: the number can be prepared again right away",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "signing_id": {
                                                    "type": "string"
                                                },
                                                "invoice_number": {
                                                    "type": "string"
                                                },
                                                "status": {
                                                    "type": "string",
                                                    "example": "cancelled"
                                                },
                                                "credits_consumed": {
                                                    "type": "integer",
                                                    "example": 0
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Developer key, or invoice belonging to another account or another environment",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "No invoice has this signing_id (NOT_FOUND)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "Too late or not available (ALREADY_SIGNED, SIGNATURE_ALREADY_CLOSED, CANCEL_NOT_SUPPORTED)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "502": {
                        "description": "Cancellation not confirmed, nothing is cancelled or debited (CANCEL_UNCONFIRMED)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/credits/balance": {
            "get": {
                "tags": [
                    "Credits"
                ],
                "summary": "Credit balance",
                "description": "Current balance, total consumed and total purchased for the wallet.",
                "responses": {
                    "200": {
                        "description": "Credit balance",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "success": {
                                            "type": "boolean",
                                            "example": true
                                        },
                                        "data": {
                                            "type": "object",
                                            "properties": {
                                                "balance": {
                                                    "type": "integer",
                                                    "example": 4230
                                                },
                                                "total_used": {
                                                    "type": "integer",
                                                    "example": 770
                                                },
                                                "total_purchased": {
                                                    "type": "integer",
                                                    "example": 5000
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/clients": {
            "get": {
                "tags": [
                    "Clients (developer key)"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "summary": "List your clients",
                "description": "Developer key (sk_dev_). All your clients, secrets masked, with credits, statistics and wallet balance.",
                "responses": {
                    "200": {
                        "description": "List of clients and wallet"
                    },
                    "403": {
                        "description": "Client key used instead of the developer key",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            },
            "post": {
                "tags": [
                    "Clients (developer key)"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "summary": "Create a client",
                "description": "Developer key (sk_dev_). Creates a client and returns its ck_test_ / ck_live_ keys. Add provision to create its signing account at the same time.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "example": "Société ABC"
                                    },
                                    "matricule": {
                                        "type": "string",
                                        "example": "1234567RAM000"
                                    },
                                    "signer_method": {
                                        "type": "string",
                                        "enum": [
                                            "seal",
                                            "usb",
                                            "digigo",
                                            "mobileid"
                                        ]
                                    },
                                    "signer_email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "Email address of the signer's DigiGo or E-Houwiya certificate. Required for digigo and mobileid."
                                    },
                                    "seal_passphrase_test": {
                                        "type": "string",
                                        "description": "PIN of the sandbox seal. Masked on read."
                                    },
                                    "seal_passphrase_prod": {
                                        "type": "string",
                                        "description": "PIN of the live seal. Masked on read."
                                    },
                                    "submission_channel": {
                                        "type": "string",
                                        "enum": [
                                            "delegated",
                                            "soap",
                                            "sftp"
                                        ],
                                        "description": "Who submits to TTN: delegated (the signing service, default), soap or sftp (us, with the client's TTN access)."
                                    },
                                    "credit_cap": {
                                        "type": "integer",
                                        "nullable": true,
                                        "description": "Client's credit cap; null = unlimited."
                                    },
                                    "ttn": {
                                        "type": "object",
                                        "description": "TTN access per environment: sandbox / prod, each { login, password }."
                                    },
                                    "provision": {
                                        "type": "string",
                                        "enum": [
                                            "sandbox",
                                            "production",
                                            "both"
                                        ],
                                        "description": "Creates or updates the client's signing account."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "201": {
                        "description": "Client created, keys in data.keys"
                    },
                    "422": {
                        "description": "Invalid field, tax ID missing or already registered (VALIDATION_FAILED)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/clients/{id}": {
            "get": {
                "tags": [
                    "Clients (developer key)"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "summary": "Read a client",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Client identifier."
                    }
                ],
                "description": "Configuration, credits, statistics and API keys of the client (passwords masked).",
                "responses": {
                    "200": {
                        "description": "The client"
                    },
                    "404": {
                        "description": "Client not found (NOT_FOUND)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            },
            "patch": {
                "tags": [
                    "Clients (developer key)"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "summary": "Update a client",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Client identifier."
                    }
                ],
                "description": "Partial update: only the fields sent change. An omitted password is kept.",
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string",
                                        "example": "Société ABC"
                                    },
                                    "matricule": {
                                        "type": "string",
                                        "example": "1234567RAM000"
                                    },
                                    "signer_method": {
                                        "type": "string",
                                        "enum": [
                                            "seal",
                                            "usb",
                                            "digigo",
                                            "mobileid"
                                        ]
                                    },
                                    "signer_email": {
                                        "type": "string",
                                        "format": "email",
                                        "description": "Email address of the signer's DigiGo or E-Houwiya certificate. Required for digigo and mobileid."
                                    },
                                    "seal_passphrase_test": {
                                        "type": "string",
                                        "description": "PIN of the sandbox seal. Masked on read."
                                    },
                                    "seal_passphrase_prod": {
                                        "type": "string",
                                        "description": "PIN of the live seal. Masked on read."
                                    },
                                    "submission_channel": {
                                        "type": "string",
                                        "enum": [
                                            "delegated",
                                            "soap",
                                            "sftp"
                                        ],
                                        "description": "Who submits to TTN: delegated (the signing service, default), soap or sftp (us, with the client's TTN access)."
                                    },
                                    "credit_cap": {
                                        "type": "integer",
                                        "nullable": true,
                                        "description": "Client's credit cap; null = unlimited."
                                    },
                                    "ttn": {
                                        "type": "object",
                                        "description": "TTN access per environment: sandbox / prod, each { login, password }."
                                    },
                                    "provision": {
                                        "type": "string",
                                        "enum": [
                                            "sandbox",
                                            "production",
                                            "both"
                                        ],
                                        "description": "Creates or updates the client's signing account."
                                    }
                                }
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "The updated client"
                    },
                    "404": {
                        "description": "Client not found (NOT_FOUND)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "422": {
                        "description": "Invalid field (VALIDATION_FAILED)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            },
            "delete": {
                "tags": [
                    "Clients (developer key)"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "summary": "Delete a client",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Client identifier."
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Client deleted (data.deleted = true)"
                    },
                    "404": {
                        "description": "Client not found (NOT_FOUND)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/v1/clients/{id}/keys": {
            "post": {
                "tags": [
                    "Clients (developer key)"
                ],
                "security": [
                    {
                        "ApiKeyAuth": []
                    }
                ],
                "summary": "Regenerate a client's keys",
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Client identifier."
                    }
                ],
                "description": "The old keys stop working immediately; the new ones are returned in data.keys.",
                "responses": {
                    "200": {
                        "description": "New keys"
                    },
                    "404": {
                        "description": "Client not found (NOT_FOUND)",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error (INTERNAL_ERROR), always in JSON.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "Service temporarily unavailable (SERVICE_UNAVAILABLE): retry after Retry-After.",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/ErrorResponse"
                                }
                            }
                        },
                        "headers": {
                            "Retry-After": {
                                "description": "Seconds to wait before retrying.",
                                "schema": {
                                    "type": "integer",
                                    "example": 30
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "tags": [
        {
            "name": "General",
            "description": "Platform status."
        },
        {
            "name": "Issue: server seal (synchronous)",
            "description": "Validate, then sign and submit in one request."
        },
        {
            "name": "Issue: user signature (asynchronous)",
            "description": "DigiGo, USB key, E-Houwiya."
        },
        {
            "name": "Track an invoice",
            "description": "Read, resubmit to TTN, cancel a pending signature."
        },
        {
            "name": "Credits",
            "description": "Wallet balance."
        },
        {
            "name": "Clients (developer key)",
            "description": "Create and configure your clients with your sk_dev_ key."
        }
    ]
}
