API-Referenz
Öffentliche Couverty-API
Greifen Sie auf Ihre Daten zu und binden Sie Couverty in Ihre Anwendungen ein.
Schnellstart
Erstellen Sie einen API-Schlüssel und nutzen Sie die API in 3 Schritten.
- 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
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
Anfragen senden
Verwenden Sie den Schlüssel im HeaderX-API-Key, um Ihre Anfragen zu authentifizieren.
Authentifizierung
Drei Methoden, um Ihre Anfragen zu authentifizieren.
Methode 1: Header X-API-Key (empfohlen)
Die einfachste und sicherste Methode.
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.
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.
curl https://api.couverty.ch/api/integrations/3cx/lookup?apikey=qr_your_api_key_here&phone=%2B41...
Sicherheit
Berechtigungen
restaurant:read, menu:read usw. Anfragen schlagen fehl, wenn Ihr Schlüssel die nötige Berechtigung nicht hat.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).
/api/public/v1/restaurantBeispielantwort
{
"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ü.
/api/public/v1/menutype: all | plats | boissons (Standard: all)includeHidden: true | false (Standard: false)
Beispielantwort
{
"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"
}
}Öffentliche Endpoints nach Slug
Zugriff auf Verfügbarkeit, Konfiguration und Speisekarte ohne Authentifizierung. Vom Widget verwendet.
Allgemein verfügbar
https://restaurant.qr-menu.ch/book/[slug]Konfiguration & Einstellungen
/api/public/[slug]/configRestaurantkonfiguration 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)
/api/public/[slug]/settingsÖffentliche Einstellungen des Restaurants (Name, Kontakt, Farben, soziale Netzwerke). Cache: 5 Min. CDN, 1 Min. Browser.
Verfügbarkeit
/api/public/[slug]/availabilityPrüft, ob ein Datum, ein Service oder eine Uhrzeit verfügbar ist. Cache: 2 Min.
date: YYYY-MM-DD (erforderlich)service: midi | soir (erforderlich)heure: HH:mm (optional)personnes: Zahl (Standard: 2)
/api/public/[slug]/creneauxListet die verfügbaren Zeitfenster mit Kapazitätsangabe auf. Cache: 1 Min.
date: YYYY-MM-DD (erforderlich)service: midi | soir (erforderlich)personnesodernombrePersonnes: Zahl (Standard: 2)
Speisekarte & Getränke
/api/public/[slug]/menuVollständige Speisekarte mit Kategorien und sichtbaren Gerichten. Cache: 10 Min.
/api/public/[slug]/boissonsGetränkekarte mit Kategorien. Cache: 10 Min.
/api/public/[slug]/fermeturesBevorstehende 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
/api/public/[slug]/reservationsErstellt eine neue Reservation. Rate Limit: 20 Anfragen/Min. pro IP.
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
{
"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"
}
}3CX-Integration
Rufen Sie Gästedaten ab und melden Sie Anrufe.
Erforderliche Konfiguration
/api/integrations/3cx/lookupSucht einen Gast anhand der Telefonnummer. Liefert seine Informationen und Zusatzdaten (Besuche, No-Shows).
phone: string im Format E.164 (erforderlich), z. B. +41791234567
/api/integrations/3cx/report-callMeldet einen Anruf (eingehend, ausgehend, verpasst). Erstellt bei einem verpassten Anruf eine Benachrichtigung.
phoneNumber: string E.164 (erforderlich)callType: Inbound | Outbound | Missed | Notanswered (erforderlich)durationSeconds: number (optional)callDateTime: ISO 8601 (optional)agent: string (optional)
Antwortformat
Alle API-Antworten folgen einem einheitlichen Format.
Erfolgreiche Antwort (2xx)
{
"success": true,
"data": {
// Die angeforderten Daten
},
"meta": {
"tenantId": "tenant_123",
"fetchedAt": "2026-03-13T10:30:00Z"
}
}Fehlerantwort
{
"success": false,
"error": "Beschreibende Fehlermeldung"
}Fehler & Limits
Fehlercodes, Rate Limits und Fehlerbehebung.
HTTP-Fehlercodes
| Code | Bedeutung | Beispiel |
|---|---|---|
| 200 | OK - Anfrage erfolgreich | Daten zurückgegeben |
| 400 | Bad Request - Ungültige Parameter | Datum fehlt |
| 401 | Unauthorized - API-Schlüssel fehlt oder ist ungültig | API-Schlüssel abgelaufen |
| 403 | Forbidden - Unzureichende Berechtigung | menu:read fehlt |
| 404 | Not Found - Ressource existiert nicht | Restaurant nicht gefunden |
| 429 | Too Many Requests - Rate Limit erreicht | Zu viele Anfragen pro Minute |
| 500 | Internal Server Error | Serverfehler |
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.
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 HeaderX-API-Keyoder überAuthorization: BearerInvalid API key: Der Schlüssel existiert nicht oder wurde falsch kopiert. Er beginnt immer mitqr_This API key has been revoked: Der Schlüssel wurde deaktiviert. Erstellen Sie in Ihren Einstellungen einen neuenThis 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:readundrestaurant: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
Codebeispiele
Vollständige Beispiele in mehreren Sprachen für einen schnellen Einstieg.
Restaurantinformationen abrufen
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