API-Referenz

Öffentliche Couverty-API

Greifen Sie auf Ihre Daten zu und binden Sie Couverty in Ihre Anwendungen ein.

Anleitung

Schnellstart

Erstellen Sie einen API-Schlüssel und nutzen Sie die API in 3 Schritten.

  1. 1

    API-Schlüssel erstellen

    Öffnen Sie Ihre Integrationseinstellungen. Klicken Sie auf «API-Schlüssel erstellen» und wählen Sie die nötigen Berechtigungen (restaurant:read, menu:read usw.).
  2. 2

    Schlüssel kopieren

    Kopieren Sie den erzeugten API-Schlüssel und bewahren Sie ihn sicher auf. Nach dem Schliessen des Dialogs können Sie ihn nicht mehr einsehen.
  3. 3

    Anfragen senden

    Verwenden Sie den Schlüssel im Header X-API-Key, um Ihre Anfragen zu authentifizieren.
Sicherheit

Authentifizierung

Drei Methoden, um Ihre Anfragen zu authentifizieren.

Methode 1: Header X-API-Key (empfohlen)

Die einfachste und sicherste Methode.

bash
curl -H "X-API-Key: qr_your_api_key_here" \
  https://api.couverty.ch/api/public/v1/restaurant

Methode 2: Authorization Bearer

Alternative mit dem Standard-Header Authorization.

bash
curl -H "Authorization: Bearer qr_your_api_key_here" \
  https://api.couverty.ch/api/public/v1/restaurant

Methode 3: Query-Parameter (nur 3CX)

Nur für 3CX-Integrationen, die keine Header verwenden können.

bash
curl https://api.couverty.ch/api/integrations/3cx/lookup?apikey=qr_your_api_key_here&phone=%2B41...

Sicherheit

Ihre API-Schlüssel sind geheim. Geben Sie sie nie clientseitig (im Browser) preis. Speichern Sie sie serverseitig in Umgebungsvariablen. Wurde ein Schlüssel kompromittiert, erstellen Sie in Ihren Einstellungen sofort einen neuen.

Berechtigungen

Jeder API-Schlüssel hat konfigurierbare Berechtigungen: restaurant:read, menu:read usw. Anfragen schlagen fehl, wenn Ihr Schlüssel die nötige Berechtigung nicht hat.
Authentifiziert

API-v1-Endpoints

Greifen Sie mit Authentifizierung per API-Schlüssel auf die Daten Ihres Restaurants zu.

GET /api/public/v1/restaurant

Liefert die Informationen des Restaurants (Name, Kontakt, Öffnungszeiten, Branding).

GET
/api/public/v1/restaurant
Berechtigung:restaurant:read
Authentifizierung:X-API-Key erforderlich
Beispielantwort
json
{
  "success": true,
  "data": {
    "name": "Le Restaurant",
    "slug": "le-restaurant",
    "contact": {
      "email": "contact@example.com",
      "telephone": "+41 22 123 45 67",
      "address": {
        "rue": "10 Rue de la Paix",
        "npaVille": "1200 Genève",
        "pays": "Suisse"
      }
    },
    "hours": {
      "midi": {
        "enabled": true,
        "ouverture": "11:30",
        "fermeture": "14:30",
        "jours": [1, 2, 3, 4, 5]
      },
      "soir": {
        "enabled": true,
        "ouverture": "18:30",
        "fermeture": "23:00",
        "jours": [0, 1, 2, 3, 4, 5, 6]
      }
    },
    "social": {
      "website": "https://example.com",
      "facebook": "https://facebook.com/restaurant",
      "instagram": "https://instagram.com/restaurant",
      "tiktok": null,
      "googleReview": null,
      "tripadvisor": null
    },
    "branding": {
      "primaryColor": "#B91C1C",
      "secondaryColor": "#D4AF37",
      "logoUrl": "https://example.com/logo.png",
      "coverImageUrl": "https://example.com/cover.png"
    }
  },
  "meta": {
    "tenantId": "tenant_123",
    "fetchedAt": "2026-03-13T10:30:00Z"
  }
}

