Guida

Avvio rapido

Crei una chiave API e inizi a usare l'API in 3 passi.

  1. 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. 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. 3

    Inviare richieste

    Usi la chiave nell'header X-API-Key per autenticare le Sue richieste.
Sicurezza

Autenticazione

Tre metodi per autenticare le Sue richieste.

Metodo 1: header X-API-Key (consigliato)

Il metodo più semplice e più sicuro.

bash
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.

bash
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.

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

Sicurezza

Le Sue chiavi API sono segrete. Non le esponga mai lato client (browser). Le conservi in variabili d'ambiente lato server. Se una chiave è stata compromessa, ne generi subito una nuova nelle Sue impostazioni.

Permessi

Ogni chiave API ha permessi configurabili: restaurant:read, menu:read, ecc. Le richieste falliscono se la Sua chiave non ha il permesso richiesto.
Autenticati

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).

GET
/api/public/v1/restaurant
Permesso:restaurant:read
Autenticazione:X-API-Key obbligatoria
Esempio di risposta
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

Restituisce il menu completo (piatti e bevande) con categorie e menu della settimana.

GET
/api/public/v1/menu
Permesso:menu:read
Parametri di query:
  • type : all | plats | boissons (predefinito: all)
  • includeHidden : true | false (predefinito: false)
Esempio di risposta
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"
  }
}
Pubblici

Endpoint pubblici per slug

Accesso a disponibilità, configurazione e menu senza autenticazione. Usati dal widget.

Disponibilità generale

Questi endpoint non richiedono autenticazione. Lo slug del ristorante è visibile nell'URL della Sua pagina di prenotazione: https://restaurant.qr-menu.ch/book/[slug]

Configurazione & Impostazioni

GET
/api/public/[slug]/config

Configurazione 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)

GET
/api/public/[slug]/settings

Impostazioni pubbliche del ristorante (nome, contatti, colori, social network). Cache: 5 min CDN, 1 min browser.

Disponibilità

GET
/api/public/[slug]/availability

Verifica se una data, un servizio o un orario è disponibile. Cache: 2 min.

Parametri:
  • date : YYYY-MM-DD (obbligatorio)
  • service : midi | soir (obbligatorio)
  • heure : HH:mm (facoltativo)
  • personnes : numero (predefinito: 2)
GET
/api/public/[slug]/creneaux

Elenca le fasce orarie disponibili con le informazioni sulla capacità. Cache: 1 min.

Parametri:
  • date : YYYY-MM-DD (obbligatorio)
  • service : midi | soir (obbligatorio)
  • personnes o nombrePersonnes : numero (predefinito: 2)

Menu & Bevande

GET
/api/public/[slug]/menu

Menu completo con categorie e piatti visibili. Cache: 10 min.

GET
/api/public/[slug]/boissons

Carta delle bevande con categorie. Cache: 10 min.

GET
/api/public/[slug]/fermetures

Chiusure 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

POST
/api/public/[slug]/reservations

Crea una nuova prenotazione. Rate limit: 20 richieste/min per IP.

Corpo della richiesta:
  • 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
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"
  }
}
Telefonia

Integrazione 3CX

Recuperi i dati dei clienti e segnali le chiamate.

Configurazione richiesta

Basta una chiave API dell'esercizio: questi due endpoint non richiedono permessi particolari. In pratica non chiamerà questa API da sé: lo fa per Lei il modello CRM fornito. Veda la guida all'installazione di 3CX.
GET
/api/integrations/3cx/lookup

Cerca un cliente tramite numero di telefono. Restituisce le informazioni e i dati aggiuntivi (visite, no-show).

Parametri:
  • phone : string in formato E.164 (obbligatorio), es.: +41791234567
Autenticazione:X-API-Key o Authorization: Bearer
POST
/api/integrations/3cx/report-call

Segnala una chiamata (in entrata, in uscita, persa). Crea una notifica in caso di chiamata persa.

Corpo della richiesta:
  • phoneNumber : string E.164 (obbligatorio)
  • callType : Inbound | Outbound | Missed | Notanswered (obbligatorio)
  • durationSeconds : number (facoltativo)
  • callDateTime : ISO 8601 (facoltativo)
  • agent : string (facoltativo)
Strutture

Formato delle risposte

Tutte le risposte dell'API seguono un formato standard.

Risposta riuscita (2xx)

json
{
  "success": true,
  "data": {
    // I dati richiesti
  },
  "meta": {
    "tenantId": "tenant_123",
    "fetchedAt": "2026-03-13T10:30:00Z"
  }
}

Risposta di errore

json
{
  "success": false,
  "error": "Messaggio di errore descrittivo"
}
Gestione

Errori & Limiti

Codici di errore, rate limit e risoluzione dei problemi.

Codici di errore HTTP

CodiceSignificatoEsempio
200OK - Richiesta riuscitaDati restituiti
400Bad Request - Parametri non validiData mancante
401Unauthorized - Chiave API mancante o non validaChiave API scaduta
403Forbidden - Permesso insufficientemenu:read mancante
404Not Found - Risorsa inesistenteRistorante non trovato
429Too Many Requests - Rate limit raggiuntoTroppe richieste al minuto
500Internal Server ErrorErrore 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.

http
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'header X-API-Key o tramite Authorization: Bearer
  • Invalid API key: la chiave non esiste o è stata copiata male. Inizia sempre con qr_
  • This API key has been revoked: la chiave è stata disattivata. Ne crei una nuova nelle Sue impostazioni
  • This 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:read e restaurant: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
Implementazione

Esempi di codice

Esempi completi in più linguaggi per iniziare rapidamente.

Recuperare le informazioni del ristorante

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('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();
})();

Ha bisogno di aiuto?

Consulti la nostra documentazione o contatti il supporto.

Gestire le chiavi API