Strumenti

Tutti gli strumenti sono limitati all’account autenticato; venueId restringe a un locale su quell’account e viene rifiutato (NOT_FOUND) per qualsiasi altro. Ogni strumento restituisce l’envelope { data, meta }; ogni fallimento è un risultato isError.

Input condivisi

Questi parametri ricorrono tra gli strumenti e si comportano allo stesso modo ovunque.

Parametro	Tipo	Note
`page`	integer ≥ 1	Default `1`
`limit`	integer 1-100	Default per strumento sotto; `list-top-products` limita a 25
`from`, `to`	string	`YYYY-MM-DD` o datetime ISO con `Z`/offset numerico (≤ 3 cifre frazionarie). I valori solo data sono date di calendario locali nel fuso orario effettivo, inclusive. Intervallo ≤ 90 date locali
`timezone`	Nome IANA	Sostituisce il fuso orario effettivo. Default: il fuso orario del locale quando è dato `venueId`, altrimenti `UTC`
`dateBasis`	enum	Quale timestamp filtra l’intervallo di date, consulta ogni strumento

Ogni enum sotto è una lista fissa validata dal server; qualsiasi altro valore viene rifiutato con INVALID_INPUT. I valori dei metodi di fulfillment, dove accettati, sono esattamente: InStore, Delivery, Pickup, Curbside, Billpay, CateringDelivery, CateringPickup.

Locali

`list-venues`

Lettura. Parti da qui: è come un agente scopre gli ID dei locali.

Input	Note
`archived`	`true` mostra solo i locali archiviati; default solo attivi
`page`, `limit`	Limit di default 100

Restituisce data.results[] di riepiloghi dei locali: id, name, slug, timezone, currency, indirizzo e capability di fulfillment.

`get-venue`

Lettura.

Input	Note
`venueId`	Obbligatorio

Restituisce il locale con indirizzo, orari di apertura per metodo di fulfillment, tempi di preparazione, commissioni di consegna e service charge.

Ordini

`list-orders`

Lettura. Gli ordini rifiutati e cancellati sono esclusi salvo che vengano selezionati con status. pagination.total può essere una stima; pagina con hasMore.

Input	Note
`venueId`	Opzionale
`status`	Stato esatto memorizzato: `New`, `Received`, `Pending`, `Accepted`, `Preparing`, `Ready For Pickup`, `Out for Delivery`, `Delivered`, `Complete`, `Rejected`, `Cancelled`, `Failed`, `Retrying`, `Syncing`
`fulfillmentMethod`	Vedi valori condivisi
`from`, `to`, `timezone`	Default ultime 7 date locali
`dateBasis`	`fulfillment` (default: tempo programmato, ripiegando sulla creazione) o `creation`
`page`, `limit`	Limit di default 50

`get-order`

Lettura.

Input	Note
`orderId`	ID ordine alfanumerico corto

Restituisce le voci con modificatori, il dettaglio dei prezzi (subtotale, commissione di consegna, service charge, mancia, sconto), cliente, tavolo/area, indirizzo di consegna e cronologia dei rimborsi.

`get-order-events`

Lettura. L’audit trail del ciclo di vita dell’ordine: cambi di stato, esiti del dispatch al POS, aggiornamenti di consegna.

Input	Note
`orderId`	Obbligatorio
`page`, `limit`	Limit di default 100

`list-menus`

Lettura.

Input	Note
`venueId`	Opzionale
`showArchived`	Default `false`
`page`, `limit`	Limit di default 100

Restituisce i menu con l’assegnazione al locale e lo stato attivo/archiviato. Lettura.

Input	Note
`menuId`	ID menu (string)

Restituisce categorie con ordine di visualizzazione, e prodotti con prezzi, disponibilità, tracciamento dell’inventario e tag. Non paginato.

Snooze

`get-snooze-report`

Lettura. Gli snooze che si sovrappongono all’intervallo. Il riepilogo e la time series coprono l’intero intervallo; gli item sono paginati.

Input	Note
`venueId`	Opzionale
`from`, `to`, `timezone`	Default ultime 7 date locali
`source`	`manual`, `deliverect`, `lightspeed`, `zonal`
`includeEvents`	Eventi on/off per item; default `false`
`eventLimit`	1-100, default 100. Gli item che lo superano sono contrassegnati `eventsTruncated`
`page`, `limit`	Limit di default 50

Statistiche

`get-order-stats`

Lettura. Conteggio degli ordini, somma dei totali degli ordini e valore medio dell’ordine per momento di creazione dell’ordine, insieme al periodo precedente di uguale lunghezza. I totali escludono gli ordini rifiutati/cancellati e non sono al netto dei rimborsi (un’entry meta.warnings lo dice). Su un account i cui locali usano più di una valuta, venueId è obbligatorio (INVALID_INPUT).

Input	Note
`venueId`	Opzionale, vedi sopra
`period`	1-90 date locali oggi incluso; default 30. Non con `from`/`to`
`from`, `to`, `timezone`	Alternativa a `period`

`list-top-products`

Lettura. Prodotti classificati per quantità venduta, per momento di creazione dell’ordine. I prezzi sono i prezzi correnti del catalogo, non i prezzi storici di vendita. Gli account multi-valuta devono passare venueId.

Input	Note
`venueId`	Opzionale, vedi sopra
`from`, `to`, `timezone`	Default ultime 30 date locali
`page`, `limit`	Limit di default 10, max 25

Sconti

`list-discount-codes`

Lettura.

Input	Note
`venueId`	Codici assegnati a questo locale
`showArchived`	Default `false`
`page`, `limit`	Limit di default 100

