Vorrei Ordinare — API, Webhook & Integrazioni

Quickstart

curl -s "https://tuo-dominio/api_v2_registratori.php?limit=50&cursor=0" \
  -H "Authorization: Bearer LA_TUA_CHIAVE" | jq .

Ometti data per avere gli ordini da oggi 00:00:01. Persisti il cursor lato gestionale.

Endpoint API

• Ordini (pull): GET /api_v2_registratori.php — filtri limit, cursor, data.
• Webhook (push): evento order.created/order.updated con firma HMAC (vedi sotto).

Formato di data: YYYY-MM-DD. Charset UTF‑8, locale it‑IT.

Schema risposta (ridotto)

[
  {
    "id_ordini":"409",
    "totale":"22.00",
    "pagamento":"Alla consegna",
    "dataconsegna":"2025-10-31",
    "oraconsegna":"10:20",
    "tipo_ordine":"consegna",
    "note_preparazione":"",
    "note_consegna":"",
    "km": 201,
    "costo_consegna_commissioni": 2,
    "carrello":[{"id_prodotto":"1557-0","nome_prodotto":"Bianca con Prosciutto","prezzo":"2.00","varianti":[]}],
    "dati_utente":[{"first_name":"Mario","telefono":"3331234567","indirizzo":"Via Roma","numero_civico":"10","citta":"Roma","cap":"00186"}]
  }
]

Campi vuoti: stringa vuota "" o array []. Vedi pagina sviluppatori per lo schema completo.

Webhook (BETA)

Opzionale: inviamo una POST firmata al tuo endpoint quando arriva o cambia un ordine.

{
  "event": "order.created",
  "signature": "hmac_sha256_base64",
  "ts": 1732742400,
  "payload": { "id_ordini":"410", "stato":"nuovo", "totale":"18.00" }
}

// Verifica firma (PHP)
$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_VO_SIGNATURE'] ?? '';
$calc = base64_encode(hash_hmac('sha256', $raw, 'LA_TUA_CHIAVE_WEBHOOK', true));
if (!hash_equals($calc, $sig)) { http_response_code(401); exit; }
// Idempotenza: usa payload.ts + payload.id_ordini
http_response_code(200);

Abilitazione su richiesta. In alternativa, usa solo il polling con cursor.

Stampanti & Registratori

• Comande per reparto (cucina/bar/pizzeria) via print server.
• Registratori: integrazione BETA tramite endpoint V2.
• Righe scontrino: descrizione + varianti/aggiunte/rimozioni in nota riga.

Consigli: rete cablata, coda locale con retry, watchdog ping.

Sicurezza

• HTTPS obbligatorio. Auth Bearer o ?key=.
• Log con requestId (vedi intestazione pagina) e rotazione 30 giorni.
• Privacy by design: payload essenziale. Vedi Privacy e Cookie.

Riduci PII nei log: maschera email/telefono quando non servono in diagnostica.

Errori standard

403 {"errore":"Chiave_KEY_Errata","requestId":"..."}
500 {"errore":"DB_Conn_Error","dettaglio":"...","requestId":"..."}

HTTP code coerenti, messaggi sintetici, requestId per supporto.

Rate limit & Retry

• Client-side consigliato: max 2 req/sec.
• Backoff esponenziale: 250→2000 ms.
• Idempotenza su id_ordini e cursore persistente.

Avanza il cursore solo quando il documento è stampato/registrato.

Sandbox & Test

• Dataset fittizio con chiave dedicata.
• Esempi cURL / JS / PHP pronti.
• Supporto congiunto con fornitore cassa se necessario.

Richiedi sandbox

FAQ tecniche

Polling vs Webhook? Puoi partire solo con polling (limit + cursor). Il webhook è opzionale.

Varianti a scontrino? Inserisci varianti[] / aggiungere / rimuovere nella nota riga.

Multi-sede? Chiavi distinte o parametro filtro su richiesta (contattaci per enterprise).

Contatti tecnici

• Email: info@vorreiordinare.it
• Richiesta attivazione: contatti.php#attivazione
• API dettagliate: sviluppatori.php

Ultimo aggiornamento: 28/11/2025 — requestId: req_69371cb7d05476.88123217