Référence, limites et téléchargements

Ce que les applications partenaires ne peuvent pas faire

Même avec tous les scopes accordés, plusieurs capacités restent réservées aux clés API propres de l'organisation :

Soumission directe à TTN — POST /api/core-proxy/invoices/:id/submit-ttn renvoie 403 PARTNER_NOT_ALLOWED pour un token partenaire. Utilisez toujours sign-and-send.
Mode de livraison des évènements et notifications pull — GET/PUT /api/core-proxy/event-delivery/mode et GET/POST /api/core-proxy/notifications* renvoient 401 PARTNER_CONTEXT_NOT_ALLOWED, réservés aux clés API propres de l'organisation. Utilisez plutôt les webhooks pour le suivi en temps réel — désormais disponibles pour une application partenaire autorisée.
Filtres de liste listCreatorScope=ORG — bloqués pour les tokens partenaires (401 LIST_ORG_SCOPE_NOT_ALLOWED).
Édition des factures depuis l'interface Fatoora — une fois soumises via l'API, les factures sont en lecture seule côté client.
Agir sans org_id autorisé — un token app-only n'accède qu'aux deux endpoints de découverte (organisations).

Vous cherchez la documentation des clés API propres à votre organisation ?

Cette section « Partner API » s'adresse aux intégrateurs techniques qui soumettent des factures au nom d'organisations clientes qui les ont autorisés. Si vous êtes vous-même une organisation cliente (plan DigiGO, SEAL Max ou Fatoora Trust) qui utilise ses propres clés API, consultez plutôt la section Organisation API.

Gestion des erreurs

Codes d'erreur les plus fréquents :

Code	HTTP	Signification / correction
`invalid_client`	401	`client_id`/`client_secret` incorrect
`access_denied`	403	Organisation non autorisée, ou app non partenaire
`INSUFFICIENT_SCOPES`	401/403	Demandez le scope manquant au client (nouveau flux d'approbation)
`ORG_NOT_FOUND`	404	Matricule ne correspondant à aucune organisation vous ayant autorisé
`PARTNER_NOT_ALLOWED`	403	Endpoint non disponible pour les tokens partenaires
`VALIDATION_ERROR` / `INVOICE_VALIDATION_ERROR`	400/422	Le TEIF échoue la validation — vérifiez `details[]`
`NO_SIGNATURE_CREDITS`	402	Quota de signature du client épuisé
`SUBSCRIPTION_INACTIVE`	402	Votre abonnement Partner API est en pause/annulé/expiré
`RATE_LIMIT_EXCEEDED` / `TOO_MANY_REQUESTS`	429	Ralentissez et réessayez

Limites de débit et quotas

Limiteur	Portée	Limite
`POST /oauth/token`	par IP	30 requêtes / 15 min
Autres appels `/api/*`	par IP	300 requêtes / 15 min

Quotas de plan (indépendants des limites de débit) :

monthlyDocLimit — total de factures soumises tous clients confondus, par mois calendaire (varie selon partner-starter/business/max).
maxOrgs — nombre d'organisations clientes autorisées simultanément.
Pendant la période d'essai, tous les plans sont plafonnés à 100 documents, quel que soit le plan.

Exemple de code

# 1. Token app-only
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. Token org-scoped, puis soumission
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

D'autres exemples (JavaScript, Python, signature et suivi de job) sont dans le guide PDF complet ci-dessous.

Partner API vs. Partner Signer

	Partner API (cette catégorie)	Partner Signer
Plans	`partner-starter/business/max`	`partner-signer`, `partner-signer-pro`
Modèle	API REST serveur-à-serveur (OAuth2)	Pont de signature locale PKCS#11/navigateur
Ce que vous soumettez	Factures TEIF complètes, au nom des clients	Rien — vous ne faites que relayer des sessions de signature locale
Onboarding client	Autorisation par OTP, par organisation	Pré-enregistrement direct par matricule, sans OTP
Restriction de domaine	Aucune	Oui — whitelist de domaines obligatoire

Voir la catégorie Partner Signer pour le détail de cette seconde offre.

Télécharger la documentation technique complète

Cette catégorie couvre l'essentiel du workflow d'intégration. Pour la spécification technique exhaustive — schémas de réponse détaillés, tous les codes d'erreur, structure TEIF complète, exemples multi-langages, spécification OpenAPI et collection Postman intégrées en pièce jointe dans le PDF — téléchargez le guide complet :

📄 Guide Partner API complet (PDF) — le PDF embarque déjà le fichier OpenAPI et la collection Postman en pièce jointe téléchargeable (icône trombone) dans un lecteur PDF compatible (Adobe Acrobat/Reader).
🔧 Spécification OpenAPI (YAML) — lien direct, si vous préférez ne pas ouvrir le PDF.
📦 Collection Postman (JSON) — lien direct, prête à importer dans Postman.
🧩 Guide dédié et téléchargement du script Bash — exemple exécutable (curl + jq) : authentification app-only puis org-scoped, découverte des organisations autorisées (sélection par --org-id, --org-tax-id ou --interactive; automatique uniquement s’il n’existe qu’un client), récupération du taxIdentifier, soumission de facture (XML ou JSON), signature SEAL, suivi du job jusqu'à acceptation TTN, puis téléchargement du XML signé et du PDF. Fonctionne aussi en mode Organisation API (--mode organization). ./fatoora-full-workflow.sh --help pour la liste des options.

Aussi disponible depuis votre tableau de bord

Une fois votre application partenaire créée, retrouvez ces mêmes fichiers depuis Tableau de bord Fatoora → Partner → Credentials → API guide.

Ce que les applications partenaires ne peuvent pas faire​

Gestion des erreurs​

Limites de débit et quotas​

Exemple de code​

Partner API vs. Partner Signer​

Télécharger la documentation technique complète​