Workforce Sales API

As a developer integrating with Mapal OS, you can use the Workforce Sales API to manage, import, and retrieve sales data efficiently. This guide introduces how to authenticate, start importing, and retrieve sales, with a quick start flow and full endpoint reference.

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:

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.

Originally published at https://help.mapal-os.com/analytics/sales/workforce-sales-api/