Bien démarrer

Itool propose une API RESTful permettant d'intégrer très facilement vos outils propres à nos solutions de comptabilité et de gestion commerciale.

Pour bien démarrer, nous vous recommandons de lire ces quelques conseils.

Pour aller plus loin, consultez notre documentation technique.

L'authentification

Basée sur un token propre et unique à l'utilisateur, c'est lui qui vous permet l'accès ou non aus différentes ressources de l'API.

Les droits relatifs à l'usage des API peuvent différer selon vos doits d'accès aux dossiers. Imaginons que vous ayez un dossier de Comptabilité uniquement et un autre de Comptabilité et de Gestion commerciale.

Les ressources propres à la gestion commerciale seront disponible dans le second dossier, mais pas dans le premier.

Par ailleurs, on distingue 2 niveaux d'habilitations au sein des API :

  • le droit de lecture
  • le droit de lecture + écriture

Vous pouvez donc par exemple avoir le droit de récupérer des informations de la gestion commerciale sans pouvoir rien modifier ou le droit et de récupérer et de créer / modifier / supprimer ces informations.

NB: Toutes les actions disponibles dans l'appli ne sont pas nécéssairement disponibles au travers de l'API.

Tris et Pagination

Pour les ressources GET, vous pouvez utiliser les paramètres limit et page qui vous permettent de naviguer dans le jeu de données complet de votre requête. Pour des raisons techniques, le paramètre limit est parfois bloqué à une valeur maximum si le nombre d'éléments de la réponse est trop important.

limit=X&page=X

Le paramètre orderBy vous permet d'ordonnancer les éléments de réponses selon les propriétés visibles dans la réponse.

orderBy=EcrId;desc

Pour obtenir des écritures par exemple le tri pourra être effectué sur l'un des champs suivants:

  • EcrId
  • date
  • designation
  • journal
  • numero
  • userCreation

Les ressources de comptabilité

Gestion des comptes / sous-comptes

  • Lister tous les comptes / sous-comptes du plan comptable
  • Obtenir unitairement le détail d'un compte / sous-compte
  • Créer un compte / sous-compte
  • Modifier un compte / sous-compte
  • Obtenir le solde d'un compte / sous-compte

Gestion des écritures:

  • Lister des écritures
  • Obtenir unitairement une écriture
  • Créer une écriture
  • Lister des lignes d’écritures

Gestion des lettrages:

  • Lister des lettrages
  • Obtenir le détail d’un lettrage
  • Créer un lettrage
  • Supprimer un lettrage

Les journaux:

  • Lister des journaux
  • Obtenir le détail d’un journal
  • Créer un journal
  • Modifier un journal
  • NB: Il n'est pas possible de supprimer un journal

Les ressources de gestion commerciale

Familles de produits / produits

  • Lister les familles de produits
  • Obtenir unitairement le détail d’une famille de produits
  • Créer une famille de produit
  • Modifier une famille de produit
  • Supprimer une famille de produit
  • Lister les produits
  • Obtenir unitairement le détail d’un produit
  • Créer un produit
  • Modifier un produit
  • Supprimer un produit

Familles de clients / clients :

  • Lister les familles de clients
  • Obtenir unitairement le détail d’une famille de clients
  • Créer une famille de clients
  • Modifier une famille de clients
  • Supprimer une famille de clients
  • Lister les clients
  • Obtenir unitairement le détail d’un client
  • Créer un client
  • Modifier un client
  • Supprimer un client

Les banques :

  • Lister les banques d’un client
  • Obtenir le détail d’une banque
  • Créer une banque
  • NB: Il n'est pas possible de supprimer une banque

Les documents de vente:

Pour chacun des types de documents ci-après, il est possible de lister l'ensemble des documents, d'en récupérer le détail et d'en créer de nouveaux. Il est également possible de récupérer la version PDF de chacun de ces documents. Il est également possible sous certaines conditions de modifier des documents (en cours) mais aucune suppression de document n'est possible au travers des APIs.

  • Les devis / factures / avoirs
  • Les bons de commande / bons de livraison

Concernant les factures d’acomptes, elles peuvent seulement être récupérées (pas de création / modification)

Quelques règles à bien respecter

Les champs “Formated” :

Dès lors que dans la structure de donnée récupérée par un GET (ressources de Gestion commerciale) le champ contient Formated, c'est qu'il s'agit d'un champ calculé. En cas de POST ou de PUT pour une création ou une mise à jour, ces champs doivent être retirés de la structure do données. S'il sont maintenus, l'opération ne s'effectuera pas.

Les règles de modifications :

Supposons un client avec 2 adresses de livraison distinctes:

      "AdrLivraison": [
          {
              "AdrId": 6,
              "AdrCodePostal": "78120",
              "AdrLocalite": "RAMBOUILLET",
              "AdrPays": "FRANCE",
              "AdrRaisonSociale": "ITOOL",
              "AdrAdresse": "ZA du Bel Air, Rue de Cutesson",
              "AdresseFormated": "ITOOL, ZA du Bel Air, Rue de Cutesson 78120 RAMBOUILLET"
          },
          {
              "AdrId": 7,
              "AdrCodePostal": "78125",
              "AdrLocalite": "GAZERAN",
              "AdrPays": "FRANCE",
              "AdrRaisonSociale": "ITOOL SYSTEMS",
              "AdrAdresse": "ZA du Bel Air, Rue de Cutesson",
              "AdresseFormated": "ITOOL SYSTEMS, ZA du Bel Air, Rue de Cutesson 78125 GAZERAN"
          }
      ]
  },

Si l'on souhaite modifier la 1ère adresse pour remplacer “ITOOL” par “Itool Systems” dans la raison sociale par exemple, il faut envoyer dans le PUT :

      "AdrLivraison": [
          {
              "AdrId": 6,
              "AdrRaisonSociale": "Itool Systems",
          },
          {
              "AdrId": 7,
          }
      ]
  },
  • Seule la donnée renvoyée est mise à jour.
  • le rappel de l'IdAdresse permet d'identifier l'adresse à modifier.
  • Si l'on ne renvoie pas l'IdAdresse 7, cette adresse sera supprimée.

Il en est de même pour :

  • Les adresses de facturation
  • Les contacts
  • Les adresses de contact
  • plus généralement toute collection d'objet rattachés à une ressource.




Liens