Adding a business
Adding a business
Contents
- Overview
- Version-specific information
- Permissions and Authentication
- Headers
- HTTP Parameters
- Example response JSON
- Possible error responses
Overview
- Call name: add-business
- Endpoint URL: https://{API hostname}/internal/add-business
- Request methods: POST
- Request Content-Type: multipart/form-data or application/x-www-form-urlencoded or application/json
- Response Content-Type: application/json
- Auth required: yes
In Spaaza terminology, a "business" is a branch of a retailer (a "chain"). This API call adds a new business.
Version-specific information
The following version-specific changes apply to this endpoint. See the versioning page for more details.
| Version | Change details |
|---|---|
| N/A | N/A |
Permissions and Authentication
This API call requires a valid Spaaza session. See the authentication page for more details. The session can be as follows:
- Admin authentication: The performing user needs to be logged in and have
write accessto the chain to which the user is connected.
Headers
The following headers can/must be passed to the API call:
| Parameter | Description |
|---|---|
| N/A | N/A |
HTTP Parameters
The following HTTP parameters can be passed to the API:
| Parameter | Description |
|---|---|
| chain_id | (integer, mandatory) The chain_id of the chain to which the business belongs. |
| address_1 | (string, optional, max 255 chars) The first line of the business address. |
| address_2 | (string, optional, max 255 chars) The second line of the business address. |
| address_3 | (string, optional, max 255 chars) The third line of the business address. |
| format | (string, optional, max 64 chars) The store "format" of the business. |
| countrycode | (string, optional, max 2 chars) The ISO ALPHA-2 2-letter country code of the business. |
| format | (string, optional, max 64 chars) This is used to set the business_format of a business. |
| google_place_id | (string, optional, max 1024 chars) The google_place_id of the store/business. |
| image_url | (string, optional, max 512 chars) The url link to the businesses image/logo. |
| is_shut_down | (boolean, optional) Whether the business is administratively shut down true/false. |
| latitude | (float) The latitude of the business in decimal degrees. |
| longitude | (float) The longitude of the business in decimal degrees. |
| name | (string, mandatory, max 255 chars) The name of the business. |
| opening_times | (string, optional, max 2048 chars) The opening times of the business in JSON format. Contact Spaaza for more details. |
| owner_code | (string, recommended, max 64 chars) The retailer owner_code for the store. This value will also be used as the branch_business_owner_code in add-basket and get-basket-price requests. |
| postalcode | (string, optional, max 20 chars) The postalcode of the business. |
| region | (string, optional, max 255 chars) The region or country of the business. |
| review_url | (string, optional, max 255 chars) The url link to the review business page. |
| towncity | (string, optional, max 255 chars) The postal city of the business. |
| update_if_exists* | (boolean) used to update an alter business using add-business - see note below. |
*Updating a existing business using add-business
It is possible to update an existing business using the add-business endpoint. To do this, you need to pass the update_if_exists parameter as true and the business_id or owner_code parameter must be passed to identify an existing business. |
Example response JSON
The endpoint returns JSON showing the details associated with the business. An example response is shown below:
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"business": {
"address_1": "Herengracht 504",
"address_2": "Foo",
"address_3": "Bar",
"business_format": "Metro",
"chain_id": 1743,
"created_date":"2024-04-03T12:43:54+00:00",
"countrycode": "NL",
"deleted": false,
"deleted_by": null,
"email_address": "ops@spaaza.com",
"format": "Metro",
"google_place_id": null,
"id": 1383,
"image_url": "https://media.licdn.com/dms/image/C4D0BAQEN6wx-nP_Crg/company-logo_400_400/0?e=1578528000&v=beta&t=1qKTWg0qbIJMydHHG02YPhD8N4LONyW5Rp06wn5DvN0",
"is_shut_down": false,
"last_modified_date":"2024-04-03T12:43:54+00:00",
"latitude": "52.37021570",
"longitude": "1.89516789",
"name": "ACME Inc",
"opening_times": "{\"monday\": {\"open\": \"11:00\",\"close\": \"18:00\" }, \"tuesday\": { \"open\": \"09:30\", \"close\": \"18:00\" }, \"wednesday\": { \"open\": \"09:30\", \"close\": \"18:00\" }, \"thursday\": { \"open\": \"09:30\", \"close\": \"18:00\" }, \"friday\": { \"open\": \"09:30\", \"close\": \"21:00\" }, \"saturday\": { \"open\": \"09:30\", \"close\": \"17:00\" }, \"sunday\": { \"open\": \"Elke laatste zondag van de maand\", \"close\": \"12:00-17:00\" }, \"special_hours\": [ { \"date\": \"23\/02\/2020\", \"open\": \"12:00\", \"close\": \"17:00\", \"reason\": \"Laatste zondag van de maand\" }, { \"date\": \"23\/02\/2020\", \"open\": \"-\", \"close\": \"-\", \"reason\": \"Carnaval\" } ] }",
"owner_code": "10001",
"phone_number": "0124141",
"postalcode": "1017 CB",
"programme_opted_in": true,
"region": "Noord Holland",
"towncity": "Amsterdam",
"review_url" : "https://g.page/spaaza/review",
"type": "business",
"website_url": "https://www.spaaza.com"
},
"result_type": "add-business"
}
}
Possible error responses
| Code | Name | Description | HTTP Status |
|---|---|---|---|
| 3 | http_vars_missing | Required parameter chain_id or name is missing | 400 |
| 6 | no_valid_session | No valid session key provided or session has expired | 401 |
| 13 | http_request_method_non_POST_not_allowed | Only HTTP POST allowed for this API call | 405 |
| 68 | permission_denied_or_non_existent | User has insufficient permissions or the referenced business does not exist | 403 |
| 76 | chain_id_invalid | The chain_id passed must be an integer | 400 |
| 98 | lat_long_both_required | Both decimal latitude and longitude must be supplied when specifying location | 400 |
| 99 | lat_long_invalid | Latitude must be between -90 and +90, longitude between -180 and +180 | 400 |
| 124 | business_name_invalid | The business name must be 255 characters or less | 400 |
| 125 | business_description_invalid | The business description must be 512 characters or less | 400 |
| 126 | business_address_1_invalid | The business_address_1 value must be 128 characters or less | 400 |
| 127 | business_address_2_invalid | The business_address_2 value must be 128 characters or less | 400 |
| 128 | business_address_3_invalid | The business_address_3 value must be 128 characters or less | 400 |
| 129 | business_towncity_invalid | The business_towncity value must be 56 characters or less | 400 |
| 130 | business_region_invalid | The business_region value must be 56 characters or less | 400 |
| 131 | business_postalcode_invalid | The business_postalcode value must be 20 characters or less | 400 |
| 132 | business_country_code_invalid | The business_country_code value must be 2 characters | 400 |
| 133 | business_latitude_invalid | The business_latitude must be a decimal degree value, max +/- 90 | 400 |
| 134 | business_longitude_invalid | The business_longitude must be a decimal degree value, max +/- 180 | 400 |
| 135 | business_email_address_invalid | The business_email_address value must be a valid email address | 400 |
| 136 | business_phone_number_invalid | The business_phone_number value must be a valid phone number | 400 |
| 137 | business_fax_number_invalid | The business_fax_number value must be a valid fax number | 400 |
| 138 | business_website_url_invalid | The business_website_url value must be a valid URL | 400 |
| 139 | business_facebook_url_invalid | The business_facebook_url value must be a valid URL | 400 |
| 140 | business_twitter_username_invalid | The business_twitter_username value must be a valid Twitter username | 400 |
| 141 | business_linkedin_url_invalid | The business_linkedin_url value must be a valid URL | 400 |
| 143 | business_owner_code_invalid | The business_owner_code must be 32 characters or less | 400 |
| 278 | postalcode_invalid | The postal code format is invalid for the specified country | 400 |
| 311 | business_already_exists | A business with the provided owner_code already exists in this chain | 400 |
| 316 | parameter_supplied_not_boolean | Boolean parameter (is_shut_down, programme_opted_in, update_if_exists) contains invalid value | 400 |
| 420 | country_code_invalid | The country code must be in ISO ALPHA-2 two-letter format | 400 |
| 435 | latitude_value_error | The latitude value must be between -90 and +90 degrees | 400 |
| 436 | longitude_value_error | The longitude value must be between -180 and +180 degrees | 400 |
| 441 | parameter_missing | A required parameter is missing | 400 |
| 482 | string_parameter_too_long | One or more string parameters exceeds maximum length | 400 |