Pour les logiciels de planning

API des réservations du jour

Affichez dans votre logiciel le nombre de réservations et de personnes attendues aujourd’hui dans un restaurant qui utilise la réservation en ligne Sporkoo.

Comment ça marche

Le restaurateur crée lui-même sa clé dans son espace : Réservations › Réglages › Généraux › « Brancher un logiciel de planning ». Il la communique au logiciel, qui la garde côté serveur.
La clé commence par spk_. Elle ne donne accès qu’aux réservations de son restaurant, en lecture seule.
Aucune donnée personnelle n’est renvoyée : ni nom, ni téléphone, ni e-mail de client.
Le restaurateur peut révoquer ou remplacer sa clé à tout moment ; l’ancienne cesse alors de fonctionner.

Requête

GET https://sporkoo.tn/api/v1/reservations/jour?date=AAAA-MM-JJ
Authorization: Bearer spk_xxxxxxxxxxxxxxxx

date est facultative : sans elle, c’est aujourd’hui, à l’heure de Tunis (Africa/Tunis). Les réponses ne sont pas mises en cache.

curl -H "Authorization: Bearer spk_xxxxxxxxxxxxxxxx" \
  "https://sporkoo.tn/api/v1/reservations/jour?date=2026-10-14"

Réponse (200)

{
  "date": "2026-10-14",
  "timezone": "Africa/Tunis",
  "restaurant": { "id": "aB3dE5fG7hJ9kL1m", "name": "Chez Exemple" },
  "totals":  { "reservations": 2, "covers": 7 },
  "pending": { "reservations": 2, "covers": 7 },
  "slots": [
    { "time": "13:00", "reservations": 1, "covers": 4 },
    { "time": "20:00", "reservations": 1, "covers": 3 }
  ]
}

Champ	Sens
`totals.reservations`	Réservations confirmées du jour. À utiliser comme nombre de tables : une réservation = une table (voir la remarque ci-dessous).
`totals.covers`	Nombre de personnes attendues (confirmées).
`slots`	Le même détail, heure par heure, trié par heure.
`pending`	Demandes que le restaurant n’a pas encore acceptées. Elles ne sont pas comptées dans `totals` : à afficher à part ou à ignorer.

Les réservations annulées, refusées ou expirées ne sont jamais comptées. Les heures sont celles de Tunis.

Sporkoo ne gère pas encore les tables : la capacité d’un restaurant se règle en nombre de couverts. Le nombre de réservations confirmées est donc la meilleure approximation du nombre de tables. Un vrai nombre de tables viendra avec le plan de salle.

Erreurs

Code	Cause
`401`	Clé absente, mal formée, inconnue ou révoquée.
`400`	Date invalide (format attendu `AAAA-MM-JJ`).

Le corps de l’erreur est de la forme { "error": "…" }.

Bonnes pratiques

Gardez la clé côté serveur, jamais dans une application mobile ni une page web.
Interrogez l’API à la demande ou toutes les quelques minutes, pas en boucle serrée. Une limitation de débit pourra être ajoutée.
En cas de 401, demandez une nouvelle clé au restaurateur.

Une question ? Écrivez-nous à [email protected].