POST outlet · Web API v3 · Deutsch

POST outlet

Web API v3 · Deutsch v3merchants

Aktualität laut Confluence unklar. Die englische POS API v3 ist die aktuelle Referenz.

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

Der Body des Requests zum Anlegen eines neuen Outlets kann folgende Parameter übernehmen (alle optional):

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

Feld	Beschreibung
`Name`	string : optional - Name der Filiale. Dieser Wert wir in den Smartphone-Apps für die Öffentlichkeit sichtbar sein.
`Description`	string : optional - Längere Beschreibung zur Filiale sofern vorhanden.Dieser Wert wir in den Smartphone-Apps für die Öffentlichkeit sichtbar sein.
`Street`	string : optional - Straßenname mit Straßennummer
`City`	string : optional - Stadtname
`PostalIndex`	string : optional - Postleitzahl
`CountryIso`	string : optional - 2-buchstabiger Länder-Kürzel nach ISO 3166 .
`PublicTelefon`	string : optional - Dieser Wert wir in den Smartphone-Apps als Kontakttelefon für alle sichtbar sein.
`PublicEmail`	string : optional - Dieser Wert wir in den Smartphone-Apps als Kontaktemail für alle sichtbar sein.
`WebsiteUrl`	string : optional - Url zur Website der Filiale, wenn vorhanden.
`FacebookUrl`	string : optional - Url zur Facebook-Page der Filiale, wenn vorhanden.
`TwitterUrl`	string : optional - Url zur Twitter-Page der Filiale, wenn vorhanden.

Im Response wird ein Objekt mit einer Id und einem Name zu dem neu erstellten outlet-Objekt geliefert. Beispiel:

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

Mit dieser kann dann eine Registrierung der trackingUnit vorgenommen werden (siehe GET trackingUnits)

Parameter

qnipsUserNamestringErforderlich

Lassen Sie den Merchant seinen qnipsUserName eintragen und fügen Sie diesen hier ein. Der Wert sollte URL-konform escaped werden, da er Umlaute enthalten kann, z.B. 'hans.möller@firma.de' -> 'hans.m%C3%B6ller@firma.de'.

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

brandIdlongErforderlich

Hier sollte die ID des ausgewählten Brands stehen, in welchem das Outlet angelegt werden soll

Beispiel: 123

Request-Header

Accept

application/json

DevKey

{Ihr Key}

Kontext: merchants

Wie im Kapitel Client-Registrierung beschrieben, muss sich jeder Client an unserem System zunächst als eine trackingUnit registrieren. Für diese Registrierung wird eine sogenannte outletId benötigt, die uns hilft, die trackingUnit sofort zu einer realen Filiale/Standort eines merchants zuzuordnen. Eine outletId lässt sich auf zwei unterschiedlichen Wegen besorgen:

Abrufen von bereits existierenden brands und outlets, um eine zu registrierende trackingUnit in einem bestehenden outlet einzuordnen. Bauen Sie dies wie folgt ein:
- Fragen Sie bei der menio-Aktivierung den Usernamen des menio-Accounts ab
- Führen Sie GET merchants/{qnipsUserName}/info aus und stellen Sie das Ergebnis im UI dar
- Lassen Sie den Bediener eine outletId auswählen
- Registrieren Sie die trackingUnit über GET trackingUnits
Verfügt Ihre Software über Standortinformationen, bestehend mind. aus PLZ, Stadt, Straße und Straßennummer, ist es möglich, einen automatischen Export der Standorte aus Ihrem in unser System zu ermöglichen. Bauen Sie dies ggf. wie folgt ein:
- Fragen Sie bei der menio-Aktivierung den Usernamen des menio-Accounts ab
- Führen Sie GET merchants/{qnipsUserName}/info aus und stellen Sie das Ergebnis im UI dar
- Lassen Sie den Bediener eine brandId auswählen
- Erstellen Sie in der Brand einen neuen Outlet über POST merchants/{qnipsUserName}/outlets
- Registrieren Sie die trackingUnit über GET trackingUnits