GET /api/public/v1/menu

Liefert die vollständige Speisekarte (Gerichte und Getränke) mit Kategorien und Tagesmenü.

GET
/api/public/v1/menu
Berechtigung:menu:read
Query-Parameter:
  • type : all | plats | boissons (Standard: all)
  • includeHidden : true | false (Standard: false)
Beispielantwort
json
{
  "success": true,
  "data": {
    "plats": {
      "categories": [
        {
          "id": "cat_123",
          "nom": "Entrées",
          "description": null,
          "plats": [
            {
              "id": "plat_456",
              "nom": "Salade César",
              "description": "Salade fraîche avec croutons",
              "prix": 18.50,
              "imageUrl": "https://example.com/salade.jpg",
              "allergenes": ["gluten", "oeuf"],
              "vegetarien": true,
              "vegan": false,
              "sansGluten": false
            }
          ]
        }
      ],
      "totalPlats": 45,
      "totalCategories": 5
    },
    "boissons": {
      "categories": [
        {
          "id": "cat_789",
          "nom": "Vins rouges",
          "description": "Sélection de vins rouges",
          "boissons": [
            {
              "id": "boi_321",
              "nom": "Côtes du Rhône",
              "description": "AOC 2020",
              "prix": 35.00,
              "volume": "75cl",
              "region": "Rhône",
              "annee": 2020
            }
          ]
        }
      ],
      "totalBoissons": 30,
      "totalCategories": 4
    },
    "menuSemaine": {
      "config": { ... },
      "menus": [ ... ]
    }
  },
  "meta": {
    "tenantId": "tenant_123",
    "fetchedAt": "2026-03-13T10:30:00Z"
  }
}
Öffentlich

Öffentliche Endpoints nach Slug

Zugriff auf Verfügbarkeit, Konfiguration und Speisekarte ohne Authentifizierung. Vom Widget verwendet.

Allgemein verfügbar

Diese Endpoints erfordern keine Authentifizierung. Der Slug des Restaurants steht in der URL Ihrer Reservationsseite: https://restaurant.qr-menu.ch/book/[slug]

Konfiguration & Einstellungen

GET
/api/public/[slug]/config

Restaurantkonfiguration für das Widget (Öffnungszeiten, Zeitfenster, Kapazitäten). Cache: 5 Min. CDN, 1 Min. Browser.

Zurückgegebene Felder

horairesActifs, serviceMidiActif, serviceSoirActif

creneauxMidiConfig, creneauxSoirConfig

modeCapacite, capaciteMidi, capaciteSoir

joursOuvertsMidi, joursOuvertsSoir

Und über 40 weitere Felder (siehe vollständige Antwort)

GET
/api/public/[slug]/settings

Öffentliche Einstellungen des Restaurants (Name, Kontakt, Farben, soziale Netzwerke). Cache: 5 Min. CDN, 1 Min. Browser.

Verfügbarkeit

GET
/api/public/[slug]/availability

Prüft, ob ein Datum, ein Service oder eine Uhrzeit verfügbar ist. Cache: 2 Min.

Parameter:
  • date : YYYY-MM-DD (erforderlich)
  • service : midi | soir (erforderlich)
  • heure : HH:mm (optional)
  • personnes : Zahl (Standard: 2)
GET
/api/public/[slug]/creneaux

Listet die verfügbaren Zeitfenster mit Kapazitätsangabe auf. Cache: 1 Min.

Parameter:
  • date : YYYY-MM-DD (erforderlich)
  • service : midi | soir (erforderlich)
  • personnes oder nombrePersonnes : Zahl (Standard: 2)

Speisekarte & Getränke

GET
/api/public/[slug]/menu

Vollständige Speisekarte mit Kategorien und sichtbaren Gerichten. Cache: 10 Min.

GET
/api/public/[slug]/boissons

