SPACE Developer API · Documentazione Alpha

01

Primo collegamento

Tre passaggi per verificare il token e conoscere il business a cui è collegato. Le API key vengono create o aggiornate dal pannello SPACE.

1

Configura una key

Nel pannello Developer API assegna soltanto gli scope necessari. Per chiavi esistenti puoi usare Gestisci permessi senza rigenerare il token.

2

Conserva il token lato server

La key è una credenziale segreta: non inserirla in browser, app pubbliche, QR code, repository o log applicativi.

3

Chiama whoami

Verifica business, scadenza, scope e capability prima di avviare una sincronizzazione reale.

GET · whoami.php

curl --request GET \
  --header "X-SPACE-API-Key: spx_live_..." \
  "https://space.techgamesitalia.it/api/integrations/v1/whoami.php"

PHP · server-side

<?php
$context = stream_context_create([
    'http' => [
        'method' => 'GET',
        'header' => "X-SPACE-API-Key: " . getenv('SPACE_API_KEY') . "\r\n",
        'ignore_errors' => true,
    ],
]);

$response = file_get_contents(
    'https://space.techgamesitalia.it/api/integrations/v1/whoami.php',
    false,
    $context
);

$data = json_decode($response ?: '', true);
?>

JavaScript · server runtime

const response = await fetch(
  'https://space.techgamesitalia.it/api/integrations/v1/whoami.php',
  {
    headers: {
      'X-SPACE-API-Key': process.env.SPACE_API_KEY,
    },
  }
);

const payload = await response.json();

Ogni risposta include X-SPACE-Request-Id. Conservalo quando apri una richiesta di supporto o devi correlare una chiamata nei log del tuo software.

02

Autenticazione

Tutte le richieste sono protette da API key. Puoi inviarla in un header dedicato oppure come Bearer token.

Header consigliato

Usa questo formato per chiarezza e semplicità nei log dell’integrazione.

HTTP header

X-SPACE-API-Key: spx_live_...

Bearer token supportato

Alternativa utile per SDK o middleware che usano già l’autenticazione Bearer.

HTTP header

Authorization: Bearer spx_live_...

La key dà accesso ai dati del business associato. Non esporla mai lato client. Una key sospetta può essere revocata dal pannello: le richieste future verranno bloccate immediatamente.

03

Scope e permessi

Ogni API key ha un set di capability esplicite. Gli scope nuovi non vengono mai assegnati automaticamente a chiavi già in uso.

meta.read

Base

Permette di chiamare whoami.php per conoscere business, chiave, scope e capability disponibili.

menus.read

Catalogo

Legge manifest e menu sorgente completo, incluse sezioni, prodotti, varianti, aggiunte, allergeni, ingredienti e disponibilità.

orders.read

Dati operativi

Legge ordini asporto e Self Order, stati, pagamento, tavolo, cliente, note, prodotti, modificatori e gruppi opzioni.

reservations.read

Dati operativi

Legge prenotazioni, coperti, cliente, contatti, note e assegnazione sala/tavolo quando disponibile.

orders.read e reservations.read includono dati operativi e dati cliente. Concedili solo a software autorizzati, con una policy di accesso e conservazione dati adeguata.

04

Mappa endpoint

Tutti gli endpoint sono GET, business-scoped e in sola lettura. La base URL è https://space.techgamesitalia.it.

Identità

GETmeta.read /api/integrations/v1/whoami.php

Business associato, scope assegnati e capability effettivamente abilitate.

Menu

GETmenus.read /api/integrations/v1/menus/manifest.php

Manifest leggero per capire se il menu è cambiato.

GETmenus.read /api/integrations/v1/menus/current.php

Documento menu sorgente completo, con ETag e 304.

Operatività

GETorders.read /api/integrations/v1/orders/index.php

Lista paginata di asporto e Self Order.

GETorders.read /api/integrations/v1/orders/view.php?id=123

Dettaglio ordine con prodotti, modificatori e opzioni.

GETreservations.read /api/integrations/v1/reservations/index.php

Lista paginata e filtrabile di prenotazioni.

GETreservations.read /api/integrations/v1/reservations/view.php?id=123

Dettaglio con assegnazione tavolo attiva, quando presente.

05

Ordini

La collection restituisce una sintesi pronta per sincronizzare asporto e Self Order. Il dettaglio aggiunge righe, modificatori e gruppi opzioni.

