Workforce Sales API

The Sales API is a RESTful service for secure server-to-server integration.
It allows you to:

• Retrieve data: Get net and gross sales filtered by unit and date range.
• Submit data: Import detailed, hourly, and total sales.
• Secure integration: All communication is encrypted via SSL/TLS and authenticated with JWT tokens.

Quick Start

Here’s the typical workflow in five steps:

1. Generate a JWT token

curl -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. Start an import session

curl -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. Import sales data (example: total sales)

curl -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. Finish the import session

curl -X POST https://api.workforce.mapal-os.com/sales/api/v1/import/1/finish \
-H "Authorization: Bearer <token> "

5. Retrieve sales data

curl -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> "

Authentication

The API uses JWT (JSON Web Token) for authentication.

• Request a token with your client credentials.
  • URL: https://login.mapal-os.com/connect/token
  • grant_type: password
  • client_id: wf_wap_tp
  • client_secret: provided by Mapal OS
• Use the token in every request:
  Authorization: Bearer {access_token}
• Token expiry: Tokens expire (default: 3600 seconds). Refresh or regenerate when needed.

Import Workflow

• Authenticate: generate JWT token.
• Start import session: creates a session for a specific business day.
  • Previous sales data for that day will be replaced.
  • Sessions must be filled sequentially (no gaps in business days).
• Submit sales data: send data to one or more endpoints:
  • Detailed sales
  • Total sales
  • Half-hourly sales
  • Product mix
  • Inventory
  • VAT sales
  • …and more (see endpoint list).
• Finish import session: finalise the import.
• View imported data: inside Analytics > Sales in Mapal OS.

Endpoint Reference

All endpoints are under: https://api.workforce.mapal-os.com/sales

Sales Retrieval

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

Import Workflow

• Start import session: POST /api/v1/import
• Finish import session: POST /api/v1/import/{importId}/finish

Import Endpoints

• 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

Error Handling

• 400 Bad Request: check parameters or JSON body.
• 401 Unauthorized: refresh or regenerate token.
• 404 Not Found: invalid unitId or tenant config.
• 500 Internal Server Error: retry or contact support.