Getränkekarte mit Kategorien. Cache: 10 Min.

GET
/api/public/[slug]/fermetures

Bevorstehende Schliessungen, ein Eintrag pro Zeitraum: dateDebut, dateFin, type (FERMETURE, VACANCES, EVENEMENT_PRIVE, COMPLET), motif und betroffene Services. Damit können Sie auf Ihrer Website ein Banner «Ferienhalber geschlossen» anzeigen. Cache: 2 Min.

Reservationen

POST
/api/public/[slug]/reservations

Erstellt eine neue Reservation. Rate Limit: 20 Anfragen/Min. pro IP.

Request-Body:
  • prenom : string (erforderlich)
  • nom : string (erforderlich)
  • email : string (erforderlich)
  • telephone : string (erforderlich)
  • dateReservation : YYYY-MM-DD (erforderlich)
  • service : midi | soir (erforderlich)
  • nombrePersonnes : number (erforderlich)
  • heureReservation : HH:mm (optional)
  • commentaires : string (optional)
Beispielantwort
json
{
  "success": true,
  "data": {
    "id": "res_123abc",
    "prenom": "Jean",
    "nom": "Dupont",
    "email": "jean@example.com",
    "telephone": "+41 79 123 45 67",
    "dateReservation": "2026-03-20",
    "service": "soir",
    "nombrePersonnes": 4,
    "heureReservation": "19:30",
    "statut": "PENDING",
    "createdAt": "2026-03-13T10:30:00Z"
  }
}
Telefonie

3CX-Integration

Rufen Sie Gästedaten ab und melden Sie Anrufe.

Erforderliche Konfiguration

Ein API-Schlüssel des Betriebs genügt: Diese beiden Endpoints verlangen keine besondere Berechtigung. In der Praxis rufen Sie diese API nicht selbst auf: Das mitgelieferte CRM-Template erledigt das für Sie. Siehe die 3CX-Installationsanleitung.
GET
/api/integrations/3cx/lookup

Sucht einen Gast anhand der Telefonnummer. Liefert seine Informationen und Zusatzdaten (Besuche, No-Shows).

Parameter:
  • phone : string im Format E.164 (erforderlich), z. B. +41791234567
Authentifizierung:X-API-Key oder Authorization: Bearer
POST
/api/integrations/3cx/report-call

Meldet einen Anruf (eingehend, ausgehend, verpasst). Erstellt bei einem verpassten Anruf eine Benachrichtigung.

Request-Body:
  • phoneNumber : string E.164 (erforderlich)
  • callType : Inbound | Outbound | Missed | Notanswered (erforderlich)
  • durationSeconds : number (optional)
  • callDateTime : ISO 8601 (optional)
  • agent : string (optional)
Strukturen

Antwortformat

Alle API-Antworten folgen einem einheitlichen Format.

Erfolgreiche Antwort (2xx)

json
{
  "success": true,
  "data": {
    // Die angeforderten Daten
  },
  "meta": {
    "tenantId": "tenant_123",
    "fetchedAt": "2026-03-13T10:30:00Z"
  }
}

Fehlerantwort

json
{
  "success": false,
  "error": "Beschreibende Fehlermeldung"
}
Verwaltung

Fehler & Limits

Fehlercodes, Rate Limits und Fehlerbehebung.

HTTP-Fehlercodes

CodeBedeutungBeispiel
200OK - Anfrage erfolgreichDaten zurückgegeben
400Bad Request - Ungültige ParameterDatum fehlt
401Unauthorized - API-Schlüssel fehlt oder ist ungültigAPI-Schlüssel abgelaufen
403Forbidden - Unzureichende Berechtigungmenu:read fehlt
404Not Found - Ressource existiert nichtRestaurant nicht gefunden
429Too Many Requests - Rate Limit erreichtZu viele Anfragen pro Minute
500Internal Server ErrorServerfehler

Rate Limits

API v1

1000 Anfragen pro Stunde und API-Schlüssel

Öffentliche Endpoints

