Depuis son déploiement progressif à partir de 2021, Trackdéchets est devenu le système nerveux de la traçabilité des déchets dangereux en France. Obligatoire pour la quasi-totalité des flux de déchets dangereux depuis le 1er janvier 2022, la plateforme de l'État centralise la création et le suivi des bordereaux de suivi de déchets (BSD) de manière dématérialisée. Mais pour les professionnels du recyclage qui traitent des centaines de BSD par mois, se connecter manuellement à la plateforme web pour chaque bordereau est impensable. C'est là qu'intervient l'intégration API : connecter directement votre ERP à Trackdéchets pour automatiser l'ensemble du cycle BSD.
L'API Trackdéchets : architecture et principes de base
Trackdéchets expose une API GraphQL publique, accessible à tout éditeur de logiciel après une procédure d'habilitation. Contrairement aux API REST classiques qui utilisent des endpoints HTTP distincts pour chaque ressource, une API GraphQL utilise un unique endpoint sur lequel le client envoie des requêtes structurées décrivant exactement les données qu'il veut récupérer ou les opérations qu'il veut effectuer.
L'authentification se fait par token OAuth2 : chaque entreprise utilisatrice génère un token depuis son compte Trackdéchets, et ce token est utilisé par l'ERP pour s'authentifier lors de chaque appel API. Il existe deux types de tokens : les tokens personnels (liés à un compte utilisateur) et les tokens d'application (recommandés pour les intégrations ERP, car ils ne sont pas liés à une personne physique et ne sont pas affectés par les changements de personnel).
L'environnement de Trackdéchets distingue deux espaces : l'environnement de recette (sandbox), sur lequel les éditeurs testent leurs intégrations sans créer de vrais BSD, et l'environnement de production. Une intégration sérieuse passe obligatoirement par une phase de test en sandbox avant tout passage en production.
Créer et signer un BSD depuis l'ERP : le flux opérationnel
Dans un ERP recyclage intégré à Trackdéchets, le cycle de vie d'un BSD suit un flux automatisé. Quand un opérateur prépare une mission de collecte de déchets dangereux — par exemple un enlèvement d'huiles usagées (code 13 02 05) chez un client industriel — l'ERP crée automatiquement le brouillon de BSD dans Trackdéchets avec les informations disponibles : producteur (SIRET, adresse), transporteur, destinataire (l'installation de traitement), code déchet, quantité estimée, conditionnement.
Le producteur signe ensuite le BSD depuis le portail client d'Okapia OS ou via l'interface ERP si c'est un de vos propres sites. Cette signature déclenche un appel API vers Trackdéchets qui enregistre la signature et fait passer le BSD au statut « SIGNED_BY_PRODUCER ». Au moment de l'enlèvement, le chauffeur signe depuis l'application mobile— signature qui est transmise à Trackdéchets via l'API et fait passer le BSD au statut « SENT ». À la réception sur l'installation de traitement, le responsable de quai signe la réception depuis l'ERP, ce qui déclenche le passage au statut « RECEIVED ». Enfin, après le traitement effectif des déchets, la déclaration d'opération de traitement finalise le BSD au statut « PROCESSED ».
Toute cette chaîne de signatures se fait depuis l'ERP, sans jamais ouvrir le site web de Trackdéchets. Les statuts se synchronisent automatiquement dans les deux sens : si un autre acteur signe depuis l'interface web de Trackdéchets, l'ERP détecte ce changement lors de la prochaine synchronisation et met à jour son propre enregistrement.
Les différents types de BSD et leurs spécificités API
Trackdéchets gère plusieurs types de bordereaux, chacun avec sa propre structure de données dans l'API. Le BSDD (Bordereau de Suivi de Déchets Dangereux) est le plus courant — c'est le BSD « généraliste » qui couvre la majorité des déchets dangereux. Le BSDA (Bordereau de Suivi de Déchets Amiantés) est spécifique aux déchets contenant de l'amiante et comporte des champs supplémentaires pour le type d'amiante et les mesures de protection.
Le BSFF (Bordereau de Suivi des Fluides Frigorigènes) gère la traçabilité des fluides frigorigènes récupérés lors d'opérations de maintenance ou de démantèlement d'équipements. Le BSVHU (Bordereau de Suivi des Véhicules Hors d'Usage) s'applique aux centres VHU agréés. Le BSDASRI (Bordereau de Suivi des Déchets d'Activités de Soins à Risques Infectieux) concerne les déchets médicaux.
Chaque type de BSD a ses propres mutations GraphQL dans l'API Trackdéchets. Un ERP qui ne supporte que le BSDD sera insuffisant pour les entreprises qui traitent des flux d'amiante ou de VHU. Le module BSD d'Okapia OSsupporte nativement tous les types de bordereaux disponibles dans l'API.
La synchronisation des statuts : éviter les désynchronisations
Le principal défi technique d'une intégration Trackdéchets n'est pas la création des BSD, mais la synchronisation des statuts. En effet, tous les acteurs d'un BSD (producteur, transporteur, destinataire) peuvent agir depuis des interfaces différentes : certains utilisent le site web de Trackdéchets directement, d'autres passent par leur propre ERP. L'ERP du destinataire doit donc détecter et intégrer les changements de statut initiés par d'autres acteurs.
Deux approches existent pour cette synchronisation. La première est le polling périodique : l'ERP interroge l'API Trackdéchets toutes les X minutes pour chaque BSD en cours afin de détecter les changements de statut. Cette approche est simple à implémenter mais consomme beaucoup d'appels API et peut avoir un délai de détection allant jusqu'à plusieurs minutes. La seconde approche, plus moderne, est le webhook : Trackdéchets notifie l'ERP en temps réel dès qu'un BSD change de statut. Cette approche est plus réactive mais nécessite que l'ERP expose un endpoint web accessible depuis l'extérieur.
Un ERP SaaS hébergé dans le cloud est naturellement compatible avec les webhooks Trackdéchets, ce qui permet une synchronisation quasi-instantanée. Pour les installations on-premise derrière un pare-feu d'entreprise, le polling reste souvent la seule option pratique.
Les erreurs courantes et comment les éviter
Plusieurs erreurs reviennent régulièrement lors des intégrations Trackdéchets. La première est l'utilisation de SIRET incorrects : Trackdéchets valide systématiquement les SIRET des entreprises participantes contre la base Sirene. Un SIRET inconnu ou radié entraîne une erreur lors de la création du BSD. Le référentiel clients et fournisseurs de l'ERP doit donc être maintenu à jour avec des SIRET valides — une vérification que le module BSD d'Okapia OSeffectue automatiquement via l'API Sirene.
La deuxième erreur fréquente concerne les codes déchets : Trackdéchets valide que le code déchet utilisé dans un BSD figure bien dans la liste des codes autorisés par l'arrêté du 7 novembre 2016 pour ce type de bordereau. Un code mal formaté (sans les espaces ou tirets requis) ou un code non applicable à ce type de BSD génère une erreur. La liste des codes déchets compatibles avec chaque type de BSD doit être intégrée dans l'ERP et maintenue à jour.
La troisième erreur est liée à la gestion des ruptures de liaison réseau. Si l'ERP ne peut pas joindre l'API Trackdéchets au moment de la signature (panne réseau, maintenance Trackdéchets), il doit mettre l'opération en file d'attente et la rejouer automatiquement dès que la connexion est rétablie — sans perdre les données saisies par l'utilisateur.
L'habilitation éditeur : ce que ça signifie pour vous
Tous les éditeurs d'ERP ne sont pas habilités à utiliser l'API Trackdéchets en production. L'habilitation est accordée par la Direction générale de la prévention des risques (DGPR) après vérification de la conformité de l'intégration. Un éditeur habilité a démontré que son intégration respecte les règles de sécurité et d'intégrité définies par Trackdéchets.
Pour vous, en tant que client, choisir un ERP dont l'éditeur est habilité par Trackdéchets est une garantie importante. Cela signifie que l'intégration a été auditée, que les données de vos BSD sont transmises correctement, et que l'éditeur est tenu informé des évolutions de l'API. Demandez systématiquement ce justificatif lors de votre évaluation d'un ERP recyclage. Pour aller plus loin, lisez notre article dédié à la traçabilité BSD avec Trackdéchets.