Reference, limits and downloads

What partner applications cannot do

Even with all scopes granted, several capabilities remain restricted to the organization's own API keys:

• Direct TTN submission — POST /api/core-proxy/invoices/:id/submit-ttn returns 403 PARTNER_NOT_ALLOWED for a partner token. Always use sign-and-send instead.
• Webhook management — /api/core-proxy/webhooks* endpoints return 401 PARTNER_CONTEXT_NOT_ALLOWED. Webhooks are configured by the client itself, on their own keys.
• listCreatorScope=ORG list filters — blocked for partner tokens (401 LIST_ORG_SCOPE_NOT_ALLOWED).
• Editing client invoices from the Fatoora UI — once submitted via your API, invoices are read-only to the client.
• Acting without an authorized org_id — an app-only token can only call the two discovery endpoints (organizations).

Error handling

Most common error codes:

Code	HTTP	Meaning / fix
invalid_client	401	Wrong client_id/client_secret
access_denied	403	Org not authorized, or app not a partner app
INSUFFICIENT_SCOPES	401/403	Request the missing scope from the client (re-approval flow)
ORG_NOT_FOUND	404	Tax ID doesn't match an org that authorized you
PARTNER_NOT_ALLOWED	403	Endpoint not available to partner tokens
VALIDATION_ERROR / INVOICE_VALIDATION_ERROR	400/422	TEIF payload fails validation — check details[]
NO_SIGNATURE_CREDITS	402	Client org's signing quota is exhausted
SUBSCRIPTION_INACTIVE	402	Your own Partner API subscription is paused/cancelled/expired
RATE_LIMIT_EXCEEDED / TOO_MANY_REQUESTS	429	Back off and retry

Rate limits and quotas

Limiter	Scope	Limit
POST /oauth/token	per IP	30 requests / 15 min
Other /api/* calls	per IP	300 requests / 15 min

Plan-level quotas (independent of rate limits):

• monthlyDocLimit — total invoices across all client orgs, per calendar month (varies by partner-starter/business/max).
• maxOrgs — how many client organizations can be authorized at once.
• During the trial period, every plan is capped at 100 documents, regardless of tier.

Code example

# 1. App-only token
curl -X POST "https://business.fatoora.tn/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

# 2. Org-scoped token, then submission
curl -X POST "https://business.fatoora.tn/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "org_id=TARGET_ORG_UUID"

curl -X POST "https://business.fatoora.tn/api/core-proxy/invoices/submit" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @invoice.json

More examples (JavaScript, Python, signing and job tracking) are in the full PDF guide below.

Partner API vs. Partner Signer

	Partner API (this category)	Partner Signer
Plans	partner-starter/business/max	partner-signer, partner-signer-pro
Model	Server-to-server REST API (OAuth2)	Local PKCS#11/browser signing bridge
What you submit	Full TEIF invoices, on behalf of clients	Nothing — you only broker local signing sessions
Client onboarding	OTP-based authorization, per organization	Direct pre-registration by tax ID, no OTP
Domain restriction	None	Required — domain whitelist

See the Partner Signer category for that other offering.

Download the full technical documentation

This category covers the essential integration workflow. For the exhaustive technical specification — detailed response schemas, every error code, the full TEIF structure, multi-language examples, and the OpenAPI spec plus Postman collection embedded as file attachments in the PDF — download the full guide:

• 📄 Full Partner API Guide (PDF) — the PDF already embeds the OpenAPI file and Postman collection as downloadable attachments (paperclip icon) in a compatible PDF viewer (Adobe Acrobat/Reader).
• 🔧 OpenAPI specification (YAML) — direct link, if you'd rather not open the PDF.
• 📦 Postman collection (JSON) — direct link, ready to import into Postman.

Also available from your dashboard

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