POST outlet · POS API

POST outlet

POS API v3merchants

POST/merchants/{qnipsUserName}/outlets?brandId={brandId}

The body of the request to create a new outlet can take the following parameters (all optional):

{ "Name": "Demo Branch." "Description": "Demo Branch." "Street": "Schulenburger Landstrasse 156", "City": "Hannover", "PostalIndex": "30419." "CountryIso": "DE" "PublicTelefon": "0511-12345" "PublicEmail": "example@example.de" "WebsiteUrl": "http://..." "FacebookUrl": "http://..." "TwitterUrl": "http://..." }

Field	Description
`Name`	string : optional - name of the branch. This value will be visible to the public in the smartphone apps.
`Description`	string : optional - Longer description to the branch if available This value will be visible to the public in the smartphone apps.
`Street`	string : optional - street name with street number
`City`	string : optional - city name
`PostalIndex`	string : optional - postal code
`CountryIso`	string : optional - 2-letter country abbreviation according to ISO 3166 .
`PublicTelefon`	string : optional - This value will be visible to everyone in the smartphone apps as a contact phone.
`PublicEmail`	string : optional - This value will be visible to everyone in the smartphone apps as contact mail.
`WebsiteUrl`	string : optional - Url to the website of the branch, if available.
`FacebookUrl`	string : optional - Url to the Facebook page of the branch, if available.
`TwitterUrl`	string : optional - Url to the Twitter page of the branch, if available.

In the response, an object with an 'ID' and a 'name' is delivered to the newly created 'outlet' object. Example:

