Guide de l’interface Sandbox
La sandbox reproduit l’interface de production avec des données et identifiants de test. Ce guide montre comment un intégrateur prépare son compte Partner, demande uniquement les droits nécessaires, puis comment une organisation cliente l’autorise avant toute création de facture en son nom.
N’utilisez jamais des secrets, certificats, PIN SEAL ou données fiscales de production dans la sandbox. Les captures ci-dessous ne contiennent aucun mot de passe ni secret API exploitable.
Compte Partner
Le tableau de bord Partner donne accès au profil public, aux identifiants API, aux organisations clientes, aux factures déléguées, aux traitements et au journal d’audit.
1. Compléter la fiche Partner
Ouvrez Partner → Partner profile. Renseignez la raison sociale, la forme juridique et l’adresse. Le matricule fiscal est géré par la plateforme et n’est pas modifiable depuis cette fiche.
Dans l’onglet Catalog, ajoutez un libellé métier et des descriptions EN/FR/AR compréhensibles par les organisations. Expliquez précisément ce que fait votre intégration et pour quel usage les droits seront demandés.
2. Définir les droits demandés
Dans l’onglet API, sélectionnez le minimum requis :
| Scope | Usage |
|---|---|
invoice:read | Lire les factures et leur statut |
invoice:write | Créer ou modifier des factures |
ttn:submit | Soumettre une facture à TTN |
digigo:sign | Initier une signature DigiGO nécessitant une validation utilisateur |
seal:sign | Déclencher une signature SEAL lorsque l’organisation l’a configurée |
Les scopes deviennent les droits proposés lors de l’activation. Ils ne donnent aucun accès tant que l’organisation ne les a pas approuvés.
3. Utiliser les identifiants API
La page Partner → API credentials présente les identifiants OAuth2 du Partner. Conservez le secret côté serveur, ne l’insérez jamais dans une application web ou mobile et ne le transmettez pas à l’organisation cliente.
La page Clients liste uniquement les organisations ayant accordé une autorisation effective.
Compte Organisation
Le compte Organisation permet de gérer les factures, imports TEIF, produits, clés API, paramètres fiscaux et partenaires autorisés.
1. Vérifier l’organisation et ses moyens d’intégration
Contrôlez les informations de l’organisation avant de produire une facture, notamment le nom légal et le matricule fiscal.
Pour une intégration directe sans Partner, utilisez API Keys afin de créer une application OAuth2 appartenant à l’organisation. Le secret n’est affiché qu’au moment de la création et doit rester côté serveur.
2. Trouver et activer un Partner
Ouvrez App catalog, recherchez le nom du Partner et examinez sa description, son statut de vérification et les scopes proposés.
Cliquez sur Activate. L’écran de consentement détaille chaque droit. Annulez si un droit n’est pas justifié et demandez au Partner de réduire ses scopes par défaut.
Après confirmation, saisissez l’OTP reçu par le propriétaire de l’organisation. En sandbox, le code de test par défaut peut être fourni par l’équipe Fatoora ; en production, utilisez exclusivement le code reçu par le canal sécurisé.
Une activation réussie affiche le badge Activated dans le catalogue et l’organisation apparaît dans Partner → Clients. Si la confirmation retourne une erreur, ne contournez pas le consentement : notez l’heure, le Partner, l’organisation et contactez le support.
Après l’autorisation
Le Partner peut alors obtenir un token OAuth2 avec ses propres identifiants, sélectionner l’organisation autorisée conformément à la Partner API, récupérer son identité générale via l’endpoint de compte, puis créer, signer et soumettre des factures dans la limite des scopes accordés.
Pour tester les deux modes d’intégration de bout en bout, utilisez le workflow Bash et les collections Postman référencées dans les pages Partner API et Organisation API.
Checklist de validation
- La fiche Partner explique clairement le service proposé.
- Seuls les scopes nécessaires sont demandés.
- L’organisation a contrôlé chaque droit avant l’OTP.
- Le catalogue affiche Activated après confirmation.
- L’organisation apparaît dans la liste Clients du Partner.
- Le Partner peut lire l’identité générale de l’organisation, sans accéder à ses données d’abonnement ou autres informations sensibles.
- Une facture de test complète atteint le statut attendu dans la sandbox.