Lista ordini

GET /api/integrations/v1/orders/index.php

Richiede orders.read. Restituisce schema_version, business, array orders e metadati page.

Dettaglio ordine

GET /api/integrations/v1/orders/view.php?id=123

Accetta id oppure code, mai entrambi. Restituisce l’ordine completo con items, modifiers e option_groups.

Esempio lista ordini

curl --request GET \
  --header "X-SPACE-API-Key: spx_live_..." \
  "https://space.techgamesitalia.it/api/integrations/v1/orders/index.php?status=confirmed,preparing,ready&limit=50"

Parametro	Tipo	Descrizione
limit	1–100	Numero massimo di risorse per pagina. Default 50.
cursor	string	Cursor opaco restituito in data.page.next_cursor. Non costruirlo manualmente.
updated_after	ISO-8601	Restituisce risorse cambiate a partire dal checkpoint indicato.
status	CSV	pending, confirmed, preparing, ready, completed, cancelled, rejected, no_show
channel	CSV	takeaway per asporto oppure table per Self Order al tavolo.

Struttura sintetica ordine

{
  "id": 123,
  "code": "ORD-000123",
  "channel": "table",
  "fulfillment_type": "dine_in",
  "status": "confirmed",
  "customer": {
    "id": 54,
    "name": "Mario Rossi",
    "phone": "+39...",
    "email": "..."
  },
  "service": {
    "pickup_mode": null,
    "pickup_date": null,
    "pickup_time": null,
    "table": {
      "label": "Tavolo 12",
      "room_id": 3,
      "room_table_id": 28,
      "qr_mode": "single_qr"
    }
  },
  "payment": {
    "mode": "online_future",
    "status": "paid",
    "provider": "stripe",
    "paid_at": "2026-06-23T18:30:00+02:00"
  },
  "totals": {
    "subtotal": 19.50,
    "discount": 0,
    "total": 19.50,
    "currency": "EUR"
  },
  "changed_at": "2026-06-23T18:30:00+02:00"
}

07

Prenotazioni

Recupera agenda, cliente, coperti, note e assegnazione tavolo attiva. Le date vengono restituite nel contesto timezone del business.

Lista prenotazioni

GET /api/integrations/v1/reservations/index.php

Richiede reservations.read. Restituisce una pagina ordinata per ultima modifica, poi ID decrescente.

Dettaglio prenotazione

GET /api/integrations/v1/reservations/view.php?id=123

Richiede un ID SPACE valido. Include table_assignment quando la prenotazione ha un’assegnazione attiva.

Esempio agenda

curl --request GET \
  --header "X-SPACE-API-Key: spx_live_..." \
  "https://space.techgamesitalia.it/api/integrations/v1/reservations/index.php?date_from=2026-06-23&date_to=2026-06-24&status=pending,confirmed"

Parametro	Tipo	Descrizione
limit	1–100	Numero massimo di prenotazioni per pagina. Default 50.
cursor	string	Cursor opaco da data.page.next_cursor.
updated_after	ISO-8601	Checkpoint per sincronizzazioni incrementali.
status	CSV	pending, confirmed, cancelled, rejected, completed, no_show
date_from	YYYY-MM-DD	Include prenotazioni dalla data indicata.
date_to	YYYY-MM-DD	Include prenotazioni fino alla data indicata. Non può precedere date_from.

Struttura sintetica prenotazione

{
  "id": 145,
  "status": "confirmed",
  "source": "menu",
  "customer": {
    "id": 54,
    "name": "Giulia Rinaldi",
    "phone": "+39...",
    "email": "..."
  },
  "schedule": {
    "date": "2026-06-24",
    "time": "21:00",
    "people": 2,
    "timezone": "Europe/Rome"
  },
  "notes": "Tavolo vicino alla vetrata.",
  "table_assignment": {
    "id": 18,
    "room_id": 3,
    "room_name": "Sala interna",
    "room_table_id": 28,
    "table_code": "T12",
    "table_label": "Tavolo 12",
    "starts_at": "2026-06-24T21:00:00+02:00",
    "ends_at": "2026-06-24T22:30:00+02:00",
    "people": 2
  },
  "changed_at": "2026-06-23T18:30:00+02:00"
}

08

Sincronizzazione affidabile

Usa il cursor per attraversare una risposta lunga e updated_after per le sincronizzazioni successive. Il tuo software deve trattare l’ID SPACE come identità stabile.

