{ "info": { "name": "Fatoora Partner Signer — Web Bridge", "description": "Integration guide for Fatoora Partner Signer. Covers user authentication, local bridge session management, XML signing and inspection via FatooraSigner running at 127.0.0.1:38443.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "variable": [ { "key": "business_url", "value": "https://business.fatoora.tn", "type": "string" }, { "key": "signer_url", "value": "http://127.0.0.1:38443", "type": "string" }, { "key": "partner_app_id", "value": "YOUR_PARTNER_APP_ID", "type": "string" }, { "key": "user_email", "value": "", "type": "string" }, { "key": "user_password", "value": "", "type": "string" }, { "key": "access_token", "value": "", "type": "string" }, { "key": "session_id", "value": "", "type": "string" }, { "key": "token_pin", "value": "", "type": "string" } ], "item": [ { "name": "1 — User authentication", "item": [ { "name": "POST /api/auth/login (get JWT)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"email\": \"{{user_email}}\",\n \"password\": \"{{user_password}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{business_url}}/api/auth/login", "host": [ "{{business_url}}/api/auth/login" ] }, "description": "Authenticate the end-user and retrieve an access token. Save 'accessToken' to the 'access_token' variable." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{business_url}}/api/auth/login", "host": [ "{{business_url}}/api/auth/login" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"accessToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VyX3h4eHgifQ.SIGNATURE\",\n \"refreshToken\": \"eyJhbGciOiJIUzI1NiIs...\",\n \"expiresIn\": 900\n}" }, { "name": "401 Unauthorized — wrong credentials", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "url": { "raw": "{{business_url}}/api/auth/login", "host": [ "{{business_url}}/api/auth/login" ] } }, "status": "Unauthorized", "code": 401, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"INVALID_CREDENTIALS\",\n \"message\": \"Invalid email or password.\"\n}" } ] }, { "name": "POST /api/auth/refresh (refresh JWT)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/auth/refresh", "host": [ "{{business_url}}/api/auth/refresh" ] }, "description": "Refresh an expiring access token." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/auth/refresh", "host": [ "{{business_url}}/api/auth/refresh" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"accessToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...NEW\",\n \"expiresIn\": 900\n}" } ] } ] }, { "name": "2 — Local bridge session management", "item": [ { "name": "POST /session (open bridge session)", "request": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "X-Partner-App-ID", "value": "{{partner_app_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/session", "host": [ "{{signer_url}}/api/web-bridge/v1/session" ] }, "description": "Opens a local bridge session on the client's machine. Requires FatooraSigner running at 127.0.0.1. The X-Partner-App-ID header activates partner-signer validation (allowed domains + pre-registered client check). Save 'sessionId' to the 'session_id' variable." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "X-Partner-App-ID", "value": "{{partner_app_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/session", "host": [ "{{signer_url}}/api/web-bridge/v1/session" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"sessionId\": \"sess_xxxxxxxxxxxxxxxx\",\n \"idleExpiresAt\": \"2026-07-11T15:00:00Z\",\n \"absoluteExpiresAt\": null,\n \"partnerMode\": true,\n \"partnerAppId\": \"{{partner_app_id}}\"\n}" }, { "name": "403 Forbidden — domain not whitelisted", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "X-Partner-App-ID", "value": "{{partner_app_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/session", "host": [ "{{signer_url}}/api/web-bridge/v1/session" ] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"ORIGIN_NOT_WHITELISTED\"\n}" }, { "name": "403 Forbidden — client not pre-registered", "originalRequest": { "method": "POST", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" }, { "key": "X-Partner-App-ID", "value": "{{partner_app_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/session", "host": [ "{{signer_url}}/api/web-bridge/v1/session" ] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"CLIENT_NOT_PRE_REGISTERED\"\n}" } ] }, { "name": "DELETE /session (close bridge session)", "request": { "method": "DELETE", "header": [ { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/session", "host": [ "{{signer_url}}/api/web-bridge/v1/session" ] }, "description": "Closes the bridge session. Call on user logout." }, "response": [ { "name": "204 No Content", "originalRequest": { "method": "DELETE", "header": [ { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/session", "host": [ "{{signer_url}}/api/web-bridge/v1/session" ] } }, "status": "No Content", "code": 204, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "" } ] } ] }, { "name": "3 — PKCS#11 token", "item": [ { "name": "GET /tokens/certificates (public certs, no PIN)", "request": { "method": "GET", "header": [ { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/tokens/certificates", "host": [ "{{signer_url}}/api/web-bridge/v1/tokens/certificates" ] }, "description": "Lists public certificates on the USB token without requiring a PIN." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [ { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/tokens/certificates", "host": [ "{{signer_url}}/api/web-bridge/v1/tokens/certificates" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"certificates\": [\n {\n \"slotId\": 0,\n \"keyAlias\": \"TunTrust Signing Key\",\n \"subject\": \"CN=John Doe,O=Client SARL,C=TN\",\n \"sha1\": \"0123456789ABCDEF0123456789ABCDEF01234567\",\n \"validFrom\": \"2025-01-01T00:00:00Z\",\n \"validTo\": \"2028-01-01T00:00:00Z\"\n }\n ]\n}" } ] }, { "name": "POST /tokens/detect-with-certificates (with PIN)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "body": { "mode": "raw", "raw": "{\n \"pin\": \"{{token_pin}}\",\n \"driverId\": null\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{signer_url}}/api/web-bridge/v1/tokens/detect-with-certificates", "host": [ "{{signer_url}}/api/web-bridge/v1/tokens/detect-with-certificates" ] }, "description": "Detects PKCS#11 tokens and reads certificate details. PIN is required. The PIN never leaves the client machine." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/tokens/detect-with-certificates", "host": [ "{{signer_url}}/api/web-bridge/v1/tokens/detect-with-certificates" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"driverId\": \"opensc\",\n \"slots\": [\n {\n \"slotId\": 0,\n \"label\": \"TunTrust Card\",\n \"certificates\": [\n {\n \"keyAlias\": \"TunTrust Signing Key\",\n \"subject\": \"CN=John Doe,O=Client SARL,C=TN\",\n \"sha1\": \"0123456789ABCDEF0123456789ABCDEF01234567\"\n }\n ]\n }\n ]\n}" }, { "name": "200 OK — wrong PIN (business error)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/tokens/detect-with-certificates", "host": [ "{{signer_url}}/api/web-bridge/v1/tokens/detect-with-certificates" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"ok\": false,\n \"error\": \"Invalid PIN\",\n \"errorCode\": \"INVALID_PIN\"\n}" } ] } ] }, { "name": "4 — XML signature", "item": [ { "name": "POST /xml/sign (sign TEIF document)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "body": { "mode": "raw", "raw": "{\n \"xml\": \"{{teif_xml}}\",\n \"pin\": \"{{token_pin}}\",\n \"signerRole\": \"CEO\",\n \"includeChain\": true\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{signer_url}}/api/web-bridge/v1/xml/sign", "host": [ "{{signer_url}}/api/web-bridge/v1/xml/sign" ] }, "description": "Signs a TEIF XML document using the client's local USB token. Returns 'signedXml'. Check 'ok' and 'errorCode' fields — a 200 response can still contain a business error." }, "response": [ { "name": "200 OK — signed", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/xml/sign", "host": [ "{{signer_url}}/api/web-bridge/v1/xml/sign" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"mode\": \"sign\",\n \"ok\": true,\n \"signedXml\": \"...(signed)...\",\n \"signatureLevel\": \"XAdES-BASELINE-B\"\n}" }, { "name": "200 OK — business error (wrong PIN)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/xml/sign", "host": [ "{{signer_url}}/api/web-bridge/v1/xml/sign" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"mode\": \"sign\",\n \"ok\": false,\n \"error\": \"Invalid PIN\",\n \"errorCode\": \"SIGN_FAILED\"\n}" } ] }, { "name": "POST /xml/inspect (inspect signed XML)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "body": { "mode": "raw", "raw": "{\n \"xml\": \"{{signed_teif_xml}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{signer_url}}/api/web-bridge/v1/xml/inspect", "host": [ "{{signer_url}}/api/web-bridge/v1/xml/inspect" ] }, "description": "Verifies signatures in a signed XML. Returns DSS validation details." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "X-Fatoora-Signer-Session", "value": "{{session_id}}" } ], "url": { "raw": "{{signer_url}}/api/web-bridge/v1/xml/inspect", "host": [ "{{signer_url}}/api/web-bridge/v1/xml/inspect" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"valid\": true,\n \"signatureLevel\": \"XAdES-BASELINE-B\",\n \"signerCertificate\": {\n \"subject\": \"CN=John Doe,O=Client SARL,C=TN\",\n \"issuer\": \"CN=TunTrust CA\"\n },\n \"revocationStatus\": \"GOOD\"\n}" } ] } ] }, { "name": "5 — Domain & client management (partner)", "item": [ { "name": "GET /api/partner/signer/domains", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/partner/signer/domains", "host": [ "{{business_url}}/api/partner/signer/domains" ] }, "description": "Lists domains allowed to initiate bridge sessions for this partner app." }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/partner/signer/domains", "host": [ "{{business_url}}/api/partner/signer/domains" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"domains\": [\n {\n \"id\": \"domain_0\",\n \"domain\": \"yourapp.example.com\"\n }\n ],\n \"total\": 1,\n \"partnerId\": \"{{partner_app_id}}\"\n}" } ] }, { "name": "POST /api/partner/signer/domains", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"domain\": \"yourapp.example.com\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{business_url}}/api/partner/signer/domains", "host": [ "{{business_url}}/api/partner/signer/domains" ] }, "description": "Whitelists a bare hostname (no scheme) — subdomains of a whitelisted domain also match." }, "response": [ { "name": "201 Created", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/partner/signer/domains", "host": [ "{{business_url}}/api/partner/signer/domains" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"success\": true,\n \"domain\": \"yourapp.example.com\",\n \"totalDomains\": 1\n}" }, { "name": "409 Conflict — already whitelisted", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/partner/signer/domains", "host": [ "{{business_url}}/api/partner/signer/domains" ] } }, "status": "Conflict", "code": 409, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"DOMAIN_ALREADY_EXISTS\",\n \"message\": \"Domain already whitelisted.\"\n}" }, { "name": "403 Forbidden — plan limit reached", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/partner/signer/domains", "host": [ "{{business_url}}/api/partner/signer/domains" ] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"DOMAIN_LIMIT_REACHED\",\n \"message\": \"Your plan allows a maximum of 1 whitelisted domain(s). Upgrade to add more.\",\n \"limit\": 1\n}" } ] }, { "name": "GET /api/partner/signer/clients", "request": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/partner/signer/clients", "host": [ "{{business_url}}/api/partner/signer/clients" ] } }, "response": [ { "name": "200 OK", "originalRequest": { "method": "GET", "header": [ { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/partner/signer/clients", "host": [ "{{business_url}}/api/partner/signer/clients" ] } }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"clients\": [\n {\n \"id\": \"client_xxxx\",\n \"taxId\": \"1234567ABC000\",\n \"clientName\": \"Client SARL\",\n \"isActive\": true,\n \"createdAt\": \"2026-07-11T00:00:00Z\"\n }\n ],\n \"total\": 1\n}" } ] }, { "name": "POST /api/partner/signer/clients", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "body": { "mode": "raw", "raw": "{\n \"taxId\": \"{{client_tax_id}}\",\n \"clientName\": \"{{client_name}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{business_url}}/api/partner/signer/clients", "host": [ "{{business_url}}/api/partner/signer/clients" ] }, "description": "Pre-registers a client tax ID so FatooraSigner accepts bridge sessions for this org." }, "response": [ { "name": "201 Created", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/partner/signer/clients", "host": [ "{{business_url}}/api/partner/signer/clients" ] } }, "status": "Created", "code": 201, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"id\": \"client_xxxx\",\n \"taxId\": \"1234567ABC000\",\n \"clientName\": \"Client SARL\",\n \"isActive\": true,\n \"createdAt\": \"2026-07-11T00:00:00Z\"\n}" }, { "name": "403 Forbidden — plan limit reached", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Authorization", "value": "Bearer {{access_token}}" } ], "url": { "raw": "{{business_url}}/api/partner/signer/clients", "host": [ "{{business_url}}/api/partner/signer/clients" ] } }, "status": "Forbidden", "code": 403, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"error\": \"CLIENT_LIMIT_REACHED\",\n \"message\": \"Your plan allows a maximum of 50 pre-registered client(s). Upgrade to add more.\",\n \"limit\": 50\n}" } ] } ] } ] }