Kein striktes Limit, nutzt den CDN-Cache (5-10 Min.)

POST Reservationen

20 Anfragen pro Minute und IP-Adresse

3CX

1000 Anfragen pro Stunde und API-Schlüssel

Cache-Header

Die öffentlichen Endpoints enthalten einen kurzen Browser-Cache. Der Server-Cache wird bei Änderungen im Dashboard automatisch invalidiert.

http
Cache-Control: public, max-age=10

- max-age: Kurzer Browser-Cache (10 Sekunden)
- Der Server-Cache wird bei Bedarf über revalidateTag() invalidiert

Fehlerbehebung

401 Unauthorized

Die Meldung nennt die Ursache, jeder Fall hat seine eigene Antwort:

  • API key is required: Es wurde kein Schlüssel empfangen. Senden Sie ihn im Header X-API-Key oder über Authorization: Bearer
  • Invalid API key: Der Schlüssel existiert nicht oder wurde falsch kopiert. Er beginnt immer mit qr_
  • This API key has been revoked: Der Schlüssel wurde deaktiviert. Erstellen Sie in Ihren Einstellungen einen neuen
  • This API key has expired: Das Ablaufdatum ist überschritten
403 Forbidden - Missing required permission

Der Schlüssel ist gültig, hat aber die angeforderte Berechtigung nicht. Die Meldung nennt sie, zum Beispiel Missing required permission: menu:read.

  • Erstellen Sie den Schlüssel in Ihren Einstellungen mit den nötigen Berechtigungen neu
  • Schlüssel für das WordPress-Plugin benötigen menu:read und restaurant:read
429 Too Many Requests

Das Kontingent des Schlüssels ist erreicht. Die Antwort enthält einen Header Retry-After mit der Anzahl Sekunden bis zur Zurücksetzung: Verwenden Sie ihn, statt zu raten.

  • API v1: 1000 Anfragen pro Stunde und Schlüssel, der Zähler wird jede volle Stunde zurückgesetzt (kein gleitendes Fenster)
  • Speichern Sie die Antworten im Cache, statt die API erneut aufzurufen
  • Ein Schlüssel, den mehrere Websites teilen, verbraucht ein gemeinsames Kontingent: Erstellen Sie einen Schlüssel pro Website
CORS-Fehler

Die öffentlichen Endpoints ([slug]) unterstützen CORS für das Widget. Bei CORS-Fehlern:

  • Verwenden Sie diese Endpoints nur aus dem Browser, nicht von einem privaten Server
  • Für Server-zu-Server-Aufrufe verwenden Sie die v1-Endpoints mit API-Schlüssel
Implementierung

Codebeispiele

Vollständige Beispiele in mehreren Sprachen für einen schnellen Einstieg.

Restaurantinformationen abrufen

javascript
const API_KEY = process.env.COUVERTY_API_KEY;
const API_BASE = 'https://api.couverty.ch';

async function getRestaurantInfo() {
  try {
    const response = await fetch(`${API_BASE}/api/public/v1/restaurant`, {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json',
      },
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const result = await response.json();

    if (!result.success) {
      throw new Error(result.error);
    }

    console.log('Restaurant:', result.data);
    return result.data;
  } catch (error) {
    console.error('Fehler:', error.message);
    throw error;
  }
}

async function getMenu() {
  try {
    const response = await fetch(
      `${API_BASE}/api/public/v1/menu?type=plats&includeHidden=false`,
      {
        headers: { 'X-API-Key': API_KEY },
      }
    );

    if (!response.ok) throw new Error(`HTTP ${response.status}`);

    const result = await response.json();
    return result.data;
  } catch (error) {
    console.error('Fehler:', error.message);
    throw error;
  }
}

// Verwendung
(async () => {
  const restaurant = await getRestaurantInfo();
  const menu = await getMenu();
})();

Brauchen Sie Hilfe?

Lesen Sie unsere Dokumentation oder kontaktieren Sie den Support.

API-Schlüssel verwalten