Authentification et scopes

Partner API utilise le grant OAuth2 Client Credentials (RFC 6749 §4.4). Pas de connexion utilisateur, pas de cookies ni de session : chaque appel est authentifié avec votre paire clientId / client secret.

Obtenir un token

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type    = client_credentials
client_id     = <votre clientId>
client_secret = <votre client secret>
org_id        = <UUID de l'organisation cliente>   (optionnel)

Il existe deux types de token, valables 1 heure, sans refresh token (il suffit de rappeler /oauth/token) :

Type de token	org_id envoyé ?	Usage
App-only	Non	Découverte des organisations autorisées uniquement
Org-scoped	Oui	Tous les appels facture/signature, au nom de cette organisation

Réponse :

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "invoice:write invoice:read ttn:submit"
}

Envoyez ensuite le token sur chaque appel :

Authorization: Bearer <access_token>

Erreurs fréquentes

• 401 invalid_client — client_id/client_secret incorrect.
• 403 access_denied — org_id fourni mais non autorisé pour votre app (révoqué, jamais accordé, ou inactif).
• 429 TOO_MANY_REQUESTS — limite de débit dépassée (voir la page Référence).

Scopes

Scope	Autorise
invoice:write	Créer, mettre à jour, soumettre, dupliquer, supprimer des factures brouillon ; déclencher la signature
invoice:read	Lister et récupérer factures, statuts, PDF, XML généré, jobs, activité
ttn:submit	(Re)soumettre manuellement à TTN — réservé aux clés propres de l'organisation, pas aux tokens partenaires
seal:sign	Déclencher une signature SEAL lors du sign-and-send
digigo:sign	Déclencher une signature DigiGO lors du sign-and-send

Un client n'accorde que les scopes qu'il souhaite — vérifiez allowedScopes avant d'appeler un endpoint qui nécessite un scope non accordé, sous peine de 403 INSUFFICIENT_SCOPES.

Découvrir les organisations clientes

Utilisez votre token app-only pour ces deux appels :

GET /api/partner/authorized-orgs

Liste toutes les organisations qui autorisent actuellement votre application (orgId, orgName, taxIdentifier, allowedScopes, authorizedAt).

GET /api/partner/resolve-org?taxId=<matricule>

Résout un matricule fiscal tunisien (format 8 ou 13 caractères) vers l'orgId correspondant, limité aux organisations qui vous autorisent. Renvoie 404 ORG_NOT_FOUND si aucune correspondance.

Une fois l'orgId obtenu, demandez un token org-scoped (org_id=<orgId>) et passez à la page Factures.