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 :
1. Générer un jeton JWT
cur l -X POST https://login.mapal-os.com/connect/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=password&username=<your_username>&password=<your_password>&client_id=wf_wap_tp&client_secret=<shared_client_secret> "
2. Démarrer une session d'importation
cur l -X POST https://api.workforce.mapal-os.com/sales/api/v1/import \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{ "unitId": 9, "businessDay": "2025-02-06" }'
3. Importer les données de ventes (exemple : ventes totales)
cur l -X POST https://api.workforce.mapal-os.com/sales/api/v1/import/1/total-sales \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{ "TotalSales": [ { "CurrencyId": "EUR", "NetSales": 250, "GrossSales": 270, "NumChecks": 2, "NumGuests": 3, "SalesTypeId": "TAKE", "SalesType": "Takeaway" } ] }'
4. Terminer la session d'importation
cur l -X POST https://api.workforce.mapal-os.com/sales/api/v1/import/1/finish \
-H "Authorization: Bearer <token> "
5. Récupérer les données de ventes
cur l -X GET "https://api.workforce.mapal-os.com/sales/api/v1/business-unit/9/net-sales?start=2025-02-06&end=2025-02-06" \
-H "Authorization: Bearer <token> "
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.
