/Vérifié le 13 novembre 2026

Fonctionnalités natives ou manquantes et limitations fondamentales des API : un exemple avec les codes de serrures

Quand une serrure ne sait pas faire expirer un code, qui se charge alors de le programmer puis de l'effacer, et que se passe-t-il quand la serrure ne répond pas ? Cet article explore l’un des multiples exemples de limitations et d’adaptation possible du fonctionnement des API des fabricants.

Imaginez qu’un voyageur qui loue un logement sur une plateforme de location courte durée arrive vendredi à 16 heures et reparte dimanche à 11 heures. Son hôte, on s’en doute, voudra idéalement lui transmettre un code d’accès qui marchera pendant toute la durée de son séjour mais uniquement celle-ci, c’est-à-dire qui fonctionnera dès son arrivée et qui cessera de fonctionner ensuite. Certaines API des fabricants, pourvu qu’elles soient utilisées avec certaines serrures, permettent de faire cela nativement. On leur confie alors le code et deux dates, et les serrures gèrent cette fenêtre d’autorisation au moyen de leur propre horloge (moyennant quelques imprécisions possibles que l’on vous explique en détail dans cet article).

Pour que la serrure gère elle-même cette plage de dates, deux conditions doivent être réunies. L'API du fabricant doit accepter qu’un code soit accompagné d'une date de début et d'une date de fin. Par ailleurs, la serrure doit savoir enregistrer ces deux dates avec le code et les comparer à son horloge. Si l'une de ces deux conditions n’est pas réunie, il n’est pas possible que la serrure gère cette fenêtre temporelle par elle-même. Elle reçoit alors le code sans aucune date (soit parce que le système lui-même n’a pas pu les lui transmettre, soit qu’elle ne soit elle-même pas capable de les stocker), et pour elle, ce code reste valable jusqu'à ce qu'elle reçoive l'ordre de l'effacer. Il faut dans ce cas qu'un logiciel transmette le code à la serrure le vendredi (sans date, un code envoyé 1 semaine avant commence déjà à fonctionner une semaine avant) et lui envoie l'ordre de l’effacer le dimanche.

Quand le logiciel de l'hôte passe par Seam, ce sont nos serveurs qui se chargent de cette intendance. Ce travail fait partie de ce que nous appelons, chez Seam, le “synthetic layer”, c’est-à-dire une surcouche que nous apposons par-dessus toutes les API que nous intégrons pour les tirer plus haut et les mettre à niveau vers des capacités qu’elles n’ont pas toujours toutes en commun. Nous allons vous décrire rapidement ici ce qu’on fait avec la planification des codes d’accès.

Quant au casse-tête que représente cette intendance qui unifie l’ensemble des API, nous avons une autre formule pour le qualifier : c’est « l'enfer des intégrations directes avec les API des fabricants », au même titre que les pièges entre le logiciel et la porte et les versions d'API qui s'empilent.

Sur une serrure qui ne reçoit pas de dates, nos serveurs transmettent le code peu avant l'arrivée et l'effacent au départ

Notre documentation dresse la liste des , c'est-à-dire des plateformes logicielles des fabricants, avec lesquels nous avons la possibilité de transmettre un code en l’accompagnant d’une plage de dates (Seam, codes d'accès). Nous parlons dans ce cas de programmation native. Pour ces fournisseurs, nos serveurs transmettent le code et ses deux dates à la serrure 72 heures avant l'heure d'arrivée, par défaut, ce qui laisse une marge de sécurité (en cas de défaut de connectivité, auquel cas nous réessayons régulièrement ensuite). La serrure active alors le code à l'heure de début de la plage définie (souvent un peu avant, comme on l’explique dans cet autre article) puis le garde actif jusqu'à l'heure de fin (un peu après, là aussi). Ces mécanismes sont ceux de notre API de codes d'accès, que notre documentation présente comme une API de bas niveau ; pour donner un accès à une personne, elle recommande les Access Grants (Seam, codes d'accès).

Pourquoi ne le transmettons-nous pas encore plus à l’avance, si nous le pouvons ? Tout simplement parce qu’un code transmis à l'avance vient occuper par avance un emplacement mémoire dans la serrure, et que sur ces serrures, il existe toujours un nombre maximal de codes qu’il est possible de stocker par avance (Seam, exigences des serrures pour les codes).

Pour les autres fournisseurs, les deux dates d’une plage programmée restent sur nos serveurs puisqu’il n’est alors pas possible de les transmettre. Comme nous l’expliquons dans notre documentation, nos serveurs transmettent alors le code à la serrure 60 minutes avant l'heure d'arrivée, pour le rendre actif. À l'heure de départ, nous transmettons un nouvel ordre, pour effacer le code qui doit dès lors cesser de fonctionner (Seam, codes d'accès).

