Notes de Version de l'API 0.2.145

Build 0.2.145 · PAR POS v5.16 r2 · Historique des versions v2.0 · Juin 2026

Rapport de modification de l'API : v5.16 → v5.16 r2

Aucune modification majeure dans cette version. Toutes les modifications sont entièrement rétrocompatibles. Les intégrations existantes ne nécessitent aucune modification de code.

Portail API et documentation

La documentation complète de l'API, incluant des exemples de messages, des définitions de schémas et des descriptions de champs, est disponible sur le portail développeur PAR.

Bonnes pratiques en matière d'API

Taux de requête et traitement par lots

Les requêtes par lots doivent être séquentielles. Si les systèmes des clients finaux autorisent le traitement multithread, veuillez respecter les limites de requêtes par minute (RPM) recommandées ci-dessous.

Les modifications doivent d'abord être publiées et testées sur un seul emplacement, puis déployées sur d'autres emplacements.

Si des modifications sont effectuées en parallèle à plusieurs emplacements, seules les modifications d'enregistrements individuels doivent être exécutées ; les opérations par lots ne sont pas recommandées dans les scénarios parallèles.

Les modifications apportées à un emplacement ne doivent pas être répercutées simultanément sur plus de 500 emplacements.

Limites de débit (applicables à la fois à la publication en fin de journée et à la publication immédiate)

Groupe de points de terminaison Taille maximale du lot RPM max
SaveItems, SaveDestinations, SaveTaxes 100 5
DeleteItems, DeleteDestinations, DeleteTaxes 20 5
SavePriceChange / DeletePriceChange Non recommandé (un seul enregistrement) —

API Build 0.2.145 — Nouveautés

Nouvelles fonctionnalités

IDENTIFIANT Description
AS1-3617, AS1-3495, AS1-3638 Tarification par groupe de modificateurs DSP — Prise en charge SOAP ajoutée. Les opérations SOAP SavePriceChanges et GetPriceChanges (Settings2.svc) prennent désormais en charge une tarification alternative par groupe de modificateurs et par partenaire de services de livraison (DSP), conformément à l'implémentation REST de la version 0.2.143. Un modèle imbriqué PriceChange → ModifierGroupPriceChanges → ModifierGroupItemPriceChanges est utilisé. Utilisez des identifiants négatifs pour la création d'enregistrements et des identifiants positifs pour les mises à jour. Remarque : ModifierGroupPriceChange et ModifierGroupItemPriceChange font partie du contrat d'exécution, mais ne sont pas encore déclarés dans le WSDL Settings2.xml publié sur le CDN (voir la section « Modifications du WSDL » ci-dessous). Les champs de tarification des modificateurs dans le contrat SOAP suivent la notation PascalCase (ModifierGroupId, ModifierGroupItemId, Price) ; le champ Nom du groupe est accepté, mais non enregistré. La sémantique d'enregistrement est uniquement delta : seuls les éléments du groupe de modificateurs modifiés sont envoyés, et non le groupe complet.

Modifications apportées à WSDL (0.2.143 → 0.2.145)

Dans cette version, les fichiers WSDL publiés par le CDN présentent le statut suivant. Les clients SOAP utilisant des proxys générés automatiquement à partir du WSDL du CDN doivent consulter les notes ci-dessous avant d'appliquer une tarification avec modificateurs.

WSDL Changement de 0.2.145 Notes
Settings2.xml Aucun changement (octets identiques) Les types ModifierGroupPriceChange et ModifierGroupItemPriceChange ne sont PAS déclarés dans le WSDL publié sur le CDN. Utilisez les formes de contrat d'exécution décrites dans ce guide. Consultez les fichiers wsdl-diff/WSDL_DIFF_REPORT.txt et wsdl-diff/MODIFIER_SCHEMA.txt pour obtenir tous les détails des différences.
Sales2.xml Mis à jour Ajoute trois nouveaux champs au type Order : CustomerMaskedAccountNumber (numéro de compte de carte-cadeau masqué, selon AS1-3581) ; FutureDateOrderStatus (chaîne de statut de la commande future (FDO) — Pending, Processed ou Closed — selon POG-3254/AS1-3493) ; et AccountNumber sur OrderGiftCard (quatre derniers chiffres de la carte-cadeau, selon AS1-3581). Les intégrateurs qui utilisent les opérations SOAP GetOrders ou GetFutureDateOrders doivent régénérer leurs proxys ou ajouter manuellement ces champs à leurs contrats.
HouseAccounts.xml Aucun changement Aucune modification pertinente pour l'API dans cette version.
Kitchen.xml Aucun changement Aucune modification pertinente pour l'API dans cette version.
Labor2.xml Aucun changement Aucune modification pertinente pour l'API dans cette version.
Ordering.xml Aucun changement Aucune modification pertinente pour l'API dans cette version.
Settings.xml (v1) Aucun changement Aucune modification pertinente pour l'API dans cette version.

