API und Webhooks

Überblick

My Store Locator hat eine REST-API unter /api/v1. Die Web-App selbst nutzt diese API intern – mit Anmeldung über eine Sitzung. Diese internen Endpunkte sind keine Kunden-API und können sich ohne Ankündigung ändern.

Für Sie relevant sind heute:

• öffentliche Endpunkte einer veröffentlichten Karte (Karte abrufen, Anfrage senden, Statistik-Ereignis melden)
• API-Keys und Webhooks, die Sie in der App unter API & Webhooks anlegen

Alle Antworten sind JSON. Fehler kommen als { "error": "...", "message": "..." } mit dem passenden HTTP-Status, z. B. 400 (ungültig), 404 (nicht gefunden) oder 429 (zu viele Anfragen).

Öffentliche Endpunkte

Diese Endpunkte brauchen keine Anmeldung. Sie funktionieren nur für veröffentlichte Karten aktiver Konten und sind in der Anzahl der Aufrufe pro Minute begrenzt. Der Token ist derselbe wie im Einbettungscode.

Basis-Adresse:

https://app.my-store-locator.com/api/v1/public/maps/IHR-TOKEN

Karte abrufen

GET /api/v1/public/maps/IHR-TOKEN

Liefert die Karte mit allem, was die öffentliche Ansicht braucht:

• map – Einstellungen der Karte
• locations – die sichtbaren Standorte mit Adresse, Koordinaten, Kontakt, Öffnungszeiten, Sondertagen, Kategorie, Status und den öffentlichen eigenen Feldern
• categories, statuses, customFields – die dazugehörigen Werte
• company – Name, Logo, Website und Markenfarben

Standorte, deren Status auf der Karte ausgeblendet ist, sind nicht enthalten. Nicht öffentliche eigene Felder werden nicht ausgegeben. Jeder Aufruf zählt in der Statistik als Kartenaufruf.

Anfrage senden

POST /api/v1/public/maps/IHR-TOKEN/leads
Content-Type: application/json

{ "locationId": 1003, "name": "Erika Muster", "email": "erika@example.com",
  "phone": "", "type": "Anfrage", "message": "Haben Sie samstags geöffnet?" }

name und eine gültige email sind Pflicht. Die Anfrage landet im Postfach Anfragen der App. Antwort bei Erfolg: { "ok": true }. Eine Benachrichtigung per E-Mail ist in Vorbereitung.

Statistik-Ereignis melden

POST /api/v1/public/maps/IHR-TOKEN/track
Content-Type: application/json

{ "type": "search", "term": "Köln" }

Erlaubte Werte für type: search, no_result, store_opened, directions, call, website. Bei no_result kann km die Entfernung zum nächsten Standort angeben. Die Antwort ist leer (HTTP 204).

Die Statistik speichert nur Tageszähler – ohne Cookies und ohne IP-Adressen.

API-Keys

API-Keys legen Sie unter API & Webhooks an. Sie vergeben einen Namen und wählen die Berechtigungen:

Der Key wird nur ein einziges Mal angezeigt. Wir speichern ihn ausschließlich als Hash und können ihn nicht wiederherstellen. Bewahren Sie ihn z. B. in einem Passwort-Manager auf und behandeln Sie ihn wie ein Passwort. Nicht mehr benötigte Keys können Sie jederzeit widerrufen.

Die Keys sind für die externe Kunden-API vorgesehen, die in Vorbereitung ist.

Webhooks

Webhooks melden Änderungen an Ihr eigenes System, z. B. an Ihr ERP, CRM oder einen Chat-Kanal. Sie konfigurieren pro Webhook:

• Ziel-URL (https)
• Ereignisse: location.created, location.updated, location.deleted, map.published, lead.created, import.finished
• Format: JSON, Slack oder Discord
• Status: aktiv oder pausiert

Die Konfiguration wird heute schon gespeichert. Die Zustellung der Ereignisse an Ihre URL ist in Vorbereitung.

Was in Vorbereitung ist

• externe Kunden-API /api/v1/ext/locations mit API-Keys, um Standorte aus Ihrem System zu lesen und zu pflegen
• eine OpenAPI-Beschreibung dieser Schnittstelle
• Zustellung von Webhooks inklusive Wiederholungen bei Fehlern

Sie planen eine Anbindung an Ihre Warenwirtschaft? Schreiben Sie uns über das Kontaktformular. Bis die Kunden-API verfügbar ist, können Sie Standorte per CSV importieren und exportieren.