Qui garde les datesSi le fournisseur accepte des dates, la serrure les garde. Sinon nos serveurs les gardent, et les traduisent en deux ordres.
Une frise du mardi au dimanche pour un séjour du vendredi 16h au dimanche 11h, sur deux lignes, chacune avec nos serveurs au-dessus de la serrure. Quand le fournisseur accepte des dates : le mardi à 16h, 72 heures avant par défaut, nos serveurs transmettent le code et ses dates ; la serrure le stocke, inactif, et sa propre horloge l'active et le désactive du vendredi 16h au dimanche 11h. Quand le fournisseur ne prend que le code : les dates restent sur nos serveurs, qui transmettent le code une heure avant l'arrivée ; il est actif dès qu'il est stocké, puis un ordre d'effacement suit le dimanche à 11h.
Qui garde les datesSi le fournisseur accepte des dates, la serrure les garde. Sinon nos serveurs les gardent, et les traduisent en deux ordres.
Une frise du mardi au dimanche pour un séjour du vendredi 16h au dimanche 11h, sur deux lignes, chacune avec nos serveurs au-dessus de la serrure. Quand le fournisseur accepte des dates : le mardi à 16h, 72 heures avant par défaut, nos serveurs transmettent le code et ses dates ; la serrure le stocke, inactif, et sa propre horloge l'active et le désactive du vendredi 16h au dimanche 11h. Quand le fournisseur ne prend que le code : les dates restent sur nos serveurs, qui transmettent le code une heure avant l'arrivée ; il est actif dès qu'il est stocké, puis un ordre d'effacement suit le dimanche à 11h.
La ligne qui s'applique dépend du fournisseur, et non du modèle de serrure.

Cette liste est tenue par fournisseur, et non par modèle de serrure (Seam, codes d'accès). Une serrure peut utiliser un protocole radio capable de transmettre des horaires sans que la plateforme qui la pilote ne les transmette. Une même plateforme domotique peut aussi transmettre des horaires d'accès à ses serrures Matter mais ne pas le faire pour ses serrures Z-Wave… Nous expliquons cette étrangeté dans cet article.

Dans les deux cas, notre API indique à chaque instant à quel stade se trouve le code. Il peut être en attente d'envoi, en cours d'envoi, enregistré sur la serrure mais pas encore actif, actif, ou en cours d'effacement (Seam, cycle de vie des codes d'accès).

Pour qu'un code commence et cesse de fonctionner à la bonne heure locale, nous devons aussi connaître le fuseau horaire de la serrure, ce qui n’est malheureusement pas toujours possible. Le cas qui pose problème est celui du changement d'heure, qui décale l'heure locale d'une heure par rapport au temps universel. Si la période de validité d'un code chevauche un passage à l'heure d'été ou d'hiver dans au moins l’un des fuseaux où la serrure peut se trouver, nous ajoutons une heure de marge. Cette heure prolonge la fin de période au printemps et le début de période à l'automne. Le code reste ainsi valable pendant le changement d'heure, mais il est possible qu’il continue de fonctionner une heure en plus que ce qui était souhaité. Notre API le signale par l'avertissement time_frame_adjusted_for_unknown_time_zone, et la marge disparaît dès l’instant où le fuseau horaire de la serrure est renseigné (Seam, erreurs et avertissements des codes d'accès).

Chaque serrure possède ses règles de code, et notre API les publie afin de pouvoir s’y conformer

Les serrures à clavier n'acceptent pas n'importe quel code. Pour chacun de ces appareils, notre API publie les longueurs de code acceptées, le nombre maximal de codes qu’il est possible de stocker simultanément, et la liste des règles que le code doit respecter. Nous avons consigné douze règles de ce type (Seam, exigences des serrures pour les codes). Certaines serrures refusent par exemple les codes qui contiendraient un zéro. D’autres refusent ceux qui commencent par 12. D'autres encore refusent les suites croissantes comme 1234 ou les suites décroissantes comme 9876, les codes constitués d'un seul chiffre répété, ou ceux qui ne contiendraient pas trois chiffres distincts au moins. Certaines serrures à cylindre, rappelons-le, ne disposent pour leur part que des touches 1 à 6 sur leur clavier, et refusent donc logiquement tout code qui contiendrait un 0, un 7, un 8 ou un 9. Enfin avec certains types de serrures, ce n’est pas le logiciel de l'hôte qui génère le code, mais la plateforme du fabricant qui le génère par elle-même. Si la serrure accepte qu'on lui fournisse un code mais que l'hôte n'en fournit pas, nous en générons un, à la longueur qu'il préfère dans la mesure où la serrure accepte les codes de cette taille (Seam, créer des codes d'accès)…

