---
title: "Utilisation"
weight: 30
description: "Guide d'utilisation du module OBAPI : mode client, mode serveur, onglet tiers, import et synchronisation."
---

# Utilisation

OBAPI s'utilise principalement via l'onglet **Obapi** ajouté sur la fiche de chaque tiers. Cet onglet regroupe les fonctions client (si le tiers est un fournisseur) et serveur (si le tiers est un client).

## Accéder au module

Le module est accessible de deux manières :

- **Menu principal** : **Outils > OBAPI** donne accès à la page d'accueil du module avec les liens vers la synchronisation initiale et l'actualisation des données.
- **Fiche tiers** : l'onglet **Obapi** apparaît sur chaque fiche tiers (fournisseur ou client selon la configuration).

## Mode client : se connecter à un fournisseur

### Connexion initiale

Si votre fournisseur dispose d'un serveur OBAPI, vous pouvez configurer la connexion depuis l'onglet **Obapi** de sa fiche tiers.

1. Ouvrez la fiche du tiers fournisseur
2. Cliquez sur l'onglet **Obapi**
3. Renseignez les trois informations fournies par votre fournisseur :

| Champ | Description |
|-------|-------------|
| **Adresse du service obAPI** | URL du point d'entrée OBAPI de votre fournisseur (par exemple `https://obapi.fournisseur.fr`) |
| **Identifiant utilisateur** | Votre identifiant sur le service OBAPI du fournisseur (généralement votre adresse email) |
| **Clé d'API temporaire** | Clé temporaire à usage unique fournie par votre fournisseur pour la connexion initiale |

4. Cliquez sur **Envoyer**

![Formulaire de connexion initiale à un serveur OBAPI distant](screenshots/connexion-initiale-client.webp)

La connexion initiale échange la clé temporaire contre un jeton JWT permanent qui est stocké automatiquement sur la fiche du tiers. Les connexions suivantes sont transparentes.

### Consulter les données du fournisseur

Une fois la connexion établie, l'onglet **Obapi** affiche les données mises à disposition par votre fournisseur. Selon les droits accordés, vous pouvez consulter et importer :

- **Factures** : liste des factures avec référence, date, montant HT, montant TTC, référence client et statut
- **Commandes** : liste des commandes avec les mêmes informations
- **Tiers** : liste des tiers partagés (si le fournisseur expose les tiers par catégorie)

> **À propos des autres objets** : le protocole OBAPI couvre également les devis, avoirs, contacts, produits, expéditions et dictionnaires. Ces objets sont exposés par le mode serveur (voir plus bas) et peuvent être consommés par un client compatible, mais l'onglet **Obapi** du module Dolibarr n'affiche pour l'instant que les factures, commandes et tiers. Les autres objets restent disponibles pour une intégration par script ou par un client tiers.

Chaque ligne propose un bouton **Importer** pour créer l'objet correspondant dans votre Dolibarr.

