Create a service

This endpoint enables the creation of a new service within the business.

POST /api/v2/businesses/{businessId}/services

Below is a detailed explanation of each field that can be included in the request body. Some of them are required for the request to be processed successfully.

Required fields are marked with an asterisk (*).

Request body

JSON Analysis 
{
  "newServiceOuterId": "string",
  "newServiceName": "string",
  "copyFromServiceOuterId": "string",
  "timeZone": "string",
  "firstDayOfWeek": 1,
  "parentOuterId": "string"
}
Details

  • newServiceOuterId: external identifier of the new service. Although not mandatory, it is recommended to define it so it can be used in future integration operations. It must be unique within the business.

  • newServiceName*: name of the new service.

  • copyFromServiceOuterId: external identifier of the service to be used as a reference if a copy is to be made.

  • timeZone*: time zone in which the service will be created. It is mandatory to provide a TZ identifier from this list.

  • firstDayOfWeek*: first day of the week. It is mandatory to include a value from 1 (Monday) to 7 (Sunday).

  • parentOuterId*: external identifier of the node to which the service will be linked.

Request example

After analyzing the different fields, here is an example of the request body:

{
    "newServiceOuterId": "1327",
    "newServiceName": "STORE 1327",
    "timeZone": "Africa/Freetown",
    "firstDayOfWeek": 1,
    "copyFromServiceOuterId": "0001",
    "parentOuterId": "PN"
}

Considerations

If the copyFromServiceOuterId field is provided, all dependent entities of the referenced service will be copied: products, locations, zones, employee limits, needs templates, employee distribution, service times, service parameters, regulations, employee roles, etc.

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

400 Bad Request

newServiceName must not be empty

The newServiceName field is missing. The literal travels in the cause field; the message field also adds the name of the affected parameter in square brackets.

Invalid TimeZone

The timeZone field is missing or is not a valid time zone identifier. Same field nuance as the previous row.

Invalid firstDayOfWeek. Must be an integer between 1 (monday) and 7 (sunday)

The firstDayOfWeek field is missing or does not have a value between 1 and 7. Same field nuance as the previous rows.

parentOuterId must not be empty

The parentOuterId field is missing. Same field nuance as the previous rows.

-

The request body is not valid JSON.

404 Not Found

Node not found

The parentOuterId provided does not match any node configured in the business.

Node not found

The copyFromServiceOuterId provided does not match any service configured in the business.

409 Conflict

ID already exists

The newServiceOuterId provided already exists in the business. It is recommended to use a different identifier.

-

A conflict occurred while creating the service. It is recommended to check that the data sent does not violate any integrity constraint.

Useful links

What is a service?

What is a node?