Originaler Blueprint-Ausschnitt

API Blueprint

### POST outlet [POST]
Der Body des Requests zum Anlegen eines neuen Outlets kann folgende Parameter übernehmen (alle optional):

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

| Feld | Beschreibung |
| ---    | --- |
|`Name`|**string : optional** - Name der Filiale. Dieser Wert wir in den Smartphone-Apps für die Öffentlichkeit sichtbar sein.|
|`Description`|**string : optional** - Längere Beschreibung zur Filiale sofern vorhanden.Dieser Wert wir in den Smartphone-Apps für die Öffentlichkeit sichtbar sein.|
|`Street`|**string : optional** - Straßenname mit Straßennummer|
|`City`|**string : optional** - Stadtname|
|`PostalIndex`|**string : optional** - Postleitzahl|
|`CountryIso`|**string : optional** - 2-buchstabiger Länder-Kürzel nach ISO 3166 .|
|`PublicTelefon`|**string : optional** - Dieser Wert wir in den Smartphone-Apps als Kontakttelefon für alle sichtbar sein.|
|`PublicEmail`|**string : optional** - Dieser Wert wir in den Smartphone-Apps als Kontaktemail für alle sichtbar sein.|
|`WebsiteUrl`|**string : optional** - Url zur Website der Filiale, wenn vorhanden.|
|`FacebookUrl`|**string : optional** - Url zur Facebook-Page der Filiale, wenn vorhanden.|
|`TwitterUrl`|**string : optional** - Url zur Twitter-Page der Filiale, wenn vorhanden.|

Im Response wird ein Objekt mit einer `Id` und einem `Name` zu dem neu erstellten `outlet`-Objekt geliefert. Beispiel:

        { 
            Id: 10125,
            Name: "Caesar's Hannover - (Hannover, Weidendamm 8)", 
        }
        
Mit dieser kann dann eine Registrierung der trackingUnit vorgenommen werden 
(siehe *[GET trackingUnits](#reference/trackingunits/registrieren/get-trackingunits)*)

+ Parameters
    + qnipsUserName (string, `hans.m%C3%B6ller@firma.de`) ... Lassen Sie den Merchant seinen `qnipsUserName` eintragen und fügen Sie diesen hier ein. Der Wert sollte URL-konform escaped werden, da er Umlaute enthalten kann, z.B. `'hans.möller@firma.de' -> 'hans.m%C3%B6ller@firma.de'`.
    + brandId (long, `123`) ... Hier sollte die ID des ausgewählten Brands stehen, in welchem das Outlet angelegt werden soll

+ Request

    + Headers

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

            {
                "Name":"Demo Filiale",
                "Description":"Demo Filiale",
                "Street":"Schulenburger Landstraße 156",
                "City":"Hannover",
                "PostalIndex":"30419",
                "CountryIso":"DE",
                "PublicTelefon":"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: Ein unbekannten Problem bei der Verarbeitung aufgetreten

+ Response 401 

        // HTTP-Unauthorized: DevKey nicht angegeben oder nicht vorhanden

+ Response 404

        // HTTP-NotFound: qnipsUserName unbekannt oder hat keine brands

Request

cURL

curl --request POST \
  'http://pos.prelive.qnips.com/api/pos/v3/merchants/{qnipsUserName}/outlets?brandId={brandId}' \
  --header 'Accept: application/json' \
  --header 'DevKey: {YOUR_DEV_KEY}' \
  --data-raw '{
    "Name":"Demo Filiale",
    "Description":"Demo Filiale",
    "Street":"Schulenburger Landstraße 156",
    "City":"Hannover",
    "PostalIndex":"30419",
    "CountryIso":"DE",
    "PublicTelefon":"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: Ein unbekannten Problem bei der Verarbeitung aufgetreten

Response 401

// HTTP-Unauthorized: DevKey nicht angegeben oder nicht vorhanden

Response 404

// HTTP-NotFound: qnipsUserName unbekannt oder hat keine brands