PAR POS ™ | Notes de version de l'API
Version 0.2.152 · PAR POS v5.16r4 · Août 2026
Rapport de modification de l'API : v5.16r3 → v5.16r4
| ✅ 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 POS :
https://developers.partech.com/
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.152 — Nouveautés
Nouvelles fonctionnalités
| IDENTIFIANT | Description |
|---|---|
| AS1-3823 | Champs de paie SaveEmployees CrunchTime. PayrollId et ExportToPayroll existent déjà dans l'API publique Brink save-employees, mais manquaient dans la méthode SaveEmployees spécifique à CrunchTime. La charge utile save-employees CrunchTime accepte désormais ces deux champs et les enregistre de la même façon que le chemin public settings/save employees, afin que les intégrateurs puissent définir l'identité de paie et l'export vers la paie lors de la création d'un employé, sans un second appel à l'API publique. Aucun paramètre du Portail d'administration n'est requis. Incluez PayrollId et ExportToPayroll dans la charge utile de l'employé sur le point de terminaison SaveEmployees spécifique à CrunchTime. Les deux champs sont facultatifs et entièrement rétrocompatibles — les appelants existants qui les omettent ne sont pas affectés. |
Modifications apportées à WSDL (0.2.148 → 0.2.152)
AS1-3823 étend le contrat de requête SaveEmployees spécifique à CrunchTime avec deux champs facultatifs (PayrollId, ExportToPayroll). Aucune modification des fichiers WSDL publiés sur le CDN n'a été identifiée pour les services SOAP couverts par cette version ; les clients SOAP utilisant des proxys générés automatiquement ne nécessitent aucune régénération pour cette version.
API Build 0.2.148 — Nouveautés
Nouvelles fonctionnalités
| IDENTIFIANT | Description |
|---|---|
| AS1-3736, AS1-3737 | Cycle de vie des chauffeurs Deliverect 1PD (Départ/Retour). Ce module complète le cycle de vie des chauffeurs de livraison (1PD) en ajoutant les événements de Départ et de Retour, en complément de l'événement LivraisonDéposée (AS1-3526). Les événements sont initiés au terminal Deliverect, relayés par le client et appliqués à la commande via l'API des événements de livraison (voir ci-dessous). Le Départ enregistre le départ du chauffeur : la commande passe à l'état « En transit » ou « En cours de livraison », et l'horodatage de départ ainsi que le nom du chauffeur sont enregistrés. Un départ couvrant plusieurs commandes génère un événement par commande. Le Retour clôture la course : un événement « TERMINÉ » applique le paiement en espèces au solde restant, clôture la commande et enregistre le résultat. Un événement avec un autre statut est enregistré sans modifier l'état de la commande. Le paiement en cours de route se fait exclusivement en espèces ; l'encaissement par carte n'est pas inclus dans cette version. Aucune session de connexion au terminal de paiement du chauffeur n'est requise pour ces événements (AS1-3760/AS1-3761). Nécessite une destination de type livraison et un mode de paiement en espèces actif disponible pour le chemin de commande/API. |
Événements de livraison 1PD — Surface de l'API
Les exemples ci-dessous présentent les points de terminaison, les en-têtes et le schéma qui sous-tendent le cycle de vie d'extraction et d'enregistrement décrit ci-dessus.
| IDENTIFIANT | Description |
|---|---|
| AS1-3661 | Point de terminaison webhook de sortie avec authentification HMAC. Le client envoie un webhook de sortie par commande à PAR lorsqu'un livreur quitte le magasin. Les requêtes contiennent un en-tête Authorization: HMAC {hex-signature} ; PAR vérifie l'authentification HMAC-SHA256 sur le corps brut de la requête, en fonction du point de vente. Un événement valide est mis en file d'attente pour le magasin cible via SQS et un worker EKS, et PAR répond par un code 202 Accepted. Une signature invalide renvoie une erreur 401 et est consignée. Chaque événement est consigné avec l'identifiant de l'événement (eventId), l'identifiant de la commande (orderId), le numéro de l'emplacement (locationNumber), l'identifiant de l'employé (employeeId), l'horodatage et le code de réponse HTTP. |
| AS1-3650 | Point de terminaison des événements de livraison de l'API Cloud. La requête POST /v1/orders/{orderId}/delivery-events sur le service de commandes de l'API Cloud accepte un événement de livraison et le transmet au point de terminaison correspondant en magasin. La requête contient l'identifiant du chauffeur (DriverEmployeeId), le type d'événement (DriverCheckout ou DriverCheckin) et l'horodatage. L'API Cloud authentifie la requête et la route vers l'emplacement et la pile appropriés. Il s'agit de la partie « magasin » de la paire de points de terminaison des événements de livraison. |
| AS1-3649 | Le point de terminaison des événements de livraison du service de commande en magasin reçoit, via la requête POST /v1/orders/{orderId}/delivery-events, l'événement de sortie ou d'enregistrement acheminé depuis l'API Cloud, avec les mêmes champs DriverEmployeeId, EventType et Timestamp. Le traitement génère un message SQS destiné au système de gestion en magasin (ajouté sous AS1-3626), permettant ainsi à la caisse de mettre à jour l'état de la commande : en transit, encaissement et fermeture. Il s'agit de la partie côté magasin du processus. |
| AS1-3708 | Le paiement en espèces est désormais accepté pour les paiements complémentaires des commandes de livraison. Auparavant, la requête POST /v1/orders/add-payment du service de commandes limitait cette option aux paiements externes ; le type de paiement TenderType.Cash est maintenant également accepté, car le paiement en cours de livraison pour les véhicules de livraison est exclusivement en espèces. Le gestionnaire de messages ApplyPaymentMessageHandler applique la même allocation lorsque la destination de la commande est une livraison. Pour un paiement en espèces, l'identifiant de l'employé (EmployeeId) de la requête est défini sur l'identifiant du propriétaire (OwnerId) de la commande, afin que le paiement soit attribué au chauffeur déjà affecté à la commande de livraison. Ce mode de paiement nécessite un mode de paiement en espèces actif et une destination de type Livraison. |
| AS1-3718 | En-tête Idempotency-Key lors de l'ajout d'un paiement. La méthode ApplyPayment est désormais idempotente ; ainsi, une nouvelle tentative d'enregistrement suite à un délai d'attente réseau ou à une nouvelle tentative du processus n'entraîne pas un double prélèvement. L'appelant envoie l'ID de l'événement en tant qu'en-tête Idempotency-Key ; l'API Cloud (requête POST /v1/orders/{orderId}/add-payment) accepte cet en-tête et le transmet au service de commandes, qui l'intègre dans les propriétés du message SQS. Le système vérifie la présence de la clé dans les données supplémentaires de paiement de la commande, actuellement sous clé : si la clé est déjà présente, il renvoie AlreadyApplied ; sinon, il stocke la clé et applique le paiement. L'API Cloud et le service de commandes renvoient tous deux le code 200 lorsque le système signale AlreadyApplied. Les clients et les processus doivent envoyer l'en-tête ; aucune configuration de stockage n'est requise. |
| AS1-3750 | Les paiements en espèces peuvent désormais inclure des données supplémentaires pour garantir l'idempotence. L'objet ApplyCashPaymentInfo, dérivé de ApplyPaymentInfo et doté d'une collection AdditionalData NameValuePairs, est ajouté afin que les paiements en espèces puissent inclure la clé d'idempotence au même titre que les paiements externes. Les paiements en espèces sont enregistrés dans le flux XML ApplyPayment. Le gestionnaire de messages ApplyPaymentMessageHandler construit désormais un objet ApplyCashPaymentInfo contenant la clé au lieu de transmettre une valeur nulle. Les validateurs considèrent les informations supplémentaires relatives aux paiements en espèces comme facultatives, mais exigent qu'il s'agisse d'un objet ApplyCashPaymentInfo lorsqu'il est présent. Les fonctions d'audit gèrent le type ApplyPaymentInfoType.Cash. Sans cela, un paiement en espèces à l'enregistrement, même tenté à plusieurs reprises, pourrait être appliqué plusieurs fois. Ce système est compatible avec le flux d'idempotence décrit dans la norme AS1-3718. |
| AS1-3745 | Le montant en espèces à l'enregistrement est déduit du solde de la commande. Lors d'un enregistrement 1PD finalisé, ApplyPayment utilise le solde de la commande en cours. Ce solde correspond au montant du paiement en espèces, et non à un montant payé fourni par le client ou Deliverect, qui ne reflète pas le montant exact encaissé sur la route. Ce solde est identique à celui calculé par CloseOrder avant la clôture, permettant ainsi de régler et de clôturer une commande de livraison en espèces impayée sans dépendre d'un champ de montant externe. Ce fonctionnement est conforme au modèle utilisé pour les 3PD selon la norme AS1-3598. |
| AS1-3744 | Le schéma des événements d'arrivée/départ est normalisé. Les données d'état de livraison, d'arrivée et de départ sont mappées sur le modèle de livraison interne de PAR. Ainsi, les champs orderId, runId, location, status, timestamp, employee, tip et les champs associés à la livraison, au trajet et au coursier restent exacts, même si les noms ou la structure des champs PJI diffèrent. Le traitement des arrivées et départs en aval utilise les champs normalisés. Cette modification de contrat et de mappage concerne les intégrations sans composant d'éditeur de paramètres ; assurez-vous que les données correspondent au schéma convenu pour votre environnement. |
| AS1-3764 | Les champs « pourboire » et « kilométrage » sont désormais inclus dans le schéma d'enregistrement. Le schéma d'événement d'enregistrement publié contient officiellement les données relatives au pourboire et au kilométrage (distance). PAR utilise et transmet ces champs avec l'événement d'enregistrement afin que les systèmes en aval (accumulateur de kilométrage et PAR) puissent calculer la rémunération du chauffeur sans attendre un contrat supplémentaire. Le client et Deliverect envoient le pourboire et le kilométrage lors de l'enregistrement, lorsque ces informations sont disponibles. |
Modifications apportées à WSDL (0.2.145 → 0.2.148)
Les points de terminaison des événements de livraison, l'allocation de trésorerie lors de l'ajout d'un paiement et l'en-tête Idempotency-Key sont des ajouts REST sur le chemin d'API Cloud/Externe et ne sont pas représentés dans les fichiers WSDL publiés sur le CDN. AS1-3750 introduit le type ApplyCashPaymentInfo dans le contrat de sérialisation ApplyPayment utilisé entre l'API et le registre. Aucune modification n'a été identifiée dans les fichiers WSDL publiés sur le CDN pour les services SOAP couverts par cette version : les correctifs AS1-3753, AS1-3755 et AS1-3800 modifient uniquement le contenu des réponses et les codes de résultat ; par conséquent, les clients SOAP utilisant des proxys générés automatiquement ne nécessitent aucune régénération pour cette version.
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 masqué de la carte cadeau, conformément à la norme AS1-3581) ; FutureDateOrderStatus (statut FDO : En attente, Traitée ou Clôturée, conformément aux normes POG-3254/AS1-3493) ; et AccountNumber on OrderGiftCard (quatre derniers chiffres de la carte cadeau, conformément à la norme AS1-3581). Les intégrateurs utilisant les opérations SOAP GetOrders ou GetFutureDateOrders doivent régénérer les proxys ou ajouter manuellement ces champs à leurs contrats. |
| HouseAccounts.xml | Aucun changement | Aucune modification relative à l'API dans cette version. |
| Kitchen.xml | Aucun changement | Aucune modification relative à l'API dans cette version. |
| Labor2.xml | Aucun changement | Aucune modification relative à l'API dans cette version. |
| Ordering.xml | Aucun changement | Aucune modification relative à l'API dans cette version. |
| Settings.xml (v1) | Aucun changement | Aucune modification relative à 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'ID du conteneur/mappage), et NON à l'ItemId du menu. |
| Prix / prix | Requis pour les modificateurs avec ModifierPriceMethod = ModifierPrice. |
| Nom du groupe (SOAP) | Accepté au format XML mais non stocké. Omis pour plus de clarté. |
| Nom de l'article / Prix d'origine | Non stocké ; ne fait pas partie du schéma REST. |
| Sauvegarder la sémantique | Delta uniquement — n'envoie que les éléments modifiés du groupe de modificateurs, et non le groupe complet. |
| Créer ou mettre à jour | Utilisez un identifiant négatif pour les nouveaux enregistrements ; un identifiant positif pour les enregistrements existants. |
API Build 0.2.143 — Nouveautés
Nouvelles fonctionnalités
| IDENTIFIANT | Description |
|---|---|
| AS1-3581 | Les 4 derniers chiffres des cartes-cadeaux sont désormais renvoyés par GetOrders. L'API GetOrders (REST et SOAP) renvoie désormais les 4 derniers chiffres du numéro de compte d'une carte-cadeau dans un nouveau champ AccountNumber de l'objet OrderGiftCard. Ce champ est masqué pour des raisons de sécurité, conformément à la gestion des numéros de cartes de paiement dans le reste de l'API. La documentation du portail API et le schéma OpenAPI ont été mis à jour en conséquence. Remarque : AccountNumber est renseigné uniquement pour les articles 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 via l'API (intégration PMP/RSI). L'API SavePromotions permet désormais de modifier le prix et la disponibilité des promotions grâce à des intégrations externes de gestion des prix telles que RSI/PMP. Deux nouveaux points de terminaison REST sont désormais disponibles pour la gestion des promotions : • POST /settings/v1/promotions – Crée une ou plusieurs nouvelles promotions. Renvoie un code HTTP 201 avec les identifiants attribués. • PUT /settings/v1/promotions – Met à jour les promotions existantes. Renvoie un code HTTP 200. Une nouvelle opération SOAP SavePromotions est également disponible, prenant en charge les mêmes flux de travail de création/mise à jour. Types de promotions prises en charge : BOGO, carte-cadeau, coupon, réduction de commande et combo. Les promotions peuvent inclure des configurations complexes telles que des conditions d'éligibilité, des articles à prix réduit, des composants combinés, des destinations, des sections, des articles/groupes éligibles et des champs personnalisés — tous dotés d'identifiants automatiquement attribués lors de leur création. Les modifications peuvent être publiées immédiatement ou via des ensembles de modifications. Les champs obsolètes ont été clairement indiqués dans le contrat de l'API afin d'éviter que les intégrateurs n'utilisent des propriétés dépréciées. Notes • Lors de la création de promotions via 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 volontairement certaines logiques de validation ; les intégrateurs doivent donc s'assurer de l'exactitude des données avant de les soumettre. • Le type de données MarketingCampaigns doit être explicitement demandé dans l'appel GetSettings ; il n'est pas renvoyé par défaut. • Plusieurs champs obsolètes sont désormais marqués comme dépréciés dans le schéma de l'API. Les intégrateurs doivent les examiner et les abandonner lors de leurs futures intégrations. |
| AS1-3495, AS1-3546, AS1-3557, AS1-3578 | Ajout d'une tarification par groupe de modificateurs spécifique aux DSP. Les API SavePriceChange et GetPriceChange prennent désormais en charge une tarification alternative par groupe de modificateurs et par partenaire de livraison (DSP). Un nouveau champ de type 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 modifications de prix des articles) et ModifierGroupItemPriceChange (identifiant de l'article et prix mis à jour). Le service de commande applique désormais la logique de tarification spécifique aux DSP lorsque la méthode de prix d'un article d'un groupe de modificateurs est définie sur 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 lorsque la tarification par groupe de modificateurs spécifique aux DSP est nécessaire. Mettez à jour les collections Postman et les suites SoapUI en conséquence. |
| AS1-3583 | La fonction GetSettings renvoie désormais les données de campagne marketing pour l'enregistrement des promotions. La réponse de l'API GetSettings inclut maintenant les champs de données de campagne marketing, dont la structure et les noms correspondent à ceux affichés par l'interface utilisateur de l'éditeur de paramètres. Ces données sont obligatoires pour l'API SavePromotion : les attributs de campagne renvoyés par GetSettings doivent être fournis lors de la création ou de la modification d'une promotion via l'API. Sans cette correction, la validation des opérations d'enregistrement des promotions échouait. |
| POG-3254 | Le statut des commandes à livraison future (FDO) est désormais inclus dans l'historique des données de commande. Ce statut (En attente / Traité / Clôturé) est maintenant accessible via l'API cloud pour les intégrateurs back-office. Auparavant, bien que disponible dans le modèle de données historiques (Order
|
| MPP-37 | Améliorations des API CalculateOrder et SubmitOrder. Les deux API prennent désormais en charge les remises en pourcentage et à montant fixe via les champs discountPercentage et discountAmount, appliquées au sous-total avant taxes. L'API SubmitOrder a été enrichie de trois fonctionnalités supplémentaires : un champ employeeId permettant d'associer les commandes à un employé spécifique (gestion des pourboires, gestion de caisse et mise en commun des pourboires) ; des métadonnées de paiement étendues, incluant CardType, CardNumber (masqué aux 4 derniers chiffres), TransactionNumber et TransactionIdentifier ; et la prise en charge des frais supplémentaires ajoutés automatiquement. Les fonctionnalités existantes de CalculateOrder et SubmitOrder restent inchangées. |