Et nous ne sommes pas au bout de nos peines, car le nom utilisé pour désigner le code doit lui encore respecter ses propres règles. Selon le fabricant, il peut être d’une longueur bien spécifique ou encore devoir être unique. Certains doivent être articulés en deux valeurs : prénom et nom (l’idée étant de les rattacher au nom de leur utilisateur).

Pour éviter des situations bloquantes, notre API peut prendre l’initiative de raccourcir des chaînes de caractères ou d’ajouter des caractères, en renvoyant dans un champ à part le nom tel qu'il apparaît dans l'application du fabricant ou sur la serrure, afin que l'hôte puisse retrouver sans difficulté le code qu'il a créé (Seam, codes d'accès).

Grâce à la définition explicite de ces règles, les logiciels qui utilisent l’API Seam peuvent vérifier la validité d’usage des codes avant de les envoyer, en évitant l’un des pièges qui peuvent les amener à dysfonctionner (Seam, exigences des serrures pour les codes).

L'application du fabricant peut modifier le code, et nos serveurs le reprogramment, à moins que l'hôte n’ait autorisé le nouveau code

Les propriétaires des serrures continuent généralement d’utiliser l'application native du fabricant, qui communique elle aussi avec les serrures et peuvent leur apporter des modifications en même temps que nos serveurs. Ils peuvent ainsi potentiellement modifier les chiffres d'un code que nous aurions programmé, changer ses dates, ou même l'effacer. Dès lors, le code enregistré sur la serrure ne correspond plus au code qui est décrit par notre API.

Par défaut, nos serveurs reprogramment la serrure pour que le code corresponde de nouveau à celui que décrit notre API, y compris quand le code a été effacé, et ils le font jusqu'à la date de fin du code. Notre API envoie alors l'événement access_code.modified_external_to_seam et attache une erreur au code (Seam, codes d'accès). Notre documentation conseille de prévenir les utilisateurs de ce comportement, parce qu'il peut les surprendre, et de vérifier si une autre intégration branchée sur la serrure modifie les codes (Seam, résoudre les problèmes de codes).

L'hôte peut désactiver ce comportement, code par code, au moment où il le crée. Nos serveurs ne reprogramment alors plus la serrure, et notre API attache au code un avertissement au lieu d'une erreur (Seam, codes d'accès).

Nos serveurs tentent répétitivement de joindre les serrures qui n’ont pas pu l’être, et des codes de secours prennent le relais

Les serrures à piles mettent leur radio en veille la plupart du temps, et la connexion Wi-Fi ou le qui les relie à Internet peut aussi tomber. Aucun logiciel ne peut forcer une serrure injoignable à recevoir un ordre. Les codes hors connexion contournent le problème autrement : la serrure ne reçoit rien, elle calcule elle-même le code que la plateforme a calculé de son côté (nous expliquons ce fonctionnement dans cet article).

Lorsqu’une serrure est capable d’enregistrer elle-même les dates de début et de fin d’un code, nos serveurs les lui transmettent trois jours avant l’arrivée, comme nous l’avons vu plus haut. Si un envoi échoue, notre API l’indique aussitôt dans les informations liées à ce code, par une erreur ou un avertissement : l’hôte l’apprend donc trois jours avant l’arrivée du voyageur, et non le jour même, ce qui lui donne le temps d’agir (Seam, résoudre les problèmes de codes).

Si le code n'est toujours pas enregistré sur la serrure alors que l'heure d'arrivée approche, notre API attache au code l'avertissement delay_in_issuing, et nos serveurs continuent d'essayer (Seam, cycle de vie des codes d'accès). Si l'heure d'arrivée passe sans que le code soit enregistré, notre API attache au code l'erreur failed_to_issue, parce que le voyageur risque de trouver la porte fermée. Nos serveurs continuent malgré tout d'essayer, en cas d'erreur passagère, et retirent l'erreur dès qu'un essai réussit (Seam, résoudre les problèmes de codes).

Un avertissement ne suffit cependant pas pour ouvrir la porte au voyageur. Pour gérer ces cas, nous recommandons toujours d'enregistrer à l'avance sur la serrure une série de codes de secours, qui pourront être fournis en urgence lorsqu'un code n'aura pas pu être programmé (Seam, codes d'accès). Sur les serrures qui le permettent, nous entretenons cette réserve. Quand l'hôte l'active, nos serveurs enregistrent sur la serrure ces codes supplémentaires, en plus des codes ordinaires. Lorsqu’un code ordinaire pose problème, par exemple à cause d'une connexion intermittente, d'un effacement manuel réalisé directement sur la serrure ou dans l'application du fabricant, ou encore à cause d'une panne du service du fabricant lui-même, il est possible de demander un code de secours à notre API pour le fournir directement au voyageur. La date de fin du code de secours peut ensuite être alignée sur celle du code d'origine. Dans l'application du fabricant, les codes de secours apparaissent sous le nom « Backup », suivi de l'identifiant du code et de la mention « (Seam) » (Seam, codes de secours).

Les codes de secours ne sont proposés que pour les codes temporaires, comme ceux qui sont fournis aux voyageurs. Les codes permanents, qui ne possèdent pas de date de fin, ne sont pas remplaçables par des codes de secours. Comme la réserve de code de secours n’est pas inépuisable, s’il arrive qu’elle se vide, notre API marque la serrure avec l’erreur empty_backup_access_code_pool (Seam, codes de secours).

Les codes restés dans la serrure après le départ sont signalés, et nous retentons régulièrement de les effacer

Les serrures qui reçoivent un code et sa plage de validité le gardent actif jusqu'à l'heure de fin, en se basant sur leur propre horloge. Pour les serrures qui ne savent stocker que le code lui-même, l’arrêt de validité du code se réalise par une opération d'effacement que nos serveurs exécutent dès que la date de fin est passée (Seam, codes d'accès). La conséquence de ce fonctionnement est que si la serrure n’est pas joignable au moment de recevoir cet ordre, le code y reste enregistré, et permet encore d’ouvrir la porte.

Notre API attache alors au code l'erreur failed_to_delete, qui signifie que le code est encore actif sur la serrure après sa date de fin et que le voyageur peut encore entrer. Nos serveurs tentent à nouveau d’effacer le code jusqu'à y parvenir, et nous recommandons de s’appuyer sur cette notification pour prévenir le propriétaire de la serrure (Seam, cycle de vie des codes d'accès). Aucun logiciel n’est en effet capable d’effacer un code sur une serrure qu'il n'arrive pas à joindre. C'est aussi pour cette raison que le délai pour révoquer un accès varie sensiblement, selon la façon dont le système atteint la serrure.

Autre cas extrême : si le compte qui relie l'hôte au service du fabricant est déconnecté, ou si la serrure a été elle-même retirée, alors nos serveurs se retrouvent incapables de vérifier ce que la serrure contient. Dans ce cas, notre API affiche l'état du code comme inconnu (Seam, cycle de vie des codes d'accès).

Le code du voyageur, du vendredi au dimanche
Ce que font l'API du fabricant et la serrureCe que nos serveurs ajoutentCe qui reste hors de portée
Les dates du codeAvec la programmation native, la serrure reçoit le code et ses dates et les applique elle-même. Sinon, elle reçoit le code seulLe code envoyé peu avant l'arrivée, l'ordre d'effacement envoyé au départ, une heure de marge si le fuseau horaire est inconnuUne serrure qui ne reçoit pas l'ordre d'effacement
Les règles du codeDes longueurs, un nombre maximal de codes, des règles propres au fabricant ou au modèleLa liste des règles publiée pour chaque serrureLes serrures sur lesquelles le logiciel de l'hôte ne peut pas fournir de code
Le code modifié dans l'applicationL'application du fabricant change ou efface le codeLe code reprogrammé jusqu'à sa date de fin, ou la modification gardée si l'hôte l'a autoriséeLe choix entre les deux comportements, qui revient à l'hôte
La serrure injoignableRadio en veille, Wi-Fi ou bridge tombéUn envoi commencé à l'avance, de nouveaux essais, une alerte avant l'arrivée, des codes de secours déjà enregistrésForcer la serrure à recevoir un ordre
La fin du séjourAvec la programmation native, la serrure désactive le code. Sinon, rienL'ordre d'effacement, renvoyé jusqu'à ce qu'il arriveUn code qui ouvre encore la porte tant que l'ordre d'effacement n'est pas arrivé

La troisième colonne décrit le travail de nos serveurs. La dernière dépend de la serrure et de sa connexion, et aucun logiciel ne la fait disparaître.

Les logiciels qui s'adressent directement aux API des fabricants doivent construire eux-mêmes chacun de ces mécanismes, qui ne sont que quelques exemples parmi d’autres actions que nous réalisons à l’arrière-plan pour améliorer la qualité du service. Pour cela, il faut savoir quels fabricants acceptent des dates avec un code, envoyer et effacer les codes à l'heure pour les autres, tenir registre des règles de code pour chacun des modèles, réagir aux modifications faites dans les applications des fabricants, réessayer aussi longtemps que la serrure ne répond pas et assurer la maintenance d’une réserve de codes de secours.

Smart Locks
Access Systems
Lock Capabilities
Thermostats
Sensors
© 2026 Seam Labs, Inc.