Règles des champs clés (SOAP et REST)

Champ Règle
ModifierGroupItemId (SOAP) / modifierGroupItemId (REST) Correspond à ModifierGroupItem.Id (l'identifiant du conteneur/de la correspondance), et NON à l'ItemId du menu.
Price / price Obligatoire pour les modificateurs dont ModifierPriceMethod = ModifierPrice.
Nom du groupe (SOAP) Accepté dans le XML, mais non enregistré. À omettre par souci de clarté.
Nom de l'article / originalPrice Non enregistrés ; ne font pas partie du schéma REST.
Sémantique d'enregistrement Delta uniquement — envoyez seulement les éléments du groupe de modificateurs modifiés, et non le groupe complet.
Création ou mise à jour Utilisez un Id négatif pour les nouveaux enregistrements et un Id positif pour les enregistrements existants.

API Build 0.2.143 — Nouveautés

Nouvelles fonctionnalités

IDENTIFIANT Description
AS1-3581 Les quatre derniers chiffres d'une carte-cadeau sont maintenant renvoyés par GetOrders. L'API GetOrders (REST et SOAP) renvoie maintenant les quatre derniers chiffres du numéro de compte d'une carte-cadeau dans un nouveau champ AccountNumber de l'objet OrderGiftCard. Le champ est masqué par mesure de sécurité, conformément à la façon dont les numéros de cartes de paiement sont traités ailleurs dans l'API. La documentation du portail API et le schéma OpenAPI ont été mis à jour pour refléter le nouveau champ. Remarque : AccountNumber n'est renseigné que pour les éléments OrderGiftCard et ne s'applique pas aux autres types de lignes de commande.

AS1-3318

AS1-3582

Mises à jour des prix et de la disponibilité des promotions par SavePromotions via l'API (intégration PMP/RSI). L'API SavePromotions prend maintenant en charge la modification du prix et de la disponibilité des promotions au moyen d'intégrations de gestion des prix externes comme RSI/PMP.

Deux nouveaux points de terminaison REST sont maintenant disponibles pour gérer les promotions :

  • POST /settings/v1/promotions – Crée une ou plusieurs nouvelles promotions. Renvoie HTTP 201 avec les identifiants attribués.

  • PUT /settings/v1/promotions – Met à jour des promotions existantes. Renvoie HTTP 200.

Une nouvelle opération SOAP SavePromotions est également disponible et prend en charge les mêmes flux de création et de mise à jour.

Types de promotions pris en charge : BOGO, carte-cadeau, coupon, réduction de commande et combo.

Les promotions peuvent inclure des configurations complexes telles que des admissibilités, des articles de rabais, des composants de combo, des destinations, des sections, des articles ou groupes admissibles et des champs personnalisés — tous avec des identifiants attribués automatiquement à la création.

Les modifications peuvent être publiées immédiatement ou au moyen de jeux de modifications.

Les champs obsolètes ont été clairement indiqués dans le contrat de l'API afin d'orienter les intégrateurs loin des propriétés désuètes.

Remarques

  • Lors de la création de promotions au moyen de l'API REST, la charge utile de la requête doit utiliser des identifiants négatifs ; des identifiants positifs sont requis lors de la mise à jour de promotions existantes.

  • L'opération SOAP SavePromotions contourne certaines validations par conception — les intégrateurs doivent s'assurer de l'exactitude des données avant de les soumettre.

  • Le type de données MarketingCampaigns doit être demandé explicitement dans l'appel GetSettings ; il n'est pas renvoyé par défaut.

  • Plusieurs champs obsolètes sont maintenant marqués comme désuets dans le schéma de l'API. Les intégrateurs doivent les examiner et cesser de les utiliser dans leurs futures intégrations.

AS1-3495, AS1-3546, AS1-3557, AS1-3578 Tarification par groupe de modificateurs propre aux DSP ajoutée. Les API SavePriceChange et GetPriceChange prennent maintenant en charge une tarification alternative par groupe de modificateurs et par partenaire de services de livraison (DSP). Un nouveau champ de tableau ModifierGroupPriceChanges a été ajouté au type de données PriceChange, ainsi que deux nouveaux types de données : ModifierGroupPriceChange (identifiant du groupe de modificateurs, nom et liste des changements de prix des articles) et ModifierGroupItemPriceChange (identifiant de l'article et prix mis à jour). Le service de commandes (Ordering Service) applique maintenant la logique de tarification propre aux DSP lorsque la méthode de prix d'un élément de groupe de modificateurs est réglée à ModifierPrice. La documentation complète du portail API et des exemples de code (C#, C# Core, Python, XML) sont inclus. Cette modification est entièrement rétrocompatible — le champ ModifierGroupPriceChanges est facultatif et n'est requis que lorsqu'une tarification de modificateurs propre aux DSP est nécessaire. Mettez à jour vos collections Postman et vos suites SoapUI en conséquence.
AS1-3583 GetSettings renvoie maintenant les données de campagnes de marketing pour SavePromotion. La réponse de l'API GetSettings inclut maintenant les champs de données de campagnes de marketing, conformes à la structure et aux noms de champs présentés dans l'interface de l'Éditeur de paramètres. Ces données sont une entrée requise pour l'API SavePromotion — les attributs de campagne renvoyés par GetSettings doivent être fournis de nouveau lors de la création ou de la modification d'une promotion par l'API. Sans ce correctif, les opérations d'enregistrement de promotions échoueraient à la validation.
POG-3254 Le statut FDO est maintenant inclus dans les données de commandes historiques. Le statut FDO (Pending / Processed / Closed) est maintenant exposé par l'API infonuagique pour les intégrateurs de l'arrière-guichet. Auparavant, le statut FDO était disponible dans le modèle de données historiques (Historical Data Model, Order:v1.4), mais n'était pas renvoyé par l'API GetOrders, ce qui empêchait les intégrateurs de déterminer la date comptable prévue d'une commande de livraison future (Future Delivery Order). Cette modification relie la propriété de bout en bout : le HD Worker lit maintenant FutureOrderDetail.Status à partir des messages HDM entrants et le conserve dans la colonne JSONB Details, les anciens contrats PosHistorical ont été mis à jour, et le statut est correctement désérialisé et renvoyé par l'API infonuagique. Remarque : le champ Status est facultatif (nullable) — les commandes sans données FDO renverront null, et les intégrations existantes ne sont pas touchées. Voir AS1-3493 pour le travail de suivi visant à associer le statut FDO au modèle HistoricalOrderFutureOrder de brink.externalapi.
MPP-37 Améliorations des API CalculateOrder et SubmitOrder. Les deux API prennent maintenant en charge les rabais en pourcentage et à montant fixe au moyen des champs discountPercentage et discountAmount, appliqués au sous-total avant taxes. SubmitOrder a été étendue avec trois capacités additionnelles : un champ employeeId pour associer les commandes à un employé précis (prenant en charge la gestion des pourboires, la gestion des tiroirs et la mise en commun des pourboires) ; des métadonnées de paiement élargies, notamment CardType, CardNumber (masqué aux quatre derniers chiffres), TransactionNumber et TransactionIdentifier ; et la prise en charge des frais supplémentaires ajoutés automatiquement. Les fonctionnalités existantes de CalculateOrder et de SubmitOrder demeurent inchangées.

Historique des versions

Version Date Mises à jour
1.0 8 juin 2026 Version initiale
2.0 10 juillet 2026 Ajout de la section API Build 0.2.145 avec AS1-3617, AS1-3495, AS1-3638 ; tableau des modifications WSDL