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)	Fatoora Connect	Partner Signer
Plans	partner-starter/business/max	partner-connect-starter/business/max	partner-signer, partner-signer-pro
Model	Server-to-server REST API (OAuth2)	The same invoicing API, plus company management	Local PKCS#11/browser signing bridge
What you submit	Full TEIF invoices, on behalf of clients	The same invoices, for child or linked companies, each with its own seal	Nothing — you only broker local signing sessions
Client onboarding	OTP-based authorization, per organization	Create the company, or a link the owner confirms	Direct pre-registration by tax ID, no OTP
Domain restriction	None	None	Required — domain whitelist

See Fatoora Connect for companies and linking, and Partner Signer for the local signing bridge.

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.