API des ventes Workforce

En tant que développeur intégrant Mapal OS, vous pouvez utiliser l'API Ventes Workforce pour gérer, importer et récupérer efficacement les données de ventes. Ce guide présente comment s'authentifier, commencer à importer et récupérer les ventes, avec un flux de démarrage rapide et une référence complète des points de terminaiso

L'API Ventes est un service RESTful pour une intégration sécurisée de serveur à serveur. Elle vous permet de :

• Récupérer des données : Obtenir les ventes nettes et brutes filtrées par unité et plage de dates.
• Soumettre des données : Importer des ventes détaillées, horaires et totales.
• Intégration sécurisée : Toutes les communications sont chiffrées via SSL/TLS et authentifiées avec des jetons JWT.

Démarrage rapide

Voici le flux de travail typique en cinq étapes :

Authentification

L'API utilise JWT (JSON Web Token) pour l'authentification.

• Demandez un jeton avec vos identifiants client.
  • URL: https://login.mapal-os.com/connect/token
  • grant_type: password.
  • client_id: wf_wap_tp.
  • client_secret: provided by Mapal OS
• Utilisez le jeton dans chaque requête :
• Authorization: Bearer {access_token}
• Expiration du jeton : Les jetons expirent (par défaut : 3600 secondes). Rafraîchissez ou régénérez si nécessaire.

Flux d'importation

• Authentification : générer un jeton JWT.
• Démarrer une session d'importation : crée une session pour un jour ouvré spécifique.
  • Les données de ventes précédentes pour ce jour seront remplacées.
  • Les sessions doivent être remplies séquentiellement (pas de lacunes dans les jours ouvrés).
• Soumettre les données de ventes : envoyez les données vers un ou plusieurs points de terminaison :
  • Ventes détaillées
  • Ventes totales
  • Ventes par demi-heure
  • Mix produit
  • Inventaire
  • Ventes TVA
  • …et plus encore (voir la liste des points de terminaison).
• Terminer la session d'importation : finaliser l'importation.
• Visualiser les données importées : dans Analytics > Ventes dans Mapal OS.

Référence des points de terminaison

Tous les points de terminaison sont sous : https://api.workforce.mapal-os.com/sales

Récupération des ventes

• Ventes nettes : GET /api /v1/business-unit/{unitId}/net-sales?start=yyyy-MM-dd&end=yyyy-MM-dd
• Ventes brutes : GET /api /v1/business-unit/{unitId}/gross-sales?start=yyyy-MM-dd&end=yyyy-MM-dd

Flux d'importation

• Démarrer une session d'importation : POST /api /v1/import
• Terminer une session d'importation : POST /api /v1/import/{importId}/finish

Points de terminaison d'importation

• POST /api/v1/import/{importId}/detailed-sales
• POST /api/v1/import/{importId}/total-sales
• POST /api/v1/import/{importId}/half-hourly-sales
• POST /api/v1/import/{importId}/total-half-hourly-sales
• POST /api/v1/import/{importId}/product-mix
• POST /api/v1/import/{importId}/special-tickets
• POST /api/v1/import/{importId}/payment-method-sales
• POST /api/v1/import/{importId}/average-ticket-duration
• POST /api/v1/import/{importId}/inventory
• POST /api/v1/import/{importId}/vat-sales

Gestion des erreurs

• 400 Bad Request : vérifiez les paramètres ou le corps JSON.
• 401 Unauthorized : rafraîchissez ou régénérez le jeton.
• 404 Not Found : unitId invalide ou configuration du tenant incorrecte.
• 500 Internal Server Error : réessayez ou contactez le support.

Originally published at https://help.mapal-os.com/fr/analytics-fr/ventes/api-des-ventes-workforce/