Best Practices — API v3
Retour à la documentation API
Le présent document est une synthèse des retours d'expériences auprès de plusieurs clients de Provigis ayant mis en place une connexion entre leur système de gestion des fournisseurs et Provigis en utilisant l'API Provigis.
Il décrit les objectifs à atteindre, les moyens mis à disposition par l'API de Provigis, et les questions qu'il convient de se poser pour profiter pleinement des capacités de collecte, de contrôle et de calcul des statuts de conformité dans Provigis.
Les principaux objectifs recherchés par les clients mettant en place un connecteur avec le service de Tiers de Collecte Probatoire (TCP) de Provigis sont :
L'atteinte de ces 7 objectifs exploite pleinement la combinaison SRM/TCP : garantir un suivi exhaustif des Tiers selon les règles de conformité définies, tout en réduisant les efforts opérationnels liés à la configuration et à la gestion.
En tant qu'éditeur de logiciel, nous sommes sensibles au cycle de vie applicatif :
En tant que spécialistes du suivi de conformité, nous sommes également sensibles au fait que :
Nous ajoutons donc un objectif supplémentaire :
Le connecteur doit être le moins invasif possible dans le paramétrage du SRM: le connecteur doit être compatible avec la plupart des spécificités existantes, doit permettre le mapping entre les concepts spécifiques au SRM et ceux spécifiques à Provigis, et ne doit nécessiter la gestion que d'un minimum de données spécifiques à Provigis.
Provigis est un Tiers de Collecte Probatoire (TCP). Cela signifie que les fonctions suivantes sont automatiquement prises en charge :
La mise en œuvre de toutes ces fonctions repose sur l'implémentation d'un certain nombre de concepts qui doivent être correctement compris afin d'assurer un mapping adéquat avec les équivalents SRM.
Dans Provigis, l'entité Buyer représente le Donneur d'Ordre (DO). C'est l'élément central du suivi Provigis, puisque le portefeuille de Tiers est directement rattaché à cette entité.
Lors de la configuration, l'accès API garantit l'accès aux informations d'une entité. L'identité de l'entité est requise pour la plupart des requêtes API. Les fournisseurs reçoivent les notifications au nom d'une entité Buyer.
Les entités Buyer peuvent être organisées en hiérarchie, l'entité de tête étant toujours une société identifiée par un numéro de registre du commerce. Les sous-entités peuvent représenter des filiales, des Business Units, etc. — il n'existe pas de règles prédéfinies.
Cependant, nous recommandons fortement de créer une entité spécifique dédiée exclusivement au connecteur, accessible uniquement aux administrateurs Provigis. Cela permet d'isoler le travail du connecteur des éventuels utilisateurs de l'interface Provigis qui pourraient, par exemple, retirer un Tiers du portefeuille alors qu'il était configuré pour être suivi par le connecteur.
Selon votre configuration, vous pouvez travailler avec :
Il est tout à fait possible de faire fonctionner un connecteur en parallèle sur plusieurs entités, mais cela nécessite une compréhension approfondie de Provigis et de son API, ce qui dépasse le cadre de ce document. Dans la suite de ce document, nous considérerons qu'une seule entité Buyer est utilisée.
L'identifiant de l'entité peut être :
L'objectif étant de réaliser un accès API, un certain nombre de paramètres doivent être associés à une entité « Requester » correspondant au « buyer ». Ces paramètres sont spécifiques à Provigis et ne seront probablement pas mappés sur des champs standards existants du SRM :
https://api.sandbox.provigis.com en sandbox et https://api.provigis.com en productionL'ensemble de ces éléments sera fourni par les équipes Provigis lors de l'ouverture du canal d'accès à l'API Provigis.
Deux paramètres supplémentaires doivent être stockés et régulièrement mis à jour via l'API :
| Provigis | SRM |
|---|---|
| Entité Buyer (= Requester) | Société principale à l'origine du suivi des Tiers (société cliente Provigis) |
| Identifiant privilégié : ID technique Provigis | À stocker dans le SRM pour les appels API |
| Identifiant alternatif : Code d'association | |
Paramètres d'accès :
| Statiques, fournis par l'équipe Provigis |
Paramètres de téléchargement :
| Mis à jour via appel API |
Contrairement à l'entité Buyer (requester), l'entité Supplier (depositor) représente le Tiers à surveiller. Dans Provigis, un Tiers est un établissement, et non une entité juridique. Il doit donc être identifié par un identifiant national unique :
Lorsqu'un Tiers est intégré dans Provigis, ses informations d'identité et ses statuts d'activité sont automatiquement rectifiés à partir des bases de données de référence internationales accessibles à Provigis.
Il est donc essentiel de comprendre les points suivants :
La synchronisation du portefeuille est donc unidirectionnelle, du SRM vers Provigis. Pour permettre un suivi simplifié de la synchronisation des Tiers, nous avons mis en place :
Point clé : vous n'avez pas besoin de gérer un identifiant Provigis dans le SRM — Provigis gère votre identifiant Tiers. Tous les appels et réponses API peuvent être effectués en utilisant votre référence Tiers.
| Provigis | SRM |
|---|---|
| Entité Supplier/depositor | L'établissement Tiers à surveiller. Un fournisseur ou un partenaire, par exemple. |
| Identifiant privilégié : custom_code : code Tiers SRM à fournir lors de la création du Tiers dans Provigis | Géré nativement dans votre SRM |
| Données d'identité : Id : identifiant interne Provigis Siret : SIRET de l'établissement surveillé Address : adresse Additional_Address : complément d'adresse Postal_Code : code postal City : ville IntercommunityVAT : numéro de TVA Legal_form : forme juridique Country : code pays NationalId : numéro d'identification national | Données généralement présentes dans le SRM mais à ne pas synchroniser. |
| Données de statut : Status_Activite : Statut d'activité du Tiers sur Provigis Status : statut de conformité du Tiers Status_Certification : Statut de certification concernant l'obligation de vigilance | Données à synchroniser dans le SRM. Nous recommandons d'ajouter une date de dernière synchronisation. |
Un document dans Provigis est un élément collecté auprès du Tiers lui-même ou auprès d'un fournisseur de données privé ou public. Le document possède un identifiant unique et représente l'instance du modèle de document collecté pour un Donneur d'Ordre.
Un document peut être :
Un document comporte un certain nombre d'attributs, notamment :
Le nom est suffisant car deux modèles de documents portant le même nom ne peuvent pas être activés au sein d'une même entité Buyer.
Il est assez peu nécessaire de maîtriser ces détails d'implémentation du modèle Provigis. Notez simplement que vous devrez mapper un objet SRM sur le concept de Modèle de Document Provigis.
Certains SRM gèrent une section documentaire associée à un Tiers. Dans ce cas, nous recommandons de créer un mapping entre le nom du modèle de document Provigis et un document SRM. Cela permettra au SRM de continuer à gérer les documents dans lesquels les fichiers et les statuts de conformité pilotés par Provigis seront synchronisés.
Si votre SRM ne dispose pas de ce concept, vous pouvez :
Concernant la récupération du fichier PDF lui-même, nous recommandons de fournir un lien de téléchargement à déclencher par l'utilisateur lors de la consultation, plutôt que de récupérer le PDF et de le stocker dans le SRM :
Le lien de téléchargement est sécurisé par un jeton (voir les paramètres de l'entité Buyer). La génération et le renouvellement du jeton sont possibles via l'API. Il sera donc nécessaire d'implémenter un script qui met régulièrement à jour les liens de téléchargement stockés.
| Provigis | SRM |
|---|---|
| Modèle de Document | Dépend du SRM utilisé et de sa couverture fonctionnelle. Généralement, il existe un module de gestion documentaire qui suivra la structure : Modèle de Document, Type de Document, statut du document, date d'expiration et Fichier. |
| Identifiant privilégié : ID : identifiant technique du modèle de document | Mapping à réaliser spécifiquement dans le SRM |
| Données d'identité : Nom de section : 'legal', 'reglementaires', 'contracts', 'specifics' pour le type de document DocumentModelId : identifiant du modèle de document ID : identifiant du document Date : date d'émission du document Last_updated : date de dernière mise à jour IsPoll : indique si le document est un questionnaire | Si le mapping existe dans le SRM, il n'est pas nécessaire de stocker spécifiquement ces données |
| Données de statut : Statuts : statut du document Validity : date d'expiration du document Download Link : lien de téléchargement | Données à synchroniser dans le SRM, dans des champs spécifiques, puis le cas échéant à mapper sur les concepts natifs équivalents du SRM |
| URL de téléchargement |
Le portefeuille de Tiers Provigis est la liste des Tiers à surveiller dans Provigis, et concrètement la liste des entités fournisseurs à affecter à une entité Buyer.
Chaque entité Buyer dispose de son propre portefeuille unique. Autrement dit, si vous souhaitez synchroniser un SRM avec plusieurs entités Buyer, vous devrez maintenir autant de portefeuilles qu'il y a d'entités Buyer. Le portefeuille de Tiers est donc essentiellement un sous-ensemble de la base de données Tiers gérée dans le SRM.
L'ajout ou la suppression d'un Tiers dans un portefeuille se fait via l'API, et c'est grâce à cette fonctionnalité que vous pouvez synchroniser automatiquement les portefeuilles pour garantir que tous les Tiers répondant à certains critères sont effectivement surveillés dans Provigis.
En effet, les règles d'affectation d'un Tiers à un portefeuille dépendent généralement d'informations gérées par le SRM, par exemple :
Notre recommandation pour la gestion du portefeuille de Tiers est d'implémenter 3 règles côté SRM :
| Provigis | SRM |
|---|---|
| Portefeuille de Tiers | Liste des Tiers gérés dans le SRM où :
|
| Identifiant privilégié : Requester_ID | Gestion des attributs et mises à jour à organiser dans le SRM |
| Données d'identité : Aucune donnée d'identité à gérer | Les attributs suivants sont à gérer spécifiquement dans le SRM : « Suivi Provigis » et règle associée « Ajouter au Suivi Provigis » « Exclure de Provigis » |
Les groupes de Tiers n'ont pas nécessairement d'équivalents dans le SRM. Il s'agit d'un regroupement de Tiers côté Provigis qui permet :
La configuration des documents à collecter par groupe ne se fait pas via l'API et doit être mise en place par un administrateur Provigis sur l'entité Buyer/Requester sur laquelle le connecteur opérera.
En revanche, l'affectation de Tiers à un groupe peut être pilotée par l'API, et c'est un point clé, car le connecteur pourra piloter la collecte différenciée en fonction des informations Tiers disponibles dans le SRM.
Par exemple, si vous disposez d'une catégorie d'achats « entreprises du bâtiment » dans le SRM, il peut être décidé que seuls les fournisseurs de cette catégorie seront soumis à la collecte de l'assurance décennale. Dans ce cas, l'entité Buyer côté Provigis doit être configurée comme suit :
Le connecteur peut alors automatiquement affecter un nouveau fournisseur de la catégorie d'achats « entreprises du bâtiment » dans le SRM au groupe « entreprises du bâtiment » dans Provigis, garantissant ainsi que l'assurance décennale sera demandée à tous les fournisseurs de cette catégorie d'achats.
La gestion des groupes de Tiers est similaire à la gestion du portefeuille de Tiers, mais nous déconseillons d'implémenter des attributs côté SRM. Cela nécessiterait d'ajouter un objet SRM pour chaque groupe dans Provigis. Nous recommandons plutôt d'implémenter une règle par groupe dans le SRM. Chaque règle retournera la liste des Tiers à affecter au groupe. Typiquement, cette règle prend la forme d'une requête sur la base de données du SRM qui retourne la liste des identifiants Tiers devant être affectés à un groupe.
Un groupe de Tiers est identifié dans Provigis par un identifiant unique et un nom. Le nom du groupe est unique par entité Buyer/Requester ; autrement dit, le nom du groupe peut être utilisé comme clé dans un appel API.
Des appels API existent pour :
Ainsi, il n'est pas nécessaire de stocker dans le SRM la liste des groupes pour un Tiers, mais uniquement le mapping entre un groupe et la règle de gestion qui déterminera l'affectation ou le retrait de ce groupe.
| Provigis | SRM |
|---|---|
| Groupe de Tiers | Liste des Tiers gérés dans le SRM correspondant à un ensemble de conditions |
| Identifiant privilégié : Nom du groupe | Mapping à réaliser spécifiquement dans le SRM entre le nom du groupe Provigis et la requête de sélection des Tiers à affecter. |
| Données d'identité : ID : identifiant du groupe Provigis | Le stockage spécifique n'est pas nécessaire |
La collecte d'informations auprès des Tiers se fait par invitation par email à se connecter à la plateforme. Pour chaque Tiers ajouté au portefeuille, un ou plusieurs contacts doivent être enregistrés.
Les contacts référents sont donc quelques personnes parmi les contacts déjà gérés dans votre SRM. Il est important de noter qu'un contact référent peut :
Nous avons donc mis à disposition une API pour ajouter un contact à un Tiers du portefeuille. Cette API retourne également le statut d'activité du contact :
Pour déterminer quel contact doit rejoindre la liste des référents, nous recommandons d'implémenter un attribut de contact « Contact Provigis » côté SRM. Généralement, cet attribut prend la forme d'un rôle de contact, qui est un concept géré nativement par le SRM.
L'attribution de ce rôle à un contact doit se faire manuellement, car il est difficile d'automatiser une telle décision :
À ce sujet, il est important de noter que du point de vue du RGPD, Provigis est sous-traitant lors de la phase d'invitation sur la plateforme, et responsable de traitement pour le reste des opérations.
Un processus de Synchronisation des contacts Référents mal conçu peut engager votre responsabilité.
Un contact dans Provigis est identifié par son adresse email, qui est également un concept standard dans les SRM. Vous n'avez donc pas besoin de stocker d'autre information que le statut d'activité retourné par Provigis. Les noms, prénoms, fonction et quelques autres informations dont Provigis a besoin sont demandés directement au contact lors de son inscription sur Provigis.
| Provigis | SRM |
|---|---|
| Contact Référent | Contact fournisseur avec le rôle « Contact Provigis » attribué |
| Identifiant privilégié : Adresse email | Mapping à réaliser spécifiquement dans le SRM entre l'email d'un contact et son statut d'activité |
L'ordonnancement des appels sera bien entendu étroitement lié au mode de fonctionnement du SRM sur lequel vous implémentez le connecteur Provigis, mais dans l'ensemble, vous retrouverez les séquences décrites ci-dessous à implémenter.
Pour simplifier :
| Séquence | Manuelle | Quotidienne | Hebdomadaire | Permission |
|---|---|---|---|---|
| Paramètres et mapping | x | Administrateur SRM/Provigis | ||
| Portefeuille de Tiers | x | Administrateur SRM/Provigis | ||
| Groupe de Tiers | x | Administrateur SRM/Provigis | ||
| Contact Référents | x | Administrateur SRM/Provigis | ||
| Statuts des Tiers et Documents | x | x | Admin SRM/Provigis ou Utilisateur SRM (manuel) | |
| Statut des contacts | x | Administrateur SRM/Provigis | ||
| URL de téléchargement | x | Administrateur SRM/Provigis |
Fréquence : Manuelle
Cette séquence d'appels est généralement déclenchée manuellement par l'administrateur SRM/Provigis. Elle est nécessaire lorsque :
Fréquence : Quotidienne
Cette séquence d'appels vise à vérifier chaque jour si le jeton de téléchargement approche de son expiration, et le cas échéant :
Fréquence : Quotidienne
Cette séquence d'appels vise à ajouter ou supprimer des Tiers à surveiller dans Provigis en fonction des attributs de suivi décrits dans la section Portefeuille de Tiers :
Fréquence : Quotidienne
Cette séquence d'appels vise à ajouter ou retirer des Tiers de groupes dans Provigis en fonction des règles décrites dans la section Groupe de Tiers :
Fréquence : Hebdomadaire
Cette séquence d'appels vise à ajouter des contacts aux Tiers du portefeuille synchronisé :
IMPORTANT : Demander l'ajout d'un référent à un Tiers ne signifie pas systématiquement que le contact en question acceptera l'invitation. Certains Tiers se sont organisés pour répondre aux demandes Provigis et filtrent les contacts référents acceptés. Il est donc important de suivre les soumissions de contacts pour éviter de demander indéfiniment l'ajout d'un contact que l'administrateur du Tiers refuse.
Fréquence : Quotidienne (Portefeuille) — À la demande (Tiers individuel)
Dans Provigis, il est inutile de synchroniser les statuts des Tiers trop fréquemment, car les documents ont des périodes de validité de plusieurs mois. Il peut cependant être utile de synchroniser le statut d'un Tiers spécifique à la demande (urgence sur un référencement, etc.).
Cette séquence d'appels vise à récupérer plusieurs éléments sur le Tiers :
Pour effectuer cet appel, un seul endpoint est utilisé. Selon le volume du portefeuille, il peut être nécessaire d'effectuer un cycle de plusieurs appels paginés pour couvrir tous les Tiers : la limite est de 1 000 résultats par appel au niveau de détail 1, et de 500 aux niveaux 2 ou 3. Pour un portefeuille de quelques milliers de Tiers, ce cycle reste rapide et simple à implémenter.
En règle générale, une fois les statuts récupérés, des processus SRM doivent être lancés pour traiter ces statuts. Par exemple, le statut de validité d'un document influencera le statut du document dans le SRM. Il convient donc de recalculer ce statut SRM après l'intégration des statuts Provigis.
Fréquence : Quotidienne à Hebdomadaire
Cette séquence d'appels vise à récupérer le statut d'activité des contacts référents :
L'API Provigis v3 expose toutes ses routes sous une racine unique : /api-v3/
Tous les appels décrits dans ce document utilisent cette racine.
Provigis met à disposition de ses clients un environnement Sandbox et bien entendu un environnement de production. Deux racines d'appel sont disponibles :
Les paramètres d'appel communs à toutes les routes sont :
| Paramètre | Description |
|---|---|
Authorization: Bearer {access_token} | Jeton d'accès obtenu via l'appel d'authentification, valide 24h, à transmettre dans le header de chaque requête |
oauth_consumer_key (header) | Clé de licence fixe fournie par Provigis à l'ouverture du compte, à transmettre dans le header de chaque requête |
L'ouverture de la connexion à Provigis se fait en une seule étape :
| Appel | Commentaire |
|---|---|
POST {host}/api-v3/access_token | Récupérer les jetons de connexion |
Paramètres : | |
Réponse : | Voir la documentation API |
Une route dédiée a été développée pour récupérer l'ensemble des paramètres des entités Buyer accessibles avec les identifiants d'accès fournis.
Cette route doit être appelée chaque fois que vous souhaitez renouveler l'un des éléments suivants :
Nous recommandons de générer des jetons de téléchargement valables 2 mois et d'effectuer la synchronisation des paramètres une fois par mois ou sur demande de l'administrateur Provigis. En effet, la configuration Provigis est assez stable dans le temps, il n'est donc pas nécessaire de la vérifier à chaque appel.
| Appel | Commentaire |
|---|---|
GET {host}/api-v3/collects/settings/all | Paramètres des entités Buyer accessibles |
| Paramètres : | Paramètres communs uniquement |
Réponse : | Voir la documentation API |
Les appels suivants permettent de cibler la liste des paramètres attendus :
/api-v3/collects/settings/documents : uniquement la liste des documents/api-v3/collects/settings/pools : uniquement les stratégies de collecte/api-v3/collects/settings/groups : uniquement les groupes et les documents collectés pour chaque groupeUn endpoint dédié retourne la liste de tous les modèles de documents configurés sur le compte Buyer, permettant d'identifier ceux éligibles à l'extraction de données et incluant la définition des datablocks disponibles. Il doit être appelé avant toute implémentation de récupération de métadonnées, afin d'identifier les modèles exploitables et de construire le mapping côté SRM.
| Appel | Commentaire |
|---|---|
GET {host}/api-v3/requesters/{requester_id}/documentDefinitions | Récupérer les définitions de datablocks par Requester & document_model |
| Paramètres : | Paramètres communs uniquement |
Réponse : | Voir la documentation API |
Points d'attention :
Lors de l'ajout d'un Tiers au portefeuille, les éléments suivants doivent être fournis :
| Priorité | Identifiant | Cas d'usage |
|---|---|---|
| 1 | DUNS | Tiers français ou étranger — vérification et enrichissement automatique des données d'identité |
| 2 | SIRET | Tiers français — vérification et enrichissement automatique des données d'identité sauf pour les entreprises classées non diffusibles |
| 3 | SIREN | Tiers français — l'établissement du siège social sera surveillé + vérification et enrichissement automatique des données d'identité |
| 4 | Numéro de TVA intracommunautaire | Tiers français — l'établissement du siège social sera surveillé + vérification et enrichissement automatique des données d'identité OU Tiers étranger — pas de vérification ni d'enrichissement des données |
| 5 | Identifiant national (national_id) | Tiers étranger — pas de vérification ni d'enrichissement des données |
| Appel | Commentaire |
|---|---|
POST {host}/api-v3/requesters/{requester_id}/depositors | Ajouter un Tiers au portefeuille de Tiers |
| Paramètres : | Paramètres communs uniquement |
Body : | Renseigner au minimum une clé d'identification du Tiers et en complément : Code pays ISO 3166-1 alpha-2 (depositor_country) : requis uniquement pour la création manuelle d'un Tiers étranger sans DUNS (TVA ou national_id). Pour un Tiers français, le code pays n'est pas nécessaire. Raison sociale (depositor_name) et si possible adresse + ville : uniquement pour un Tiers étranger sans DUNS, car les données fournies sont utilisées telles quelles sans vérification automatique. custom_code (depositor_custom_code) : code d'identification du Tiers dans le SRM — recommandé pour permettre l'identification du Tiers dans les appels suivants. Il est recommandé d'ajouter un maximum de 100 par appel pour éviter d'éventuels problèmes de timeout. |
Réponse : | La réponse précise si le Tiers a été ajouté avec succès, et fournit les détails du Tiers ajouté. Ce dernier point est important, car il vous permet de récupérer le SIRET exact du Tiers ajouté, si dans le body de votre requête votre appel n'était pas aussi spécifique (par ex., fournir un SIREN et recevoir un SIRET). |
Les codes d'erreur retournés dans le champ errorCode permettent d'identifier précisément la cause d'un échec d'ajout et de déterminer l'action corrective à entreprendre côté SRM, par exemple corriger un SIRET invalide ou inactif, compléter des champs manquants ou alerter un responsable. Leur interprétation est essentielle pour une Synchronisation du portefeuille de Tiers automatique fiable.
| Code | Message | Signification | Action corrective |
|---|---|---|---|
| 51 | Supplier SIRET not registered | Le SIRET soumis n'existe pas dans les bases de données officielles | Vérifier et corriger le SIRET dans le SRM |
| 52 | Inactive supplier | L'établissement correspondant au SIRET est fermé | Identifier si un établissement de substitution existe (transfert de SIRET, siège social) ou retirer le Tiers du périmètre de surveillance |
| 4003 | Some parameters are missing | Des paramètres obligatoires sont manquants dans le body — typiquement le code pays ou la raison sociale pour un Tiers étranger sans DUNS | Compléter les champs manquants dans le SRM avant de soumettre à nouveau |
Lors de la suppression d'un Tiers du portefeuille, les éléments suivants doivent être précisés :
Il s'agit d'une dissociation : le Tiers n'est pas supprimé de la base de données Provigis, il est simplement retiré du portefeuille. Plusieurs Tiers peuvent être traités en un seul appel via un tableau dans le body.
| Appel | Commentaire |
|---|---|
DELETE {host}/api-v3/requesters/{requester_id}/depositors | Supprimer un ou plusieurs Tiers du portefeuille client |
Body : | Paramètres communs et supplierIDMethod : Peut utiliser les méthodes d'identification Tiers suivantes : custom_code, siret, duns, vat_number, national_id et id (= id technique Provigis) |
Réponse : | Les clés d'identification utilisées dans le body sont retournées pour faciliter le rapprochement et l'interprétation des résultats |
Le jeton de téléchargement sécurise le lien de téléchargement qui appelle une route publique. Cette méthode évite un appel au processus de connexion API avant d'exécuter la route de téléchargement elle-même.
L'appel à cette route nécessite les éléments suivants :
| Appel | Commentaire |
|---|---|
GET /api-v3/public/download/generate_download_token | Générer un jeton de téléchargement |
| Paramètres : Validity_date : YYYY_MM_DD Requester_id | Date de validité maximale et ID du buyer concerné |
Réponse : | La réponse précise si le jeton de téléchargement a été créé, et retourne le jeton et sa date de validité |
Lors de l'ajout d'un Tiers à un groupe, les éléments suivants doivent être précisés :
Plusieurs groupes et plusieurs Tiers peuvent être traités en un seul appel. Le groupe peut être ciblé par son identifiant technique (group_id) ou par son nom (group_name).
| Appel | Commentaire |
|---|---|
POST {host}/api-v3/requesters/{requester_id}/groups/depositors | Ajouter une liste de Tiers à un ou plusieurs groupes existants sur le compte buyer |
| Paramètres : Requester_id | |
Body : | Identification du groupe via group_name ou group_id supplierIDMethod : Peut utiliser les méthodes d'identification Tiers suivantes : custom_code, siret, duns, vat_number, national_id et id (= id technique Provigis) |
Réponse : | exist: Indique si le groupe ciblé existe dans Provigis (true/false) suppliersAddedWithSuccess: Tiers affectés au groupe avec succès suppliersAlreadyExistsInGroup: Tiers déjà présents dans le groupe — aucune action effectuée suppliersOffline: Tiers reconnus mais dont l'établissement est fermé suppliersUnknown: Tiers inconnus de Provigis |
Note importante : si le groupe est ciblé par group_name et qu'il n'existe pas, le champ exist retourne false et aucun Tiers n'est affecté. Il est recommandé de vérifier la validité du group_id et du group_name au préalable via GET /api-v3/collects/settings/groups
Lors de la suppression d'un Tiers d'un groupe, les éléments suivants doivent être précisés :
Plusieurs groupes et plusieurs Tiers peuvent être traités en un seul appel. Le groupe peut être ciblé par son identifiant technique (group_id) ou par son nom (group_name).
| Appel | Commentaire |
|---|---|
DELETE {host}/api-v3/requesters/{requester_id}/groups/depositors | Supprimer une liste de Tiers d'un ou plusieurs groupes |
| Paramètres : requester_id | |
Body : | Les méthodes d'identification acceptées (depositor_id_method) sont : id, siret, custom_code, duns, vat_number, national_id. Elles peuvent être combinées au sein d'un même appel. |
Réponse : | exist: Indique si le groupe ciblé existe dans Provigis (true/false) suppliersDeletedWithSuccess: Tiers retirés du groupe avec succès suppliersNotInGroup: Tiers reconnus mais absents du groupe ciblé — aucune action effectuée suppliersUnknown: Tiers inconnus de Provigis |
Note importante : Contrairement à la suppression du portefeuille, le champ group dans la réponse utilise l'identifiant ou le nom selon ce qui a été soumis dans le body. Notez également que retirer un Tiers d'un groupe ne le retire pas du portefeuille.
Pour obtenir la liste des Tiers appartenant à un groupe :
| Appel | Commentaire |
|---|---|
GET {host}/api-v3/requesters/{requester_id}/groups | Récupérer la liste des groupes et leurs Tiers affectés |
| Paramètres : | Paramètres communs |
| Body | Pas de body |
Réponse : | group_id: Identifiant technique du groupe dans Provigis group_name: Nom du groupe supplier_id: Identifiant interne Provigis du Tiers (= depositor_id) supplier_name: Raison sociale du Tiers supplier_custom_code: Code Tiers SRM — null si aucun custom_code n'a été associé au Tiers |
Lors de l'ajout d'un ou plusieurs contact(s) référent(s), les éléments suivants doivent être précisés :
| Appel | Commentaire |
|---|---|
POST {{host}}/api-v3/requesters/{{requester_id}}/depositors/referrers | Ajouter un ensemble de contacts à un ou plusieurs Tiers |
Body : | Valeurs obligatoires : depositor_id depositor_id_method referrer_email referrer_civility : saisir 0, 1 ou 2 |
Réponse : | supplierExist: Le Tiers est connu de Provigis supplierBlockedAddContact: Le Tiers a bloqué l'ajout de nouveaux contacts — aucun contact ne sera créé supplierAttachedToBuyer (true/false) : Le Tiers est rattaché au portefeuille du Requester referentsAddedWithSuccess: Contact créé avec succès referentsAlreadyAttached: Contact déjà associé au Tiers — aucune action effectuée referentsWithMissingParams: Contact rejeté en raison de paramètres manquants — typiquement l'email ou la civilité |
Points d'attention :
Cet endpoint retourne les statuts de tous les Tiers du portefeuille. Le paramètre level contrôle le niveau de détail retourné. La section suivante (11.11) couvre les niveaux 2 et 3 qui ajoutent le détail des documents.
| Appel | Commentaire |
|---|---|
GET {{host}}/api-v3/requesters/{{requester_id}}/depositors/status?level=1&start_index=&max_per_page=&update_date= | Récupérer les statuts des Tiers du portefeuille |
| Parameters: | Level : Niveau de détail — 1 (statuts globaux), 2 (+ détail des documents), 3 (+ détail étendu) — Défaut : 1 start_index : Index du premier résultat — défaut : 0 max_per_page : Nombre de résultats par page — max 1000 au niveau 1, max 500 aux niveaux 2 et 3 — Défaut : 50 update_date : Filtre delta — retourne uniquement les Tiers ayant eu un événement depuis cette date (format YYYY-MM-DD). |
Réponse : | status: true si l'appel a réussi totalElements: nombre total de Tiers dans le portefeuille (ou dans le delta si update_date est utilisé) startIndex / elementsPerPage: paramètres de pagination id: depositor_id Provigis status_activite: statut d'activité calculé (Active, No Contact, No Active Contact, Sleeping, Offline...) status_certification: statut de l'obligation de vigilance — Certified ou Uncertified status: statut de conformité global (verified, invalid, offline, to_verify) invalid_since: date à partir de laquelle le Tiers est en statut invalid notdiligent: true si le Tiers est resté non conforme sans action positive pendant 90 jours duns: affiché uniquement s'il a été injecté par le client à la création |
Le niveau 2 ajoute au niveau 1 le détail des documents par Tiers. Le niveau 3 ajoute au niveau 2 des détails supplémentaires sur chaque instance de document (id, dates...). Les paramètres d'appel et de pagination sont identiques au niveau 1.
| Appel | Commentaire |
|---|---|
GET {{host}}/api-v3/requesters/{{requester_id}}/depositors/status?level=3&start_index=&max_per_page=&update_date= | Récupérer les statuts et le détail des documents des Tiers du portefeuille |
| Paramètres : | Level : Niveau de détail — 1 (statuts globaux), 2 (+ détail des documents), 3 (+ détail étendu) — Défaut : 1 start_index : Index du premier résultat — défaut : 0 max_per_page : Nombre de résultats par page — max 1000 au niveau 1, max 500 aux niveaux 2 et 3 — Défaut : 50 update_date : Filtre delta — retourne uniquement les Tiers ayant eu un événement depuis cette date (format YYYY-MM-DD). |
Réponse niveau 2 (champs supplémentaires par rapport au niveau 1) :
{
"status": true,
"totalElements": 170,
"startIndex": 0,
"elementsPerPage": 50,
"level": 2,
"suppliers": [
{
"id": 180226866839109057,
"status_activite": "Active",
"status_certification": "Uncertified",
"date_added": "2026-02-18",
"name": "(GROUPE) ASTEK",
"siret": "48980080500041",
"status": "invalid",
"custom_code": "12345679",
"country": "FR",
"pool": { "id": "10746", "name": "Legal" },
"groups": [{ "id": 49811, "name": "GROUP" }],
"dateInsertionBase": "2016-06-11",
"notdiligent": "false",
"documents": {
"legal": [
{
"name": "Kbis",
"status": "to_update",
"validity": "2025-02-25",
"validation": { "status": "invalid", "message": "Ce document est incomplet." },
"documentModelId": 2
},
{
"name": "LNTE",
"status": "missing",
"documentModelId": 8
}
],
"reglementaires": [
{
"codeNaf": "",
"name": "Others",
"docs": [
{
"name": "Assurance RCP",
"entitledEn": "Professional Liability Insurance",
"status": "to_verify",
"validity": "2027-05-01",
"is_concerned": true,
"documentModelId": 15
},
{
"name": "Questionnaire RSE Standard",
"entitledEn": "Standard CSR Questionnaire",
"status": "to_update",
"validity": "2024-03-02",
"is_concerned": true,
"documentModelId": 3850,
"isPoll": true,
"pollId": 3850
}
]
}
],
"contracts": [],
"specifics": [
{
"name": "Relevé d'identité bancaire certifié",
"mandatory": true,
"status": "missing",
"documentModelId": 5909,
"not_concerned": false
},
{
"name": "questionnairebuyer",
"mandatory": true,
"status": "up_to_date",
"validity": "2125-12-02",
"documentModelId": 6442,
"not_concerned": false,
"isPoll": true,
"pollId": "6442"
}
]
}
}
]
}Champs supplémentaires par rapport au niveau 1 :
Réponse niveau 3 (champs supplémentaires par rapport au niveau 2) :
// Même structure que le niveau 2, avec des champs supplémentaires par document :
{
"name": "Kbis",
"status": "to_update",
"validity": "2025-02-25",
"documentModelId": 2,
"id": 6047219,
"date": "2024-11-25",
"lastUpdated": "2025-04-01",
"importDate": "2024-11-25",
"downloadLink": "api.provigis.com/download/6047219"
}Champs supplémentaires par rapport au niveau 2 :
| Statut | Signification |
|---|---|
missing | Aucun document soumis |
to_update | Document soumis mais expiré ou invalide |
to_verify | Document soumis, en attente de vérification |
up_to_date | Document valide et à jour |
Points d'attention :
L'appel à cet endpoint récupère le statut d'activité de chaque contact référent. Il nécessite l'envoi de :
| Appel | Commentaire |
|---|---|
GET /api-v3/requesters/{requester_id}/depositors/referrers?offset=&max= | Récupérer la liste des contacts référents et leur statut d'activité pour l'ensemble du portefeuille (paginé) |
| Paramètres : | offset : index du premier résultat — défaut : 0 max : nombre de fournisseurs retournés par page — recommandé : 5 000 maximum |
Réponse : | totalCount: nombre total de fournisseurs dans le portefeuille (pas de contacts) offset: index de début de la page retournée supplier.id: depositor_id Provigis supplier.supplier_external_code: custom_code du Tiers referrers: liste des contacts référents du Tiers — tableau vide si aucun contact n'a été enregistré activity_status: statut d'activité du contact : Active : le contact a validé les Conditions Générales d'Utilisation et accède à Provigis Not_active : le contact a été invité mais n'a pas encore activé son accès Not_Authorized : contact présent mais ne souhaitant pas être contacté civility: 0 = M., 1 = Mme, 2 = Mlle |
Points d'attention :
La pagination est basée sur le nombre de fournisseurs retournés, et non sur le nombre de contacts. Un fournisseur peut avoir plusieurs référents — le volume total de contacts peut donc être significativement supérieur au paramètre max.
Un fournisseur avec referrers: [] correspond à un Tiers sans contact référent, mais cela ne signifie pas nécessairement qu'aucun contact n'est enregistré sur le fournisseur (voir le statut d'activité).
Deux endpoints sont nécessaires pour retourner directement le fichier PDF d'un document demandé. Pour initier l'appel qui récupère le PDF, vous devez disposer d'un jeton de téléchargement valide.
| Appel | Commentaire |
|---|---|
GET {{host}}/api-v3/public/download/generate_download_token?validity_date=YYYY-MM-DD&requester_id={requester_id} | Générer un jeton de téléchargement sécurisé |
Réponse : | Le jeton est valide jusqu'à la date de validité demandée (2 mois maximum). Il est réutilisable pour tous les téléchargements de la session. Ne pas régénérer un jeton à chaque appel. Stocker la valeur et sa date d'expiration côté SRM et renouveler le jeton et les liens de téléchargement à l'expiration. |
Cet endpoint retourne directement le fichier PDF du document demandé. Il nécessite un jeton de téléchargement valide (voir ci-dessus).
| Appel | Commentaire |
|---|---|
GET {{host}}/api-v3/public/download?download_token={token}&depositor_id={depositor_id}&depositor_id_method=id&document_model_id={document_model_id} | Télécharger le PDF d'un document fournisseur |
| Paramètres : download_token depositor_id depositor_id_method document_model_id document_model_name | download_token : jeton généré (obligatoire) depositor_id : identifiant du Tiers depositor_id_method : méthode d'identification du Tiers (id, siret, custom_code, duns, vat_number, national_id) document_model_id : identifiant du modèle de document — récupéré dans la réponse de statut (niveau 2 ou 3) OU document_model_name : alternative à document_model_id, également retourné dans la réponse de statut (niveau 2 ou 3) — utiliser l'un ou l'autre, jamais les deux |
| Réponse : PDF FILE | Le fichier PDF est restitué |
Points d'attention :
L'usage recommandé est de construire l'URL de téléchargement et la rendre accessible dans le SRM ou l'ERP — les utilisateurs téléchargent le document à la demande, uniquement lorsque nécessaire. Provigis conserve le rôle de stockage et d'archivage. Il n'est pas recommandé de récupérer systématiquement tous les PDF en boucle.
Vérifier le statut du document (niveau 2 ou 3) avant de tenter un téléchargement : un statut missing garantit une réponse 412. Seuls les documents avec un statut to_update, to_verify ou up_to_date disposent d'un fichier récupérable.
Le document_model_id ou document_model_name est récupéré dans la réponse de statut (niveau 2 ou 3) ou via l'endpoint GET{host}/api-v3/collects/settings/all.
Cet endpoint récupère le contenu structuré des documents collectés — données extraites automatiquement par Provigis ou issues de connecteurs avec des fournisseurs de données. Il ne retourne pas le fichier PDF mais les valeurs structurées associées à chaque document.
Avant d'utiliser cet endpoint, appeler GET /api-v3/requesters/{requester_id}/documentDefinitions pour identifier quels modèles de documents sont éligibles à l'extraction et quels datablocks sont disponibles pour chacun. Les modèles sans datablocks (documentDefinitions: []) ne retourneront aucun contenu exploitable via cet endpoint.
| Appel | Commentaire |
|---|---|
GET /api-v3/requesters/{requester_id}/documentDefinitions | Récupérer la liste des modèles de documents et leurs datablocks disponibles |
Réponse : | Id: document_model_id — utilisable comme filtre dans l'endpoint de récupération des métadonnées entitled: Libellé du document (disponible en FR, EN, ES, IT, DE) documentDefinitions: Tableau vide = pas d'extraction de données disponible pour ce modèle. Tableau non vide = datablocks exploitables via l'endpoint documents-metadata documentDefinitions.name: Référence du template kernel associé documentDefinitions.dataBlockDefinitions.name: Nom technique de chaque datablock extractible — utilisable comme filtre datablock_names dans l'endpoint de récupération de la valeur |
| Appel | Commentaire |
|---|---|
GET /api-v3/requesters/{requester_id}/documents-metadata?offset=0&limit=100&document_model_id={id}&datablock_names=&creation_date= | Récupérer les métadonnées pour l'ensemble du portefeuille — une variante existe pour filtrer sur un seul depositor uniquement |
| Paramètres | offset : index du premier résultat — défaut : 0 limit : nombre de résultats par page — défaut : 50, max : 100 document_model_id : filtrer par modèle de document — recommandé datablock_names : filtrer par un ou plusieurs datablocks spécifiques creation_date : filtrer par date de création |
Réponse : | identification.depositorId: depositor_id Provigis du Tiers identification.documentTemplate: référence interne du template kernel creationDate: date de génération du contenu obsolescence: date d'obsolescence — null si toujours valide content.{datablock}.dataValue: valeur du datablock — chaîne, objet complexe ou null content.{datablock}.obsolescence: date d'obsolescence spécifique à ce datablock content["/"].dataValue: datablock synthétique aplati — valeurs lisibles en paires clé/valeur, le plus pratique pour le mapping SRM fileId.dataValue: identifiant du fichier PDF associé — null si pas de fichier (courant pour les documents issus de connecteurs) totalElements / page / size / totalPages: pagination |
Points d'attention :