Authentification et signature

Architecture à deux hôtes

	Fatoora Cloud (business.fatoora.tn)	FatooraSigner (127.0.0.1:38443)
Tourne où	Serveurs Fatoora	Machine du client final (agent installé)
Protocole	HTTPS	HTTP simple — pas de TLS par défaut
Vous gérez	Whitelist de domaines, pré-enregistrement clients	Rien — c'est l'installation locale du client
Applique	Votre whitelist allowed_domains + liste de clients pré-enregistrés	Une politique CORS séparée et plus large (localhost, 127.0.0.1, *.fatoora.tn)

Limitation connue — un troisième filtre CORS non documenté

Une requête d'ouverture de session traverse en réalité trois couches, pas deux :

1. Navigateur → agent local : la politique CORS de l'agent (ci-dessus).
2. Agent local → Fatoora Cloud (GET /api/auth/trust-signer-session) : le middleware CORS global de fatooraBusiness, piloté par la variable serveur CORS_ORIGINS — totalement indépendant de votre whitelist allowed_domains en libre-service.
3. Logique métier cloud : votre vérification allowed_domains, qui renvoie normalement 403 ORIGIN_NOT_WHITELISTED.

Whitelister votre domaine via POST /api/partner/signer/domains est nécessaire mais pas suffisant — l'équipe Fatoora doit aussi ajouter votre domaine à la configuration serveur CORS_ORIGINS, une étape que vous ne pouvez pas faire vous-même. Si vos appels échouent avec un 500 mentionnant "not allowed by CORS" plutôt que le 403 ORIGIN_NOT_WHITELISTED attendu, c'est cette cause — contactez le support Fatoora pour faire ajouter votre domaine côté serveur.

Flux de session

Étape A — Connexion du client final (cloud)

POST https://business.fatoora.tn/api/auth/login
{ "email": "client@example.com", "password": "..." }
→ 200 { "accessToken": "eyJhbGc..." }

Étape B — Ouverture d'une session de pont locale

POST http://127.0.0.1:38443/api/web-bridge/v1/session
Authorization: Bearer <accessToken>
X-Partner-App-ID: <votre partnerAppId>

L'agent transmet votre JWT à GET /api/auth/trust-signer-session, qui vérifie dans l'ordre : app partenaire existante → partner_type compatible → abonnement actif/trial → domaine whitelisté → matricule client pré-enregistré.

Réponse de succès :

{ "sessionId": "sess_xxxxxxxx", "idleExpiresAt": "2026-07-11T15:00:00Z", "partnerMode": true }

Utilisez sessionId comme en-tête X-Fatoora-Signer-Session sur chaque appel suivant. Timeout d'inactivité par défaut : 1 heure.

Opérations de signature

Toutes nécessitent X-Fatoora-Signer-Session et ciblent l'agent local.

Endpoint	Rôle
GET /api/web-bridge/v1/tokens/certificates	Liste les certificats publics du token — sans PIN
POST /api/web-bridge/v1/tokens/detect-with-certificates	Détecte le token et lit les certificats (PIN requis)
POST /api/web-bridge/v1/xml/sign	Signature — l'appel principal
POST /api/web-bridge/v1/xml/inspect	Vérifie une signature déjà présente dans un document

POST /xml/sign renvoie toujours 200, vérifiez le champ ok :

{ "mode": "sign", "ok": true, "signedXml": "<Invoice>...(signé)...</Invoice>" }

ou { "mode": "sign", "ok": false, "error": "Invalid PIN", "errorCode": "SIGN_FAILED" }.

Soumettre directement à TTN

Contrairement à Partner API (où les tokens partenaires sont bloqués), l'agent local FatooraSigner peut soumettre directement à TTN, avec les identifiants TTN du client, saisis localement et jamais envoyés à vos serveurs :

POST /api/web-bridge/v1/credentials/encrypt-ttn   { "login": "...", "password": "...", "matricule": "..." }
GET  /api/web-bridge/v1/ttn/check-availability?ttnMode=PROD
POST /api/web-bridge/v1/ttn/save-efact             { "encryptedCredential": "...", "documentEfact": "<base64>", "ttnMode": "PROD" }
POST /api/web-bridge/v1/ttn/consult-efact

Les identifiants sont chiffrés en AES-256-GCM, en mémoire uniquement — jamais écrits sur disque ni envoyés à Fatoora Cloud.

Étape suivante : Gestion des domaines et clients.