Intégration API Box
Nous développons votre connecteur Box
Nous branchons Box à votre dossier métier : dépôt de livrables, réaction à un fichier, audit de partage. Cadrage en amont, alertes en production.
- Équipe produit senior
- connecteurs GED en production
- du cadrage au monitoring
À quoi sert l'API Box et pourquoi connecter Box à son logiciel métier ?
Box est une plateforme de stockage et de gestion documentaire entreprise, avec des fonctions de gouvernance, de rétention et de signature électronique intégrées. Son API permet à votre application de déposer, lire et organiser des fichiers dans Box, de recevoir une notification dès qu'un document est ajouté ou modifié, et de gérer les droits d'accès par dossier. On connecte Box quand la GED est déjà en place et gouvernée, et qu'on veut que le logiciel métier y dépose automatiquement les pièces sans que les équipes basculent d'un outil à l'autre.
Ce que nos clients construisent sur l'API Box
Livrables projet dans le dossier client
Dépôt depuis le métier, FILE.UPLOADED lance la revue. Les IDs Box voyagent, pas les chemins qui se renomment.
RH : App User par salarié
Documents dans un dossier personnel, metadata template « type de pièce ». Pas d'identifiants nominatifs qui survivent à un départ.
Migration cadencée à 240 uploads/min
Le quota qui tue n'est pas le 1 000 général. Reprise, journal d'échecs, pas un pool parallèle naïf.
Audit de partage sur un an
admin_logs pour un incident ou une demande DPO. Les webhooks, limités à un item, ne remplacent pas cette piste.
Ce que ça change dans votre GED Box
La technique au service d'un résultat mesurable : un dépôt métier, une piste d'audit, moins de surprises en production.
Box reste la GED, le métier s'y raccroche
Classement et rétention vivent chez Box. Vous n'inventez pas une taxonomie parallèle que personne ne tiendra.
Un dépôt déclenche la suite
Quand un fichier arrive, le produit sait quoi faire. Moins de relectures aveugles, plus de parcours métier.
L'approbation admin est dans le devis
En entreprise, l'app ne parle pas tant qu'un admin n'a pas autorisé. Un essai sur compte développeur ne prouve pas le go-live.
Les pannes silencieuses sont surveillées
Box peut couper une session sans bruit. On alerte et on recrée, on ne le découvre pas un mois plus tard.
Comment nous livrons votre connecteur Box
Cadrage
CCG ou JWT, App + Enterprise Access, dossiers métier (pas la racine 0), Events vs webhooks. L'approbation admin est un jalon, pas un détail.
Développement
HMAC corps+timestamp, un webhook par item avec tous les triggers, limiteur 240 uploads, IDs Box persistés. Démonstration chaque semaine.
Recette
Deuxième webhook refusé sur le même dossier, port 8443 muet, signature « comme Stripe », developer token d'une heure. Rejeu avant bascule.
Monitoring
Alerte NO_ACTIVE_SESSION, WEBHOOK.DELETED, auto_cleanup. Recréation automatisée. retry-after honoré.
Ce que permet l'API Box
- Fichiers, dossiers, collaborations
- IDs numériques stables, racine 0. Commentaires, tâches, web links, shared links. As-User pour agir au nom d'un utilisateur géré.
- Webhooks v2 signés
- POST vers address, timeout 30 s, retries jusqu'à 12 fois sur 2 heures. BOX-SIGNATURE-PRIMARY et SECONDARY, version 1, HmacSHA256.
- Events entreprise
- admin_logs : un an, chrono, pas de doublons, latence plus haute. admin_logs_streaming : quasi temps réel, deux semaines, doublons possibles, ordre non garanti.
- Metadata, retentions, Box Sign
- Classement métier et durée d'archivage dans Box. Sign dans la même API, avec son quota (100 create/resend par min, 1 000 GET).
Le vocabulaire de l'API Box
- CCG
- Client Credentials Grant, défaut des nouvelles apps serveur. JWT (clé RSA, 2FA pour générer la paire) reste possible. Le bascule JWT ↔ CCG peut être verrouillé par l'entreprise.
- BOX-SIGNATURE-PRIMARY
- HMAC-SHA256 des octets du corps puis du timestamp, digest Base64. Faire confiance si l'une des deux clés (primaire ou secondaire) est valide. Fenêtre 10 minutes. Ce n'est pas Stripe (hex sur le corps seul).
- NO_ACTIVE_SESSION
- Trigger livré quand la session d'auth utilisée à la création du webhook a expiré. Developer token : une heure. Box considère avoir livré ; votre métier ne voit plus les vrais événements.
- auto_cleanup
- Suppression du webhook si dernière livraison réussie il y a 30 jours et plus de 14 jours entre succès et dernier trigger. Payload WEBHOOK.DELETED, reason auto_cleanup.
- admin_logs
- Historique entreprise jusqu'à un an, ordre chrono, pas de doublons. L'inverse de admin_logs_streaming (2 semaines, doublons, faible latence). On choisit, on ne mélange pas les hypothèses.
- As-User
- En-tête pour agir au nom d'un utilisateur géré. Pas de As-User large sans journal. App Users : modèle plateforme sans identifiants nominatifs.
Les contraintes réelles de l'API Box
Un webhook par item, pas la racine
FILE.UPLOADED empêche un second webhook FILE.DOWNLOADED sur le même dossier, même app, même user : on met à jour la liste de triggers. v2 interdit sur 0. Surveiller tout Box, c'est Events API.
240 uploads par minute
Distinct du 1 000 req/min. Search à 6/s est le deuxième plafond. 429 avec retry-after et code rate_limit_exceeded. Des quotas de licence API par entreprise s'y ajoutent.
La signature n'est pas celle de Stripe
Corps puis timestamp, Base64, deux clés, 10 minutes. Une implémentation hex sur le corps seul échoue à 100 %. Comparaison à temps constant. Déduplication sur l'id du corps, pas BOX-DELIVERY-ID (change au retry).
L'approbation admin n'est pas un POC
Compte entreprise : l'app serveur attend un admin. Developer token et compte gratuit auto-autorisé ne prouvent rien. Port 443 uniquement : :8443 ne recevra rien.
API Box ou API SharePoint ?
Deux GED d'entreprise. Le bon dépend de la gouvernance déjà en place, pas du SDK.
| Critère | BoxCette page | Microsoft 365Graph fichiers |
|---|---|---|
| Parc typique | ETI et groupes hors Microsoft 365 | SharePoint / OneDrive du locataire |
| Auth serveur | CCG (défaut 2026) ou JWT, App Users | Entra ID, Sites.Selected |
| Webhook | Payload + HMAC, un par item | Signal Graph, relecture delta |
| Piste d'audit | admin_logs jusqu'à un an | delta sharing + journal applicatif |
| Signature | Box Sign dans la même API | Hors Graph fichiers (Yousign, etc.) |
| Upload | 240 / min / user | Unités + session 320 Kio |
| Le bon cas | Box est déjà la GED gouvernée | Le locataire est déjà Microsoft 365 |
Google Drive et Dropbox se discutent sur des parcs plus PME. Un appel d'offres « connecteur Box » n'est pas une option, c'est souvent une exigence.
Ce que nous mesurons sur une intégration Box
Les autres API de fichiers
Si Box n'est pas la GED du compte, ces options se discutent au cadrage.
BoxNous développons votre connecteur BoxCette page
Microsoft 365SharePoint et OneDrive via Graph, Sites.Selected.
Google DriveDrive Workspace, Picker, export Docs/Sheets.
DropboxPartage de fichiers, curseur list_folder, App Folder.On combine Box avec
La stack qui entoure Box sur nos projets.
Intégration Box : vos questions
App serveur en CCG (défaut 2026) ou JWT, niveau App + Enterprise Access si vous touchez des Managed Users, approbation admin en compte entreprise, webhooks v2 sur des dossiers métier (pas 0), HMAC avant tout parsing, Events admin_logs pour le parc. IDs persistés, pas des chemins. Limiteur 1 000/min et 240 uploads. La partie sensible n'est pas le premier GET fichier, c'est la règle « un webhook par item » et les pannes silencieuses documentées par Box.
Un premier flux utile, typiquement dépôt dans un dossier client plus FILE.UPLOADED vers le métier, se livre en deux à trois semaines, une fois l'app autorisée par l'admin. Un connecteur GED (metadata, Events, Sign, migration 240/min) demande plutôt six à huit semaines. Le jalon d'approbation admin n'est pas du code : il se pose dans le planning dès le cadrage. C'est un arbitrage de cadrage, écrit avant le premier appel, pas une surprise de recette.
CCG est le défaut des nouvelles apps serveur en 2026. JWT (paire RSA, 2FA pour générer) reste documenté, et le bascule peut être verrouillé par un paramètre d'entreprise. Un tutoriel JWT de 2022 n'est plus le chemin de création. On écrit le choix, la rotation des secrets, et on n'utilise jamais un developer token d'une heure hors local (il crée des webhooks NO_ACTIVE_SESSION). C'est un arbitrage de cadrage, écrit avant le premier appel, pas une surprise de recette.
On suit la GED déjà gouvernée. Box si l'entreprise a choisi de ne pas mettre les fichiers dans Microsoft 365, souvent une exigence d'appel d'offres. SharePoint si le locataire Microsoft est déjà le disque. Box livre un payload webhook signé ; Graph fichiers livre un signal à relire. Drive et Dropbox pour des parcs plus PME. C'est un arbitrage de cadrage, écrit avant le premier appel, pas une surprise de recette.
Vérifier HMAC (corps puis timestamp, Base64, primaire ou secondaire, fenêtre 10 min, comparaison à temps constant) avant tout parsing. Corps brut. Répondre 2xx en moins de 30 s, travailler en file. Dédupliquer sur l'id d'événement du corps, pas BOX-DELIVERY-ID. Superviser NO_ACTIVE_SESSION, WEBHOOK.DELETED, auto_cleanup. Port 443, TLS 1.2/1.3, pas d'hôte *.box.com. C'est un arbitrage de cadrage, écrit avant le premier appel, pas une surprise de recette.
Un projet d'intégration Box ?
Parlons-en. 30 minutes pour cadrer CCG, dossiers métier, webhooks, et vous dire franchement ce que l'approbation admin implique.
Parler de mon projet Box