API Documentatie Pro+

De Couverto REST API geeft je programmatische toegang tot reserveringen, gasten en beschikbaarheid. Beschikbaar voor Pro- en Business-abonnees. Genereer je API-sleutels via app.couverto.nl/api-keys.

Authenticatie

Alle API-verzoeken vereisen een Bearer-token in de Authorization header. Je vindt en beheert je sleutels in het dashboard onder API Keys & Webhooks.

curl https://app.couverto.nl/api/v2/reservations \
  -H "Authorization: Bearer ck_live_AbCdEfGhIj..."

Base URL

https://app.couverto.nl/api/v2

Alle responses zijn JSON. Stuur Content-Type: application/json mee bij POST-verzoeken.

Foutafhandeling

De API gebruikt standaard HTTP-statuscodes. Foutresponses bevatten altijd een error-veld.

// 422 Unprocessable Entity
{
  "error": "partySize mag niet groter zijn dan 20",
  "field": "partySize"
}

Reserveringen

Reserveringen ophalen

Queryparameters:

• date — filter op datum (YYYY-MM-DD)
• status — confirmed | pending | seated | completed | cancelled | no_show
• limit — max resultaten per pagina (standaard: 50, max: 200)
• cursor — paginering cursor uit vorige response

curl "https://app.couverto.nl/api/v2/reservations?date=2026-03-27&status=confirmed" \
  -H "Authorization: Bearer ck_live_..."

// Response
{
  "data": [
    {
      "id": "res_01j...",
      "date": "2026-03-27",
      "time": "19:00",
      "partySize": 4,
      "status": "confirmed",
      "guestName": "Jan Vermeer",
      "guestEmail": "jan@voorbeeld.nl",
      "shiftName": "Diner",
      "notes": "Allergie: noten"
    }
  ],
  "nextCursor": "cur_01j...",
  "total": 47
}

Reservering aanmaken

curl -X POST https://app.couverto.nl/api/v2/reservations \
  -H "Authorization: Bearer ck_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-03-28",
    "time": "19:30",
    "partySize": 2,
    "shiftId": "shift_01j...",
    "guestName": "Sophie Bakker",
    "guestEmail": "sophie@voorbeeld.nl",
    "guestPhone": "+31612345678",
    "notes": "Verjaardag"
  }'

Gasten

Queryparameters: search (naam/e-mail/telefoon), limit, cursor.

Beschikbaarheid

curl "https://app.couverto.nl/api/v2/availability?date=2026-03-28&partySize=4" \
  -H "Authorization: Bearer ck_live_..."

Webhooks

Webhooks sturen real-time HTTP POST-verzoeken naar jouw endpoint bij elke relevante actie. Registreer een endpoint via de API of via het dashboard.

Webhook events

Signing & verificatie

Elk webhook-verzoek bevat een X-Couverto-Signature header: een HMAC-SHA256 handtekening van de request body met jouw webhook-secret. Verifieer dit altijd om nep-verzoeken te blokkeren.

// Node.js voorbeeld
const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Rate limits

De API hanteert een limiet van 120 verzoeken per minuut per API-sleutel. Bij overschrijding ontvang je een 429 respons met een Retry-After header.

Versioning

De huidige API-versie is v2. Wijzigingen die backwards-incompatibel zijn, worden aangekondigd via e-mail met minimaal 30 dagen vooraankondiging. De v1 API is alleen beschikbaar voor de widget (publiek, geen authenticatie).