Skip to main content

Reference, limits and downloads

Error handling​

Cloud session-validation errors​

CodeHTTPMeaning
"Origin ... not allowed by CORS"500⚠️ Not the same as ORIGIN_NOT_WHITELISTED — see the CORS limitation described in Authentication and signing
PARTNER_NOT_FOUND403partnerAppId doesn't match a registered partner
NOT_SIGNER_PARTNER403Profile's partner_type isn't signer/both
PLAN_NOT_ELIGIBLE403Subscription isn't an active/trial partner-signer/partner-signer-pro plan
ORIGIN_NOT_WHITELISTED403Calling domain not in your whitelist
CLIENT_NOT_PRE_REGISTERED403End client's tax ID isn't pre-registered (or inactive)

Local agent errors​

CodeHTTPMeaning
"Invalid or expired token"401Re-authenticate the client and open a new session
Missing/invalid X-Fatoora-Signer-Session401Session expired or was never opened
SIGN_FAILED (and other business errorCode values)200Check the PIN, that the token is inserted, and the PKCS#11 driver — not an HTTP-level error
(native library failure)500PKCS#11 driver couldn't load — reinstall/reconfigure the agent

Domain/client management errors​

CodeHTTPMeaning
DOMAIN_ALREADY_EXISTS409Domain already whitelisted
DOMAIN_LIMIT_REACHED / CLIENT_LIMIT_REACHED403Your plan's limit reached
VALIDATION_ERROR400Malformed request body

Rate limits and quotas​

LimiterScopeLimit
/api/partner/signer/*per IP300 requests / 15 min
Local agent (127.0.0.1:38443/*)—None — single-user local process
PlanMax domainsMax clientsTrial
partner-signer15014 days
partner-signer-pro530014 days

No signing-volume cap on either plan.

Code example​

# 1. Authenticate the end client
ACCESS_TOKEN=$(curl -s -X POST "https://business.fatoora.tn/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"client@example.com","password":"..."}' | jq -r '.accessToken')

# 2. Open a local bridge session
SESSION_ID=$(curl -s -X POST "http://127.0.0.1:38443/api/web-bridge/v1/session" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Partner-App-ID: YOUR_PARTNER_APP_ID" | jq -r '.sessionId')

# 3. Sign a TEIF XML document
curl -s -X POST "http://127.0.0.1:38443/api/web-bridge/v1/xml/sign" \
  -H "Content-Type: application/json" \
  -H "X-Fatoora-Signer-Session: $SESSION_ID" \
  -d '{"xml":"<Invoice>...</Invoice>","pin":"1234","signerRole":"CEO","includeChain":true}'

# 4. Close the session
curl -s -X DELETE "http://127.0.0.1:38443/api/web-bridge/v1/session" \
  -H "X-Fatoora-Signer-Session: $SESSION_ID"

More examples (browser-side JavaScript, domain/client management) are in the full PDF guide below.

Partner API vs. Partner Signer​

Partner APIPartner Signer (this category)
Planspartner-starter/business/maxpartner-signer, partner-signer-pro
ModelServer-to-server REST API (OAuth2)Local PKCS#11/browser signing bridge
Hosts involvedOne (business.fatoora.tn)Two (business.fatoora.tn + local agent 127.0.0.1:38443)
Client onboardingOTP-based authorizationDirect pre-registration by tax ID, no OTP
Direct TTN submissionBlockedAllowed, from the local agent
Domain restrictionNoneRequired — domain whitelist

See the Partner API category for that other offering.

Download the full technical documentation​

This category covers the essential integration workflow. For the exhaustive technical specification — the full session-validation flow, every error code, request/response structures, multi-language examples, and the OpenAPI spec plus Postman collection embedded as file attachments in the PDF — download the full guide:

Also available from your dashboard

Once your partner application is created, find the same files from Fatoora dashboard → Partner → Credentials → Signer guide.