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.

Filter and navigate through sales data

Start from: The Analytics module.

Select Sales from the main menu.

Select the Parameters button.

In Analysis, set:
- If you want to visualize Sales as Net Sales or Gross Sales.
- If you want to see Traffic by Tickets or Guests.
- The Comparison Scenario of the analytics, can be Comparable vs Previous Year, Actual vs Previous Year, Actual vs Budget, Budget vs Previous Year.
- The Reference Year, which can be any in the last five (5) years.
- If you want to see Averaged Amounts, whether daily, weekly, monthly or annual.

In Time Period, set:
- The Time period you want to see. You can see the last day, week, month, year or a specific date range that you select.
- If you want to exclude or include specific days of the week.
- If you want to include Holidays, Holiday Eves, Events and Exclude non-representative dates.
- If you want to filter by Weather or Temperatures.

In Sales Type and Periods, set:
- If you want to see Individual sales types or Groups of sales types. Then, select the specific type or group of types from the dropdown.
- If you want to see one or all Sales Periods.

In Others, you can set parameters such as data source, currencies, percentage variations in local currency or ignore days without sales. At this point, you will establish if the data will come from the POS or from the Cash Sheet.
Once the parameterization is completed, select Accept to save it OR Cancel to discard it.

Back on the Sales Analytics screen, select Filter by Center.

In this window, you will be able to select the specific center or centers for which you want to visualize the data.

Once the centers are selected, the Sales Analytics screen will show you a list of the selected centers with their respective data. On this screen you will be able to get an overview of actual sales, previous year sales (based on the comparable year), and the variation both in percentages and amounts.

This parameterization can be saved later as a Scenario, which will allow you to present it permanently on a Dashboard or make a comparison with another scenario.

Navigate through sales

Once you deploy the data, you will be able to navigate through the sales screen using different tools available in the panel.

To learn more, see Navigate using views and levels in Analytics.

Manage budgets from the Analytics sales tool

Start from: The Analytics module.

Select Sales from the main menu.

Configure the Sales screen to display the data you need OR choose an existing Scenario where you use a Budget as a Comparison Scenario.

To learn more about Sales configuration, see Filter and navigate through Sales data.

Select from the dropdown the Budget you want to view and manage.

Select Accept to see the configuration result on the Sales screen.

Select the Budget button.

A Sales Budget modal will open where you can manage four blocks:

Budget Scope

In this section, you will set the general budget data.

Select the budget to manage from the Budget* dropdown.
Select the Data Source for that budget. It can be POS or Cash Sheet.

Select the Center* for which you will configure that budget.

Set the From* and To* dates that will govern that budget.

Select the Sale Types included in that budget. Use the Individual or Group switch to set whether it will be a single group of sale types or several.

Select the Sale Periods established for the budget.

Notes: Fields marked with * are mandatory.

Reference Data

In this block, you will set whether the budget will use reference data from another center, date, or source.

In Reference Center, select whether you want to use the same center in a previous year or another specific center.

Select whether you want to use Historical Data or another Budget as Reference Source.

In Reference Date, you can set the specific time range you will use as reference for your budget. It can be the same day of the week in a previous week, same date in a previous year, or a comparable day in a previous year.

Depending on the parameter you use in Reference Date, you can select the Previous Year or Previous Week you will use as reference.

Select whether you will Use budgeted data as reference for future dates. If you do, then set the Budget for Future Dates.

Projection Method and Assumptions

In this section, you can set how you want to project the budget and whether you want to establish variations to the references you have set.

Select the Projection Method to use. It can be Sales, Tickets and Average Ticket, Customers and Average Ticket per Customer, or Trend.

In Sales Assumptions, set a Percentage variation, Specific variation or Particular value. You can set a single value for All days or a different one By days of the week.

Set a reference parameter for Tickets and Customers. It can be Same growth as in Sales, Same number of Tickets/Customers as in Reference Date, Same growth as Tickets/Customers and Average ticket per customer.

Distribution by Sale Types and Periods

In this block you can set specific budget distributions by periods and sale types.

Choose whether you want to make the distribution Based on Reference Data or not.

Choose whether you want to Show all Sale Types or not.

You can Load a base distribution by choosing a specific date from the reference data.

Set the distributions in percentage. In the table, rows correspond to sale types and columns to periods.

Keep in mind that the sum of all distributions must equal 100%. You can view this in the Total row.

Once you complete each of the blocks, select Accept to save changes OR Cancel to discard them.

Submit real-time sales via API

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=<your_username>
password=<your_password>
client_id=wf_wap_tp
client_secret=<shared_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.

Configure outlier dates to improve accuracy

Start from: The Analytics Dashboard.

Navigate to Configuration > Outlier Dates.

Select the Year and the Site for which you want to configure non-representative dates. These dates are set on the current year's calendar but are used to adjust the sales budget for the following year.

Example: If you mark dates in 2024 as outliers, they will not influence the sales budget calculations when 2024 is used as the historical reference for 2025.