{ Id: 10125, Name: 'Caesar's Hannover - (Hannover, Weidendamm 8)', }

This can then be used to register the trackingUnit (see GET trackingUnits)

Parameter

qnipsUserNamestringErforderlich

Let the merchant enter his 'qnipsUserName' and insert it here. The value should be escaped URL-compliant, as it may contain umlauts, e.g. 'hans.mÃ¶ller@firma.de' -> 'hans.m%C3%B6ller@firma.de'.

Beispiel: hans.m%C3%B6ller@firma.de

brandIdlongErforderlich

Here should be the ID of the selected brand, in which the outlet should be created

Beispiel: 123

Request-Header

Accept

application/json

DevKey

{Your Key}

Kontext: merchants

As described in the chapter Client registration, each client must register with our system as a trackingUnit first. For this registration we need a so called 'outletId' which helps us to immediately assign the trackingUnit to a real branch/location of a 'merchant'. An 'outletId' can be based on two different ways:

Retrieve existing 'brands' and 'outlets' to place a trackingUnit to be registered in an existing 'outlet Install this as follows:
- During menio activation, ask for the username of the menio account
- Execute GET merchants/{qnipsUserName}/info and display the result in the UI
- Let the operator select an 'outletId
- Register the 'trackingUnit' via GET trackingUnits
If your software has location information, consisting at least of postcode, city, street and street number, it is possible to enable an automatic export of the locations from your system to ours. If necessary, install this as follows:
- During menio activation, ask for the username of the menio account
- Execute GET merchants/{qnipsUserName}/info and display the result in the UI
- Let the operator select a 'brandId
- Create a new outlet in the Brand via POST merchants/{qnipsUserName}/outlets
- Register the 'trackingUnit' via GET trackingUnits

Originaler Blueprint-Ausschnitt

API Blueprint

### POST outlet [POST]
The body of the request to create a new outlet can take the following parameters (all optional):

        {
            "Name": "Demo Branch."
            "Description": "Demo Branch."
            "Street": "Schulenburger Landstrasse 156",
            "City": "Hannover",
            "PostalIndex": "30419."
            "CountryIso": "DE"
            "PublicTelefon": "0511-12345"
            "PublicEmail": "example@example.de"
            "WebsiteUrl": "http://..."
            "FacebookUrl": "http://..."
            "TwitterUrl": "http://..."
        }

| Field | Description |
| --- | --- |
|`Name`|**string : optional** - name of the branch. This value will be visible to the public in the smartphone apps.
|`Description`|**string : optional** - Longer description to the branch if available This value will be visible to the public in the smartphone apps.
|`Street`|**string : optional** - street name with street number|
|`City`|**string : optional** - city name|
|`PostalIndex`|**string : optional** - postal code|
|`CountryIso`|**string : optional** - 2-letter country abbreviation according to ISO 3166 .|
|`PublicTelefon`|**string : optional** - This value will be visible to everyone in the smartphone apps as a contact phone.
|`PublicEmail`|**string : optional** - This value will be visible to everyone in the smartphone apps as contact mail.
|`WebsiteUrl`|**string : optional** - Url to the website of the branch, if available.
|`FacebookUrl`|**string : optional** - Url to the Facebook page of the branch, if available.|
|`TwitterUrl`|**string : optional** - Url to the Twitter page of the branch, if available.

In the response, an object with an 'ID' and a 'name' is delivered to the newly created 'outlet' object. Example:

        {
            Id: 10125,
            Name: 'Caesar's Hannover - (Hannover, Weidendamm 8)',
        }
        
This can then be used to register the trackingUnit
(see *[GET trackingUnits](#reference/trackingunits/registrieren/get-trackingunits)*)

+ Parameters
    + qnipsUserName (string, `hans.m%C3%B6ller@firma.de`) ... Let the merchant enter his 'qnipsUserName' and insert it here. The value should be escaped URL-compliant, as it may contain umlauts, e.g. 'hans.mÃ¶ller@firma.de' -> 'hans.m%C3%B6ller@firma.de'.
    + brandId (long, `123`) ... Here should be the ID of the selected brand, in which the outlet should be created

+ Request

    + Headers

            Accept: application/json
            DevKey: {Your Key}
    
    + Body

            {
                "Name": "Demo Branch."
                "Description": "Demo Branch."
                "Street": "Schulenburger Landstrasse 156",
                "City": "Hannover",
                "PostalIndex": "30419."
                "CountryIso": "DE"
                "Public Telefon": "0511-12345"
                "PublicEmail": "example@example.de"
                "WebsiteUrl": "http://..."
                "FacebookUrl": "http://..."
                "TwitterUrl": "http://..."
            }
    

+ response 200

        {
            Id: 10125,
            Name: 'Caesar's Hannover - (Hannover, Weidendamm 8)',
        }

+ response 500

        // HTTP-InternalServerError: An unknown problem occurred during processing

+ Response 401

        // HTTP-Unauthorized: DevKey not specified or not available

+ response 404

        // HTTP-NotFound: qnipsUserName unknown or has no brands

Request

cURL

curl --request POST \
  'https://pos-playground-eu.qnips.com/api/pos/v3/merchants/{qnipsUserName}/outlets?brandId={brandId}' \
  --header 'Accept: application/json' \
  --header 'DevKey: {YOUR_DEV_KEY}' \
  --data-raw '{
    "Name": "Demo Branch."
    "Description": "Demo Branch."
    "Street": "Schulenburger Landstrasse 156",
    "City": "Hannover",
    "PostalIndex": "30419."
    "CountryIso": "DE"
    "Public Telefon": "0511-12345"
    "PublicEmail": "example@example.de"
    "WebsiteUrl": "http://..."
    "FacebookUrl": "http://..."
    "TwitterUrl": "http://..."
}
'

Dokumentationsbeispiel. Platzhalter vor der Verwendung ersetzen.

Response

Response 200

{
    Id: 10125,
    Name: 'Caesar's Hannover - (Hannover, Weidendamm 8)',
}

Response 500

// HTTP-InternalServerError: An unknown problem occurred during processing

Response 401

// HTTP-Unauthorized: DevKey not specified or not available

Response 404

// HTTP-NotFound: qnipsUserName unknown or has no brands