Strategia raccomandata

PRIMA IMPORTAZIONE
1. Chiama /orders/index.php?limit=100
2. Salva ogni risorsa usando data.orders[].id come chiave esterna
3. Finché data.page.has_more è true:
   chiama la stessa collection con cursor=data.page.next_cursor
4. Al termine salva il valore changed_at più recente elaborato

SINCRONIZZAZIONI SUCCESSIVE
1. Chiama /orders/index.php?updated_after=<checkpoint ISO-8601>
2. Durante la paginazione non cambiare filtri o updated_after
3. Effettua upsert per id SPACE
4. Salva un nuovo checkpoint solo dopo aver elaborato tutte le pagine

STESSO MODELLO
- /reservations/index.php per prenotazioni
- /menus/manifest.php → /menus/current.php per il menu

Importante: updated_after è inclusivo. Conserva gli ID già elaborati o usa un piccolo overlap temporale e un upsert idempotente per gestire risorse aggiornate nello stesso istante.

09

ETag e risposte 304

Il menu completo e i dettagli di ordini e prenotazioni restituiscono un ETag. Riutilizzalo con If-None-Match per evitare download inutili.

If-None-Match

# Prima lettura: conserva l'header ETag della risposta 200
curl --include \
  --header "X-SPACE-API-Key: spx_live_..." \
  "https://space.techgamesitalia.it/api/integrations/v1/orders/view.php?id=123"

# Lettura successiva: invia lo stesso valore
curl --include \
  --header "X-SPACE-API-Key: spx_live_..." \
  --header 'If-None-Match: "sha256-del-documento"' \
  "https://space.techgamesitalia.it/api/integrations/v1/orders/view.php?id=123"

# Se non è cambiato: HTTP 304, senza body JSON

10

Errori e diagnosi

Gli errori sono JSON coerenti. Controlla il codice HTTP, error.code e il request ID.

HTTP	Codice	Significato
401	UNAUTHORIZED	API key mancante, non valida o scaduta.
403	FORBIDDEN	La key è valida ma non possiede lo scope richiesto.
404	ORDER_NOT_FOUND / RESERVATION_NOT_FOUND	Risorsa inesistente o non appartenente al business della key.
422	INVALID_QUERY	Parametro non valido, ad esempio ID errato o filtri in conflitto.
429	RATE_LIMITED	Troppi tentativi. Rispetta l’header Retry-After.
503	API_NOT_READY / ORDERS_NOT_READY	Modulo o ambiente non ancora disponibile.

Errore standard

{
  "ok": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Scope API non autorizzato.",
    "request_id": "req_..."
  }
}

11

Sicurezza e confini

La Developer API è progettata per sincronizzazione server-to-server. È in Alpha e non espone funzioni di scrittura, credenziali locali o riferimenti sensibili ai provider di pagamento.

Ciò che l’API non espone

Credenziali Bridge e configurazioni stampanti locali.
Token, secret o payment reference Stripe.
IP hash, user agent e consensi CRM interni.
Accesso diretto al database SPACE.

Responsabilità dell’integratore

Conservare la key solo in un vault o nelle variabili ambiente server.
Applicare accessi minimi e cancellare dati non necessari.
Non condividere dati cliente con soggetti non autorizzati.
Gestire retry e upsert senza creare duplicati.

Dati del locale,
in orbita con SPACE.

Primo collegamento

Configura una key

Conserva il token lato server

Chiama whoami

Autenticazione

Header consigliato

Bearer token supportato

Scope e permessi

meta.read

menus.read

orders.read

reservations.read

Mappa endpoint

Menu

Manifest

Documento completo

Ordini

Lista ordini

Dettaglio ordine

Prenotazioni

Lista prenotazioni

Dettaglio prenotazione

Sincronizzazione affidabile

ETag e risposte 304

Errori e diagnosi

Sicurezza e confini

Ciò che l’API non espone

Responsabilità dell’integratore

Dati del locale,in orbita con SPACE.

Configura una key

Conserva il token lato server

Chiama whoami

Header consigliato

Bearer token supportato

meta.read

menus.read

orders.read

reservations.read

Manifest

Documento completo

Lista ordini

Dettaglio ordine

Lista prenotazioni

Dettaglio prenotazione

Ciò che l’API non espone

Responsabilità dell’integratore

Dati del locale,
in orbita con SPACE.