Review system-suggested outliers

Days outlined in red are Potentially Non-Representative Days. These are flagged automatically based on the sensitivity setting and variations detected in the data source (POS or cash sheet).

Adjust the sensitivity using the slider control to detect fewer or more outliers.

Manually mark non-representative days

Click on any date to mark it as Non-Representative.
The selected day will appear in yellow.
Add a comment to justify the selection (e.g., “Bank holiday” or “Local event”).

Select Accept to confirm or Cancel to discard.

Generate a report

To get a global overview of all configured outlier dates for a specific site:

Select Report at the top of the grid.
A PDF summary will be generated listing all the dates marked as Non-Representative for the selected site and year. This report helps provide visibility and traceability for forecasting decisions across your organisation.

Create and manage sales and financial budgets

Start from: The Analytics module.

Navigate to Configuration > Budgets.

Select the Budgets ? button.

Interfaz de usuario gráfica, Aplicación, Tabla Descripción generada automáticamente con confianza media

Enter the name of the budget.
Select the + button to create it.

Interfaz de usuario gráfica, Aplicación Descripción generada automáticamente

Once created, find the new budget in the table and flip the switch in the row of each role to enable the roles that will have access to it.
Permission levels include:
- View – Users can access budget details but cannot make changes.
- Close – Users can lock budgets once finalized.

Captura de pantalla de computadora Descripción generada automáticamente

Edit and rename budgets

Select the Budgets ? button.
Locate the existing budget and select Edit.
Rename the budget and press Accept.

Delete budgets

Select the Budgets ? button.
Locate the existing budget and select Delete.
Select Delete again in the confirmation window.

Configure sales forecast

Start from: The Workforce module.

Select Scheduling > Scheduler 2.0 from the main menu.

Once in the scheduler screen, select the < button to open the favourite shifts catalog and sequences in the side panel.

Escala de tiempo Descripción generada automáticamente con confianza baja

The catalog is divided into two tabs: one for favourite shifts and the other for sequences. Both tabs work in the same way.
Select the appropriate tab.

Interfaz de usuario gráfica, Texto, Aplicación Descripción generada automáticamente

Enter the name of the shift or sequence in the Search field.
Indicate how many times the assignment of the selected shift or sequence is to be repeated.

Notes: This functionality is very useful when you must make the same assignment for an employee repeatedly on consecutive days.

Select the shift or sequence from the list (the selection is marked with a blue ball).

Interfaz de usuario gráfica, Aplicación, Teams Descripción generada automáticamente

Select in the grid the day and employee to whom you will assign the shift or sequence.

Tabla Descripción generada automáticamente con confianza media

Notes: As long as the catalog panel remains open, the shift or sequence will be assigned the indicated number of times starting from the day and for the employee you have selected in the grid.

To create new favourite shifts and sequences, see Set up favourite shifts and sequences.

To change or delete existing favourite shifts and sequences, see Manage favourite shifts and sequences.

FAQs

I am planning for a week, and I have selected a shift to be assigned for 10 days in a row. When I go to look at the following week the days over the last week are not with the favourite shift assigned, why?

The favourite shifts, when we apply a repetition, are only assigned until it reaches the indicated number of repetitions or the last day of the selected period in parameters, whichever conditions that is met first.

To assign a shift 10 times we must have the 10 days we want to assign loaded in the planning.

I've assigned a sequence with time off and it gives me an error, why?

This is because we don't know the timetable of the time off to apply until we assign it to an employee and it can happen that the employee's time off's center timetable, overlaps with other shifts of the same sequence or other shifts already assigned to the employee for the same day where the time off corresponds.

I have assigned a shift or a sequence, but it gives me an error indicating that it cannot be assigned because the day for that center is not in process, why?

This is because the center that has the associated favourite shift or sequence for the day where we want to assign this favourite shift is in a different status to "On Going" and therefore cannot be edited.

Manage sales budgets

Start from: The Analytics module.

Select Sales Budgets > Budgets from the main menu.

Project or modify a sales budget

Select the Center where the budget you wish to modify is located.
Select the Budget to be modified.
Select the Year of the budget.
Select the Update button to load the budget data.

Define and adjust budget parameters

Once the budget is loaded, users can adjust different variables:
- Traffic (Customers or Tickets): Modify the projected number of customers or transactions.
- Adjusted Budgets by Sales Type and Period: Customize projections for each sales type (e.g., dine-in, takeout) and selected time periods.
- Distribution (%): Define how sales are allocated across different periods and sales types using historical percentages or custom allocations.

Set the reference data for the budget

Select the Data Source, Method, Center and Reference Year to be used to modify the budget.
Select a Month or Year depending on whether you are modifying an Annual or Monthly budget.
Under Non-Representative Dates select what to do with the dates you have set as non-representative.
Selecting the Use Budget As Reference For Future Dates checkbox will use the reference year's sales budget for future days where there are no actual sales yet.

