Isi-APP Docs fonctionnelles
Toutes les docs
Markdown brut
API N2F (notes de frais)
Actif integrations functional Revu le 2026-09-30 integrations/n2f-expense-api.md

API N2F (notes de frais)

Doc fonctionnelle : décrit le quoi et le pourquoi (point de vue utilisateur / chef de projet).

À quoi ça sert

N2F (éditeur n2jSoft) est le logiciel de notes de frais du groupe. Aujourd'hui, un client est saisi deux fois : dans le CRM Isi-APP, puis à la main dans N2F pour qu'un collaborateur puisse imputer une dépense refacturable.

L'objectif du backlog 1844 est de supprimer cette double saisie : le CRM devient la source unique, et N2F se met à jour tout seul chaque nuit.

Un écran d'administration — /admin/n2f — permet dès aujourd'hui de tester l'API avec un couple d'identifiants et de lire la documentation de la plateforme sans quitter Isi-APP. C'est la première étape : observer les réponses réelles avant d'écrire la synchronisation.

Les trois temps du besoin

Échéance Ce qui se passe État
1<sup>er</sup> octobre 2026 Les clients du CRM partent vers N2F et s'y maintiennent seuls Bac à sable livré, synchronisation à écrire
Ensuite Les frais reviennent dans Isi-APP Chantier distinct : Isi-APP n'a ni écran, ni fiche, ni circuit de validation pour les frais
À terme Les frais refacturables arrivent sur la facture À cadrer pour lui-même (TVA, refacturation au réel ou avec marge)

Ce que l'API donne

Domaine Contenu
Axes analytiques Clients, projets, centres de coûts, invités internes, véhicules
Collaborateurs Création, profils, changement de société, appareils mobiles
Dépenses & notes de frais Lecture, justificatifs, étapes de validation
Référentiels Devises, pays, taux de change, jours fériés
Achats Demandes d'achat, réceptions, factures fournisseurs

Dans N2F, un client n'est pas une entité à part : c'est une valeur de l'axe analytique clients, rattachée à une société. C'est ce qui explique la forme des appels.

L'écran /admin/n2f

Réservé aux développeurs (la page manipule des identifiants d'API globaux, non cloisonnés par entité, et peut écrire dans le référentiel N2F). Deux onglets :

  • Bac à sable — saisir le Client ID / Client Secret, choisir la plateforme (préproduction ou production), obtenir un jeton et rejouer 15 appels du catalogue. Chaque réponse affiche le statut, la durée, le code d'erreur N2F, le corps JSON et l'équivalent curl.
  • Documentation — rôle de l'API, authentification, quotas, fonctionnement de l'axe clients, codes d'erreur, environnements, questions ouvertes et trajectoire d'intégration.

Le secret n'est jamais enregistré en base : il reste chiffré dans la session serveur et disparaît à la déconnexion, ou via le bouton « Oublier ».

Règles imposées par N2F

Ce ne sont pas des recommandations : leur non-respect déclenche un blocage automatique de l'accès API pendant 12 heures.

Créneau (heure de Paris) Lectures Écritures
6 h → 20 h 60 / minute 20 / minute
20 h → 6 h 200 / minute 50 / minute
  • une synchronisation par lot au maximum une fois par jour, et jamais entre 6 h et 21 h — cette borne de 21 h, propre aux traitements de masse, est une heure plus tardive que celle du créneau de quota ci-dessus ; c'est elle qui fixe l'heure de la synchronisation de nuit ;
  • les appels doivent être séquentiels ;
  • l'authentification compte dans le quota : le jeton (valable ~1 h) doit être réutilisé ;
  • abonnement Advanced et activation de l'accès API par n2jSoft requis.

C'est ce qui fixe la promesse à annoncer aux utilisateurs : une modification dans le CRM est répercutée la nuit suivante, pas dans la seconde. Avec environ cinq nouveaux clients par mois, l'écart est invisible à l'usage.

Deux points de vigilance

Retirer un client sans casser l'historique. Un client devenu inactif ne se supprime pas : on lui pose une date de fin de validité. Il disparaît des choix de saisie, mais les notes de frais qui le mentionnent restent intactes.

Ne pas créer d'utilisateurs pour tester. Créer un utilisateur dans N2F envoie immédiatement un mail d'activation à l'intéressé, y compris depuis la préproduction. L'écran de test ne propose donc aucune écriture sur les utilisateurs.

Ce qui reste à trancher

Ces points bloquent l'écriture de la synchronisation, pas le bac à sable.

  1. Périmètre des clients. La règle « statut Client et affaire gagnée » remonte 99 fiches ; 41 fiches au statut Client n'ont pas d'affaire gagnée, et 54 fiches ont une affaire gagnée sans être au statut Client. Corriger le CRM, ou exclure ?
  2. Quels statuts d'affaire comptent comme « gagné ».
  3. Les trois sociétés du groupe : une seule société N2F, ou une répartition ? Le compte de préproduction n'en expose qu'une (ISI DSI), celui de production deux (ISI DSI et ISI APP).
  4. L'adresse est-elle exigée par N2F ? À peine une fiche client sur deux en porte une.
  5. Les collaborateurs : créés depuis Isi-APP ou saisis dans N2F ?
  6. Nos missions : poussées dès la première phase sur l'axe projects ?
  7. Le choix du client sera-t-il obligatoire sur une ligne refacturable (paramétrage N2F) ?

Accès

Qui Ce qu'il voit
Développeur ISI L'écran complet : bac à sable et documentation
Administrateur ISI non développeur Refusé (403)
Utilisateur standard Refusé par le middleware isi-admin
Session d'assistance Refusée, même si l'assistant connecté est développeur

Voir aussi