Submit real-time sales via API

As a developer integrating your system with Mapal OS, you can submit real-time sales via API so figures are instantly available for reporting and forecasting. The Real-time sales API is RESTful and secured with HTTPS and JWT.

Start from: Your server-to-server integration (API client).

Real-time Sales API

The Real-time Sales API is a RESTful service for submitting live sales data securely.

Key Benefits:

• Immediate updates to sales figures.
• Secure server-to-server connection (HTTPS + JWT).
• Supports flexible filtering by business unit and business day.

Generate a JWT token

POST to: https://login.mapal-os.com/connect/token

Parameters:

• grant_type=password

• username=

• password=

• client_id=wf_wap_tp

• client_secret= (contact Customer Support to obtain)

Successful response includes: access_token, expires_in, token_type, refresh_token, scope.

Include the token in requests

• Add header: Authorization: Bearer {access_token}

Submit real-time sales

• Base domain: https://api.workforce.mapal-os.com/sales
• Endpoint path: /api/v1/business-unit/{unitId}/real-time-sales
• Method: GET (if your OpenAPI specification shows a different method, follow the specification)

Parameters / payload fields

• unitId (route, integer)

• businessDay (string, yyyy-MM-dd)

• realTimeSales (array of objects):

  • currencyId (string)

  • salesTypeId (string)

  • timeSlotStart (string, date-time)

  • netSales (decimal)

  • grossSales (decimal)

  • numChecks (integer)

  • numGuests (integer)

Check submitted sales

• Navigate to Analytics > Sales in Mapal OS.

Notes:

• All requests must use HTTPS.

• Tokens expire (expires_in) and must be regenerated.

• Tokens can be revoked if compromised.

Error handling

• 400 Bad Request: Invalid unit ID; business day mismatch; currency or sales type mismatch; invalid time slots.

• 401 Unauthorized: Invalid or missing token.

• 404 Not Found: Tenant or tenant configuration not found.

• 500 Internal Server Error.

---

Originally published at https://help.mapal-os.com/analytics/sales/submit-real-time-sales-via-api/