The newest version of this document can be found online at: https://resources.apnet.ch/api/manage/locations
Last modified: 2021-07-12 17:44 ➔ reload

Automated location management

Only for partners with multiple physical locations

API basics

• Base-URL: https://[dev|test|www].pluscash.ch/api/manage/authentication/[api-key]/[partner-id]/
• Environments: As pronounced above there are three environments available.
  • https://dev.pluscash.ch is our development environment. If you have new / other requirements to this API, then individual features and changes are developed on this environment.
  • https://test.pluscash.ch is our testing environment. Please test your implementation to already documented features here.
  • https://www.pluscash.ch is the productive environment.
• Encoding: All data is UTF-8 encoded (input and output)!
• POST data delivery:
  • Type "multipart/form-data" with only one key / value pair, where the key named "data" and its value is a JSON string.
  • Type "application/json" with a POST body only consisting of a JSON string.
• uuid: All uuids must be unique on your system. You don't have to care about uniqueness inside the apNet systems.
• api-key and partner-id: Those two values are delivered to you by apNet, once your company is registered at apNet.
• Debugging helper: If you're sending POST data but our system is not recognizing it you can attach the following GET parameter(s) to the API URL and then see what data our system recieves:
  • display-post-data displays the received POST "multipart/form-data" data in form of an array. If you sent the data with type "application/json" and our system was able to read / interpret it it is automatically mapped to the array we would expect with "multipart/form-data". If this array is displayed empty, our system then displays the raw POST input data for you to debug.
  • as-html displays the output of display-post-data as human readable HTML.
• TCS member number for testing: An active and valid TCS member card, including member number and barcode, can be fount online at: https://resources.apnet.ch/tcs/member-card.jpg

API methods

Get Locations (GET)

[Base-URL]/locations/get

Returns all locations, which have been created via API (internal hint: location.importerId is not null).

You only have to use this API-Call, if you have to manage multiple locations by yourself.
The servers answer will be empty, if you have an online shop, just one location or your locations are managed by apNet.

Returned JSON:

{
    "success": true,
    "locations": [{
        "uuid": "4e1f73f3-ad9e-4414-a9fd-d5605ac3a350",
        "name": "xyz",
        "address": "Strasse 15",
        "city": "Musterhausen",
        "zip": 3006,
        "poBox": null,
        "phone": "052 123 45 79",
        "fax": null,
        "mail": null,
        "geo": {
            "latitude": 46.941804,
            "longitude": 7.466993
        }
    }, {
        ...
    }]
}

Returned JSON in case of an error:

{
    "success": false,
    "message": "[error-message]"
}

Set Locations (POST)

[Base-URL]/locations/set

Set your locations.

You only have to use this API-Call, if you have to manage multiple locations by yourself.

Manually created locations (e.g. by apNet or via backend) do not get touched by this API.

All locations must be submitted, the ones you don't submit will get marked as deleted.

Required POST data:

• You can pass any number of locations to this call, chained in an array.
• Mandatory fields are: uuid, address, city, zip, geo->latitude, geo->longitude

[{
    "uuid": 1243,
    "name": null,              // [optional] if not submitted the name will be partner name with location address (e.g. "Restaurant Falken, Schaffhausen, Vorstadt 5")
    "address": "Strasse 15",
    "city": "Musterhausen",
    "zip": 8200,
    "poBox": null,             // [optional]
    "phone": null,             // [optional]
    "fax": null,               // [optional]
    "mail": null,              // [optional]
    "geo": {                   // geoLocation is mandatory, since we display locations on a map
        "latitude": 45.232323,
        "longitude": 123.22321
    }
}, {
    ...
}]

Returned JSON in case of all locations have been successfully created or updated:

{
    "success": true
}

Returned JSON in case of any location had an error:

{
    "success": true,
    "notUpdatedLocationsDueToError": [{
        "uuid": "uuid of submitted location",
        "error": "message describing the problem"
    }, {
        ...
    }]
}