Les sources de données Paperbox vous permettent de charger des données de référence structurées (généralement au format CSV) que Paperbox peut utiliser dans ses workflows (par exemple pour la mise en correspondance, l'enrichissement, le routage ou les validations).
Tous les endpoints datasource font partie de l'Integration API, disponible sur https://integration.{ENV}.paperbox.ai (où {ENV} = acc ou prd). L'authentification se fait au moyen d'un JWT signé et d'une clé API fournie par Paperbox.
Les 3 routes datasource (fonctions)
1) Charger une version complète des données (tout remplacer)
Utilisez cette route lorsque vous souhaitez recharger l'intégralité de la source de données sous la forme d'un instantané complet et neuf.
Quand l'utiliser :
Chargement initial.
Intégrations « full refresh » récurrentes (export complet nocturne ou hebdomadaire).
Corrections importantes pour lesquelles tout remplacer est la solution la plus simple.
2) Upsert des données (ajouter ou mettre à jour des lignes)
Utilisez cette route lorsque vous souhaitez ajouter de nouvelles lignes et mettre à jour les lignes existantes de façon incrémentale, sans renvoyer l'ensemble du jeu de données.
Quand l'utiliser :
Mises à jour en quasi temps réel (entités nouvelles ou modifiées).
Exports delta quotidiens.
Maintenir une source de données synchronisée sans rechargement complet.
Attention : le comportement « upsert » repose sur la ou les clés uniques configurées dans Paperbox. Si vous ne savez pas quelle clé est définie, vérifiez les paramètres de la source de données dans l'interface. Important : des colonnes manquantes provoquent une erreur 400 Bad Request ; chaque upsert exige toutes les colonnes.
3) Charger des suppressions (supprimer des lignes)
Utilisez cette route lorsque vous souhaitez supprimer des enregistrements d'une source de données existante.
Quand l'utiliser :
Entités supprimées dans le système source.
Suppressions dans le cadre du RGPD ou d'une politique de conservation (le cas échéant).
Nettoyage de données de référence obsolètes.
Attentes concernant la payload CSV
Les trois routes acceptent :
content_type = text/csvpayloadsous la forme d'un envoi de fichier binaire (le contenu de votre CSV)
Conseils pratiques :
Utilisez une ligne d'en-tête contenant les noms de colonnes.
Assurez-vous que la ou les colonnes clés (identifiant unique) sont présentes et formatées de manière cohérente.
Privilégiez des encodages stables (UTF-8) et des séparateurs cohérents.
Charger des datasources manuellement via l'interface
Outre l'Integration API, les sources de données peuvent également être chargées manuellement via l'interface Paperbox. Lors d'un chargement via l'interface :
Seuls les fichiers JSON sont pris en charge.
La structure du JSON doit correspondre au schéma de la source de données.
Important : des colonnes manquantes provoquent une erreur 400 Bad Request.
Comme pour les chargements via l'API, les nouveaux champs sont créés automatiquement s'ils apparaissent dans le jeu de données chargé.
Les types de champs et leur configuration peuvent être ajustés ensuite dans l'interface si nécessaire.
Les chargements manuels sont surtout utiles pour :
Des correctifs rapides ou des tests.
De petits jeux de données.
Des mises à jour ponctuelles.
Pour des mises à jour automatisées ou récurrentes, nous recommandons d'utiliser les routes de l'Integration API décrites ci-dessus.
FAQ : « Je dois ajouter 1 à 2 nouveaux champs (colonnes). Puis-je simplement recharger le fichier ? Les champs sont-ils créés automatiquement ? »
FAQ : « Je dois ajouter 1 à 2 nouveaux champs (colonnes). Puis-je simplement recharger le fichier ? Les champs sont-ils créés automatiquement ? »
Oui. Si vous chargez un nouveau CSV contenant des colonnes supplémentaires, Paperbox crée ces champs automatiquement sur la source de données à partir des nouveaux en-têtes. Vous pouvez ensuite ajuster la configuration des champs (comme le type de champ) dans l'interface.
Quelle route utiliser ?
Pour repartir d'un contenu entièrement réinitialisé : utilisez Upload a full data version.
Pour ne mettre à jour que certaines lignes (et conserver le reste) : utilisez Upsert data.
C'est possible aussi bien via l'interface que via l'API. Dans les deux cas, ajoutez les nouvelles colonnes à l'en-tête de votre CSV : Paperbox les reconnaîtra automatiquement.