![Liste des factures disponibles sur le serveur OBAPI du fournisseur avec les boutons d'import](screenshots/liste-factures-fournisseur.webp)

### Importer des documents

Cliquez sur **Importer** en regard de la ligne souhaitée. Le module crée l'objet correspondant dans votre Dolibarr :

- **Facture** : crée une facture fournisseur en mode brouillon. Vérifiez les données avant de la valider.
- **Commande** : crée une commande fournisseur.
- **Tiers** : crée ou met à jour la fiche tiers et ses contacts.

Pour les tiers, le bouton **Tout importer** permet d'importer l'ensemble des tiers disponibles en une seule opération.

> **Vérification** : les factures et commandes importées sont créées en mode brouillon. Contrôlez toujours que toutes les données (lignes, montants, références produits) sont correctes avant de valider le document.

### Synchroniser les paiements

Sur l'onglet **Obapi** d'un fournisseur connecté, vous pouvez synchroniser les paiements de vos factures fournisseur avec les données du serveur distant.

1. Cochez les factures pour lesquelles vous souhaitez récupérer les paiements
2. Cliquez sur **Synchroniser les paiements**

Le module compare le montant payé localement avec le montant payé sur le serveur distant et crée les paiements manquants.

> **Compte bancaire** : un compte bancaire par défaut doit être configuré pour le tiers. Si ce n'est pas le cas, le module affiche un message d'erreur.

### Compatibilité des versions

Lors de la connexion, le module vérifie la version du serveur OBAPI distant. Si le serveur utilise une version 1.x (incompatible avec le client 2.0), un message d'avertissement est affiché et les données ne sont pas récupérées.

## Mode serveur : exposer vos données à un client

### Prérequis

- Le mode serveur doit être [activé dans la configuration](/obapi/configuration)
- Le tiers doit être de type **client**
- Le tiers doit avoir une adresse email renseignée sur sa fiche

### Fournir les informations de connexion

Sur la fiche d'un tiers client, l'onglet **Obapi** affiche les informations de connexion à transmettre à votre client :

| Information | Description |
|-------------|-------------|
| **Adresse du service** | URL publique de votre service OBAPI |
| **Identifiant à utiliser** | Adresse email du tiers |
| **Clé d'authentification temporaire** | Clé temporaire générée automatiquement, valide pendant la durée configurée |

![Informations de connexion serveur à transmettre au client](screenshots/informations-connexion-serveur.webp)

Transmettez ces trois informations à votre client. Il les utilisera dans son propre Dolibarr pour configurer la connexion initiale.

> **Adresse email obligatoire** : si le tiers n'a pas d'adresse email renseignée, le module affiche un message d'erreur et ne génère pas de clé temporaire. Ajoutez d'abord une adresse email sur la fiche du tiers.

### Gérer les droits d'accès

Une fois que votre client a utilisé la clé temporaire pour se connecter, l'onglet **Obapi** affiche un tableau de gestion des droits.

![Tableau de gestion des droits d'accès OBAPI pour un client connecté](screenshots/gestion-droits-client.webp)

Pour chaque type d'objet activé dans la [configuration](/obapi/configuration), vous pouvez accorder ou retirer deux niveaux de droits :

| Droit | Description |
|-------|-------------|
| **Lecture** | Le client peut consulter et télécharger les objets de ce type |
| **Créer** | Le client peut créer des objets de ce type (par exemple envoyer une commande) |

Cochez ou décochez les cases puis cliquez sur **Appliquer les droits**.

Pour révoquer complètement l'accès d'un client, cliquez sur **Supprimer l'accès OBAPI**.

### Consulter le journal des accès

Un lien en bas de l'onglet permet de consulter le journal des accès OBAPI filtré pour ce client. Ce journal enregistre chaque requête API reçue : date, adresse IP, méthode HTTP, URL demandée, code de réponse, taille de la réponse et user-agent.

## Envoyer une commande à un fournisseur

Si votre fournisseur dispose d'un service OBAPI et que vous avez configuré la connexion sur sa fiche tiers, un bouton **OBAPI: Envoyer la commande** apparaît sur la fiche des commandes fournisseur dont le statut est **Validée** ou **Commande envoyée**.

![Bouton d'envoi de commande OBAPI sur la fiche commande fournisseur](screenshots/envoi-commande-fournisseur.webp)

En cliquant sur ce bouton :

1. La commande est transmise au serveur OBAPI du fournisseur
2. La référence fournisseur distante est enregistrée dans les notes privées de la commande
3. Le statut de la commande passe à **Commande envoyée**
4. Un événement est créé dans l'agenda Dolibarr pour tracer l'opération

## Synchronisation en masse

La page **Outils > OBAPI** propose deux fonctions de synchronisation :

| Fonction | Description |
|----------|-------------|
| **Synchronisation initiale** | Importe l'ensemble des tiers depuis un serveur OBAPI distant. Une barre de progression indique l'avancement de l'opération. |
| **Actualisation des données** | Met à jour les tiers déjà importés en parcourant les références externes enregistrées. |

Ces fonctions utilisent des appels AJAX séquentiels pour traiter chaque tiers individuellement, ce qui évite les dépassements de délai sur les volumes importants.