Restituisce codice, tipo, importo, statistiche di utilizzo e date di validità.

`create-discount-code`

Scrittura. readOnlyHint: false, idempotentHint: false. Il codice deve essere univoco per locale (CONFLICT altrimenti) ed è memorizzato in minuscolo.

Input	Note
`code`	Obbligatorio
`type`	`fixed`, `percent`, `buyonegetonefree`, `freedelivery`
`codeAmount`	Unità minori per `fixed`; decimi di percentuale per `percent` (`100` = 10%); `0` per gli altri due
`venues[]`	Obbligatorio, ≥ 1: `{ id, enabled? }` (`enabled` default `true`)
`description`	Opzionale
`usageLimit`	Utilizzi totali; `0` = illimitato (default)
`usageLimitPerUser`	Per email cliente; `0` = illimitato (default)
`minimumAmount`	Subtotale minimo, unità minori; default `0`
`maxDiscountAmount`	Limite sullo sconto, unità minori; `0` = nessun limite
`startDate`, `endDate`	Timestamp ISO con offset; ometti per immediato / nessuna scadenza. `endDate` deve seguire `startDate`
`fulfillmentMethods[]`	Limita ai metodi; ometti per tutti
`autoApply`	Applica automaticamente al checkout; default `false`

Restituisce il codice sconto creato in data.

Rimborsi

`list-refunds`

Lettura. Solo rimborsi andati a buon fine.

Input	Note
`venueId`	Obbligatorio
`from`, `to`, `timezone`	Default ultime 7 date locali
`dateBasis`	`refund` (default: quando è stato effettuato il rimborso) o `creation` (quando è stato effettuato l’ordine originale)
`page`, `limit`	Limit di default 50

Pay at Table

`list-bills`

Lettura. Conti per momento di creazione.

Input	Note
`venueId`	Obbligatorio
`status`	`open`, `closed`
`from`, `to`, `timezone`	Default ultime 7 date locali
`page`, `limit`	Limit di default 50

Restituisce stato, valuta, totale, importo dovuto, coperti e nome del tavolo.

Payment link

`list-payment-links`

Lettura.

Input	Note
`venueId`	Opzionale
`status`	`active`, `inactive`, `expired`, `completed`
`type`	`one_off`, `reusable`
`page`, `limit`	Limit di default 20

Restituisce i dettagli del link con le statistiche di pagamento.

`get-payment-link`

Lettura.

Input	Note
`id`	ID esterno, `plink_…`

`create-payment-link`

Scrittura. readOnlyHint: false, idempotentHint: false. Il link è attivo non appena viene creato.

Input	Note
`venueId`	Obbligatorio
`type`	`one_off` (si disattiva dopo un pagamento) o `reusable`
`amountType`	`fixed` o `variable`
`amount`	Unità minori, 1-1.000.000. Obbligatorio per `fixed`, vietato per `variable`
`title`	Obbligatorio, ≤ 255 caratteri
`description`, `reference`	Opzionali; `reference` ≤ 255 caratteri
`expiresAt`	Timestamp ISO con offset; ometti per nessuna scadenza
`minAmount`, `maxAmount`	Limiti per `variable`, unità minori, ≤ 1.000.000
`maxPayments`	Solo `reusable`; si disattiva dopo questo numero di pagamenti
`imageUrl`	URL mostrato al checkout
`successMode`	`thank_you` (default) o `redirect`
`successMessage`	Solo modalità `thank_you`
`successRedirectUrl`	Obbligatorio quando `successMode` è `redirect`
`collectBusinessName`, `collectCustomerName`, `collectEmail`, `collectPhone`	Booleani, default `false`

Restituisce il link creato in data. Attiva il webhook payment_link.created.

`get-payment-link-qr`

Lettura. L’unico strumento che restituisce un’immagine.

Input	Note
`id`	ID esterno, `plink_…`
`size`	Pixel, 100-2000; default 500

Il risultato porta i metadata di checkout in structuredContent (e nel blocco di testo JSON) più un blocco di contenuto MCP nativo image/png. Non c’è alcun campo base64 dentro data.

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

Input condivisi

Locali

`list-venues`

`get-venue`

Ordini

`list-orders`

`get-order`

`get-order-events`

Menu

`list-menus`

`get-menu`

Snooze

`get-snooze-report`

Statistiche

`get-order-stats`

`list-top-products`

Sconti

`list-discount-codes`

`create-discount-code`

Rimborsi

`list-refunds`

Pay at Table

`list-bills`

Payment link

`list-payment-links`

`get-payment-link`

`create-payment-link`

`get-payment-link-qr`

​Input condivisi

​Locali

​list-venues

​get-venue

​Ordini

​list-orders

​get-order

​get-order-events

​Menu

​list-menus

​get-menu

​Snooze

​get-snooze-report

​Statistiche

​get-order-stats

​list-top-products

​Sconti

​list-discount-codes

​create-discount-code

​Rimborsi

​list-refunds

​Pay at Table

​list-bills

​Payment link

​list-payment-links

​get-payment-link

​create-payment-link

​get-payment-link-qr

Input condivisi

Locali

`list-venues`

`get-venue`

Ordini

`list-orders`

`get-order`

`get-order-events`

Menu

`list-menus`

`get-menu`

Snooze

`get-snooze-report`

Statistiche

`get-order-stats`

`list-top-products`

Sconti

`list-discount-codes`

`create-discount-code`

Rimborsi

`list-refunds`

Pay at Table

`list-bills`

Payment link

`list-payment-links`

`get-payment-link`

`create-payment-link`

`get-payment-link-qr`