Journal des modifications de l'API

Modifications de l'API REST /api/v1 intéressant les développeurs, les plus récentes d'abord. Les ajouts non cassants (nouveaux champs optionnels, nouveaux points de terminaison) sont signalés pour information ; tout ce qui modifie une réponse ou une forme de requête existante est marqué Modifié.

2026-08-19 — médias vidéo

Ajouté. La bibliothèque de médias accepte la vidéo.

• POST /api/v1/assets/upload-url accepte video/mp4, video/webm et video/quicktime, avec une limite de 100 Mo chacun. assetType gagne la valeur video, et AssetView.assetType peut désormais la renvoyer.
• assetType doit concorder avec mimeType : un type video/* exige assetType: "video", un type image/* exige "image". Une divergence renvoie 422. Les types de documents ne sont pas contraints : un PDF peut donc rester document, certificate ou other.
• Les URL d'envoi présignées pour la vidéo sont valables une heure plutôt que dix minutes — 100 Mo ne se transfèrent pas de façon fiable dans la fenêtre courte sur une connexion lente, et un PUT qui dépasse la fenêtre ne peut pas être confirmé. Lisez expiresAt plutôt que de supposer une valeur fixe.
• La vidéo est stockée et servie telle quelle. Il n'y a ni transcodage ni image d'aperçu : POST /api/v1/assets/{id}/renditions renvoie toujours 422 pour tout ce qui n'est pas une image, et aucune vignette n'est générée à l'envoi.

2026-08-19 — les envois de médias sont validés contre le fichier stocké

Modifié. POST /api/v1/assets/confirm valide désormais l'objet réellement envoyé, et non les valeurs du corps de la requête.

• sizeBytes dans le corps de confirmation est ignoré (et n'est plus obligatoire ; il reste accepté pour que les clients existants continuent de fonctionner). La taille stockée — et celle qui compte dans votre quota de stockage — est celle que rapporte le stockage d'objets.
• La limite de taille s'applique à cette taille réelle. Une confirmation dont l'objet stocké dépasse la limite renvoie 422, et l'objet envoyé est supprimé : un envoi refusé ne laisse plus d'octets derrière lui.
• Les premiers octets du fichier sont vérifiés contre le type MIME déclaré. Un fichier dont le contenu ne correspond pas à la déclaration est rejeté avec 422 et supprimé.
• La limite PDF est désormais de 50 Mo (contre 100 Mo). Les images restent à 20 Mo. La limite s'applique à la confirmation : les médias déjà stockés ne sont pas concernés.

Ajouté. POST /api/v1/assets/upload-url accepte un sizeBytes optionnel. Fournissez-le et un envoi trop volumineux est refusé avant tout transfert d'octets, plutôt qu'après.

Modifié. Le branding.logoAssetId d'un portail de marque n'est honoré que s'il référence une image. Le pointer vers un PDF ou un autre média non-image omet désormais le logo du portail publié au lieu de publier ce fichier. Les logos de portail publiés sont servis sans authentification : c'était donc un moyen de rendre public n'importe quel média de la bibliothèque.

2026-08-19 — transformRules retiré de l'API des canaux

Modifié. Le champ transformRules disparaît de POST /api/v1/channels, PATCH /api/v1/channels/{id} et de tous les corps de réponse de canal.

• Il était accepté, stocké et renvoyé, mais le moteur de syndication ne l'a jamais lu — la transformation d'un canal a toujours été pilotée entièrement par attributeMap.
• L'envoyer renvoie désormais 422 : les corps de requête de canal rejettent les champs inconnus.
• Rien de ce qu'il réservait n'est perdu. Les valeurs par défaut et constantes à l'échelle du canal s'expriment aujourd'hui via les opérations de transformation default et constant dans attributeMap.

Si vous envoyiez transformRules, retirez-le de la requête. Si vous le lisiez dans une réponse, vous lisiez une valeur qui valait toujours {}.

2026-08-13 — facettes de recherche, verdicts de publication et un changement de comportement de la syndication

Ajouté. GET /api/v1/search/products gagne le facettage.

• facetBy — séparé par des virgules, dans une liste blanche fixe : categoryId, categoryName, tags, status, qualityScore, supplierName. Toute autre valeur donne 422. Lorsqu'il est fourni, la réponse gagne facets: [{ "field": "...", "counts": [{ "value": "...", "count": 12 }] }].
• qualityBand — red | amber | green, filtrant sur la complétude des données. qualityScore est facetté selon ces trois bandes (et non des valeurs brutes 0–100), avec les seuils déjà utilisés par le tableau de bord qualité : vert ≥ 90, orange 60–89, rouge sous 60.
• Les documents produit gagnent qualityScore en option (la complétude minimale sur les langues activées du fournisseur — absente si le produit n'a jamais été évalué) et supplierName, que le catalogue acheteur affichait auparavant comme — parce qu'il était déclaré mais jamais indexé.
• categoryName — un nouveau paramètre de filtre. La facette categoryName renvoie des noms : c'est ce qui la rend exploitable (categoryId attend toujours un UUID).
• Les comptes de facettes sont toujours calculés dans votre propre périmètre d'accès et ne révèlent donc jamais l'existence de produits que vous ne pouvez pas lire.

Ajouté. POST /api/v1/rendition-presets/{id}/reprocess → 202 { enqueued, hasMore }. Regénère les déclinaisons qu'une modification de préréglage a rendues obsolètes, par pages bornées — appelez jusqu'à ce que hasMore soit false. PATCH /rendition-presets/{id} regénère en outre un nombre borné de déclinaisons en ligne lorsqu'il modifie ops, en renvoyant le même objet que reprocess.

Ajouté. Les éléments de GET /api/v1/channels/{id}/publications gagnent evaluation — le verdict par publication (missingRequired, transformErrors, warnings, localeFallbacks) — et externalRef, l'identifiant d'enregistrement attribué par la destination. GET /api/v1/analytics/export accepte from / to (le PDF affichait auparavant une tendance en un seul point quelle que soit la fenêtre).

Modifié — la syndication refuse désormais de livrer un enregistrement sciemment incomplet. Un produit dont la transformation d'attribute-map échoue, ou auquel manque une cible marquée required, est désormais skipped avec le motif dans last_error et evaluation au lieu d'être livré avec ce champ retiré. Si vous comptiez sur une livraison partielle, ces produits cesseront d'arriver à destination tant que le mappage ou les données produit ne sont pas corrigés — et c'est bien l'intention : le comportement précédent envoyait silencieusement des données fausses à des tiers.

Modifié — la locale d'un canal s'applique désormais réellement. Les surcharges localisées de name et d'attributs sont résolues selon la langue du canal (elles étaient auparavant totalement ignorées, chaque canal émettant donc les valeurs canoniques). Attendez-vous à ce que la première publication après cette version renvoie les produits qui ont des traductions, car leurs charges utiles changent légitimement. evaluation.localeFallbacks liste les champs retombés sur la valeur canonique parce que la langue du canal n'a pas de surcharge.

Corrigé. Les nouvelles tentatives de livraison fonctionnent (un échec transitoire de destination est réessayé au lieu d'être enregistré comme un échec permanent dès la première tentative), la livraison par lot honore les résultats par enregistrement au lieu d'appliquer un verdict unique à l'ensemble, et une relivraison vers une destination adressable met à jour l'enregistrement existant au lieu d'en créer un doublon.

2026-08-11 — le total des listes est désormais optionnel

Modifié. GET /api/v1/products et GET /api/v1/admin/orgs/{id}/products n'incluent plus le compte total dans la réponse par défaut. Passez ?withTotal=true pour l'obtenir.

• Pourquoi : le COUNT(*) par page dominait la latence des listes à grande échelle (il parcourt bien plus que la page), et la pagination par curseur n'a jamais besoin d'un total. La réponse de liste par défaut se réduit à { "items": [...], "nextCursor": "..." }.
• Migration : si vous lisez total, ajoutez withTotal=true à la chaîne de requête. Les clients qui ignoraient total n'ont rien à changer. La pagination par curseur (items + nextCursor) est inchangée — voir Pagination.