Riferimento API
API pubblica di Couverty
Acceda ai Suoi dati e integri Couverty nelle Sue applicazioni.
Avvio rapido
Crei una chiave API e inizi a usare l'API in 3 passi.
- 1
Creare una chiave API
Apra le Sue impostazioni di integrazione. Clicchi su «Crea una chiave API» e selezioni i permessi necessari (restaurant:read, menu:read, ecc.). - 2
Copiare la chiave
Copi la chiave API generata e la conservi in un luogo sicuro. Dopo aver chiuso la finestra non potrà più vederla. - 3
Inviare richieste
Usi la chiave nell'headerX-API-Keyper autenticare le Sue richieste.
Autenticazione
Tre metodi per autenticare le Sue richieste.
Metodo 1: header X-API-Key (consigliato)
Il metodo più semplice e più sicuro.
curl -H "X-API-Key: qr_your_api_key_here" \ https://api.couverty.ch/api/public/v1/restaurant
Metodo 2: Authorization Bearer
Alternativa che usa l'header standard Authorization.
curl -H "Authorization: Bearer qr_your_api_key_here" \ https://api.couverty.ch/api/public/v1/restaurant
Metodo 3: parametro di query (solo 3CX)
Solo per le integrazioni 3CX che non possono usare gli header.
curl https://api.couverty.ch/api/integrations/3cx/lookup?apikey=qr_your_api_key_here&phone=%2B41...
Sicurezza
Permessi
restaurant:read, menu:read, ecc. Le richieste falliscono se la Sua chiave non ha il permesso richiesto.Endpoint API v1
Acceda ai dati del Suo ristorante con autenticazione tramite chiave API.
GET /api/public/v1/restaurant
Restituisce le informazioni del ristorante (nome, contatti, orari, branding).
/api/public/v1/restaurantEsempio di risposta
{
"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
Restituisce il menu completo (piatti e bevande) con categorie e menu della settimana.
/api/public/v1/menutype: all | plats | boissons (predefinito: all)includeHidden: true | false (predefinito: false)
Esempio di risposta
{
"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"
}
}Endpoint pubblici per slug
Accesso a disponibilità, configurazione e menu senza autenticazione. Usati dal widget.
Disponibilità generale
https://restaurant.qr-menu.ch/book/[slug]Configurazione & Impostazioni
/api/public/[slug]/configConfigurazione del ristorante per il widget (orari, fasce orarie, capacità). Cache: 5 min CDN, 1 min browser.
Campi restituiti
horairesActifs, serviceMidiActif, serviceSoirActif
creneauxMidiConfig, creneauxSoirConfig
modeCapacite, capaciteMidi, capaciteSoir
joursOuvertsMidi, joursOuvertsSoir
E oltre 40 altri campi (vedere la risposta completa)
/api/public/[slug]/settingsImpostazioni pubbliche del ristorante (nome, contatti, colori, social network). Cache: 5 min CDN, 1 min browser.
Disponibilità
/api/public/[slug]/availabilityVerifica se una data, un servizio o un orario è disponibile. Cache: 2 min.
date: YYYY-MM-DD (obbligatorio)service: midi | soir (obbligatorio)heure: HH:mm (facoltativo)personnes: numero (predefinito: 2)
/api/public/[slug]/creneauxElenca le fasce orarie disponibili con le informazioni sulla capacità. Cache: 1 min.
date: YYYY-MM-DD (obbligatorio)service: midi | soir (obbligatorio)personnesonombrePersonnes: numero (predefinito: 2)
Menu & Bevande
/api/public/[slug]/menuMenu completo con categorie e piatti visibili. Cache: 10 min.
/api/public/[slug]/boissonsCarta delle bevande con categorie. Cache: 10 min.
/api/public/[slug]/fermeturesChiusure in arrivo, una voce per periodo: dateDebut, dateFin, type (FERMETURE, VACANCES, EVENEMENT_PRIVE, COMPLET), motif e servizi interessati. Quanto basta per mostrare un banner «chiuso per ferie» sul Suo sito. Cache: 2 min.
Prenotazioni
/api/public/[slug]/reservationsCrea una nuova prenotazione. Rate limit: 20 richieste/min per IP.
prenom: string (obbligatorio)nom: string (obbligatorio)email: string (obbligatorio)telephone: string (obbligatorio)dateReservation: YYYY-MM-DD (obbligatorio)service: midi | soir (obbligatorio)nombrePersonnes: number (obbligatorio)heureReservation: HH:mm (facoltativo)commentaires: string (facoltativo)
Esempio di risposta
{
"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"
}
}Integrazione 3CX
Recuperi i dati dei clienti e segnali le chiamate.
Configurazione richiesta
/api/integrations/3cx/lookupCerca un cliente tramite numero di telefono. Restituisce le informazioni e i dati aggiuntivi (visite, no-show).
phone: string in formato E.164 (obbligatorio), es.: +41791234567
/api/integrations/3cx/report-callSegnala una chiamata (in entrata, in uscita, persa). Crea una notifica in caso di chiamata persa.
phoneNumber: string E.164 (obbligatorio)callType: Inbound | Outbound | Missed | Notanswered (obbligatorio)durationSeconds: number (facoltativo)callDateTime: ISO 8601 (facoltativo)agent: string (facoltativo)
Formato delle risposte
Tutte le risposte dell'API seguono un formato standard.
Risposta riuscita (2xx)
{
"success": true,
"data": {
// I dati richiesti
},
"meta": {
"tenantId": "tenant_123",
"fetchedAt": "2026-03-13T10:30:00Z"
}
}Risposta di errore
{
"success": false,
"error": "Messaggio di errore descrittivo"
}Errori & Limiti
Codici di errore, rate limit e risoluzione dei problemi.
Codici di errore HTTP
| Codice | Significato | Esempio |
|---|---|---|
| 200 | OK - Richiesta riuscita | Dati restituiti |
| 400 | Bad Request - Parametri non validi | Data mancante |
| 401 | Unauthorized - Chiave API mancante o non valida | Chiave API scaduta |
| 403 | Forbidden - Permesso insufficiente | menu:read mancante |
| 404 | Not Found - Risorsa inesistente | Ristorante non trovato |
| 429 | Too Many Requests - Rate limit raggiunto | Troppe richieste al minuto |
| 500 | Internal Server Error | Errore del server |
Rate limit
API v1
1000 richieste all'ora per chiave API
Endpoint pubblici
Nessun limite rigido, usa la cache CDN (5-10 min)
POST Prenotazioni
20 richieste al minuto per indirizzo IP
3CX
1000 richieste all'ora per chiave API
Header di cache
Gli endpoint pubblici includono una breve cache del browser. La cache del server viene invalidata automaticamente quando si apportano modifiche nella dashboard.
Cache-Control: public, max-age=10 - max-age: Breve cache del browser (10 secondi) - La cache del server viene invalidata su richiesta tramite revalidateTag()
Risoluzione dei problemi
401 Unauthorized
Il messaggio indica la causa, ogni caso ha la propria risposta:
API key is required: nessuna chiave ricevuta. La invii nell'headerX-API-Keyo tramiteAuthorization: BearerInvalid API key: la chiave non esiste o è stata copiata male. Inizia sempre conqr_This API key has been revoked: la chiave è stata disattivata. Ne crei una nuova nelle Sue impostazioniThis API key has expired: la data di scadenza è superata
403 Forbidden - Missing required permission
La chiave è valida ma non ha il permesso richiesto. Il messaggio lo indica, per esempio Missing required permission: menu:read.
- Rigeneri la chiave con i permessi necessari nelle Sue impostazioni
- Le chiavi usate dal plugin WordPress richiedono
menu:readerestaurant:read
429 Too Many Requests
La quota della chiave è esaurita. La risposta contiene un header Retry-After che indica i secondi mancanti all'azzeramento: lo usi invece di tirare a indovinare.
- API v1: 1000 richieste all'ora per chiave, contatore azzerato ogni ora (finestra non scorrevole)
- Metta in cache le risposte invece di richiamare l'API
- Una stessa chiave condivisa tra più siti consuma una quota comune: crei una chiave per sito
Errori CORS
Gli endpoint pubblici ([slug]) supportano CORS per il widget. In caso di errori CORS:
- Usi questi endpoint solo dal browser, non da un server privato
- Per le chiamate da server a server, usi gli endpoint v1 con chiave API
Esempi di codice
Esempi completi in più linguaggi per iniziare rapidamente.
Recuperare le informazioni del ristorante
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('Errore:', 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('Errore:', error.message);
throw error;
}
}
// Utilizzo
(async () => {
const restaurant = await getRestaurantInfo();
const menu = await getMenu();
})();