Una captura de pantalla de una computadora Descripción generada automáticamente

Choose the budget method

Once you have selected whether to modify the Budget by Year or Month, on the screen that appears, you’ll be prompted to select a calculation method:
- Sales Budget: Modify sales figures directly.
- Ticket Budget and Average Ticket: Adjust projections based on ticket count and average spending per ticket
- Customer Budget and Average Net Ticket per Customer: Modify budgets based on expected customer volume and average spending per customer.
- Trend Analysis: Project budgets using historical data trends.
Within this screen, you can apply percentage variations to modify the budget against reference data. If set to zero, the budget remains unchanged.

Notes: The Lock Table button causes the data typed in a cell to be repeated in the entire row, Unlock Table allows you to adjust cell by cell, and Clear allows you to delete all data in the table and return it to zero.

Once you have made the settings in this table, select Accept to save the changes OR Cancel to discard them.

Interfaz de usuario gráfica Descripción generada automáticamente con confianza baja
Notes: To make a budget adjustment, you must make sure that the budget has not been Closed. If it is closed, it must be reopened for modifications.

Export a sales budget

In the Budget Sales screen, select the Center where the budget you wish to modify is configured.
Select the Budget to be modified.
Select the Year of the budget.
Select the Update button to load the budget data.

Select the Excel button.
In the next window, choose the Template with budgeted data.

The resulting file will be an .XLS file with the budget data.

Tabla Descripción generada automáticamente con confianza media

Understand sales types and periods

Start from: The Analytics module.

Navigate to Configuration > POS - Configuration.

In the POS - Configuration screen, you will find two tabs with their respective listings:

Sales Types

Sales types, also known as sales channels, are all the channels through which sales are made in a business center. Each type of sale has a code, Category, Traffic, and groups assigned to it to facilitate its location and use in the system.

These channels are previously configured in the POS and GIR extracts them from that source for use in the system's budget configuration. To edit parameters such as the name and code of the Sales Types, it is recommended to go directly to the POS configuration.

Pantalla de computadora Descripción generada automáticamente con confianza media

Sales Periods

Sales Periods are the time frames in which sales are made at the work center. Each period has a code and a category to facilitate its location and use in the system.

The periods are predefined in GIR and comprise four time periods: Breakfast (0), Lunch (1), PM (2), Dinner (3). The names and parameters of these periods can be changed at the user's request.

Interfaz de usuario gráfica, Aplicación Descripción generada automáticamente

Track the performance of products in my business

Start from: The Analytics dashboard.

Select Product Mix from the main menu.

Parameterize the data

Select the Parameters button to configure data settings. In the lateral window, you will find four parameter groups:
- Analysis
  - The Analysis dropdown helps you select the type of analysis, that can be by Product, by Business Units, or by Employee. In this particular case, you must select Product to display the products.
  - Select the specific Sales Type to include in the analysis. It can be Net Sales or Gross Sales.
- Period
  - Select the Period you want to display. It can be Yesterday, Week to Date, Month to Date, Year to Date, etc.
  - Select specific Weekdays if needed.
  - Select if you want to include specific Bank Holidays, Holiday Eves, or Events.
  - You can also select Meteorology parameters.
- Products
  - Narrow down the product selection by Family, Subfamily, or specific Products.
- Others
  - Set up the Currency to be shown in the grid.
Select Accept to apply your parameters and update the displayed data.

Key metrics

The Data grid will now show you the data broken down into three key metrics:
- Net/Gross Sales: Total sales of each product, sorted by families and sub-families.
- Quantity Sold: Number of products sold, including the average per day or per customer.
- Avg Price & TCOGS: Percentage that each product or category represents within a broader group.
- Ticketshare: Percentage of total sales tickets that include a particular product.

You can also switch to the Charts tab to visualize this information graphically. You can select different types of graphics, analysis, and ordinations according to your preferences.

You can refine the results of the visible data by filtering the information by specific Business Units. For more information about this filtering, see Use the Business Unit Tree Selector.

Quick Start

Authentication

Import Workflow

Endpoint Reference

Error Handling

Navigate through sales

Budget Scope

Reference Data

Projection Method and Assumptions

Distribution by Sale Types and Periods

Real-time Sales API

Include the token in requests

Submit real-time sales

Parameters / payload fields

Check submitted sales

Error handling

Review system-suggested outliers

Manually mark non-representative days

Generate a report

Edit and rename budgets

Delete budgets

FAQs

I am planning for a week, and I have selected a shift to be assigned for 10 days in a row. When I go to look at the following week the days over the last week are not with the favourite shift assigned, why?

I've assigned a sequence with time off and it gives me an error, why?

I have assigned a shift or a sequence, but it gives me an error indicating that it cannot be assigned because the day for that center is not in process, why?

Project or modify a sales budget

Define and adjust budget parameters

Set the reference data for the budget

Choose the budget method

Export a sales budget

Sales Types

Sales Periods

Parameterize the data

Analysis

Period

Products

Others

Key metrics