> ## Documentation Index > Fetch the complete documentation index at: https://storekit.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Formato della risposta > L'envelope data-and-meta del merchant MCP: come vengono restituiti e parsati risultati, paginazione, intervalli di date, fusi orari, valute e immagini. Ogni chiamata a uno strumento andata a buon fine restituisce un envelope, consegnato due volte nel risultato MCP: come `structuredContent`, e come testo JSON del primo blocco di `content`. Leggi quello che il tuo client espone; sono identici. Ogni strumento pubblica un `outputSchema` corrispondente, così un client conforme alla specifica valida `structuredContent` contro di esso. ```json theme={null} { "data": { "results": [ { "id": 42, "name": "Soho", "timezone": "Europe/London", "currency": "GBP" } ] }, "meta": { "schemaVersion": 2, "timezone": "Europe/London", "dateRange": { "from": "2026-09-11T23:00:00.000Z", "to": "2026-09-18T22:59:59.999Z", "basis": "fulfillment", "endInclusive": true }, "pagination": { "page": 1, "limit": 50, "returned": 50, "total": 1240, "totalIsEstimate": true, "hasMore": true, "nextPage": 2, "truncated": true }, "warnings": [], "currencyCodes": ["GBP"] } } ``` ## `data` * Gli strumenti **list** restituiscono `data.results`, un array. * Gli strumenti **detail** (`get-venue`, `get-order`, `get-menu`, `get-payment-link`, `get-order-stats`, le due scritture) restituiscono il record stesso in `data`. * `get-snooze-report` restituisce insieme un riepilogo, una time series e un array `items` paginato. * I campi sono in allowlist per risorsa. Qualsiasi cosa non presente nell'`outputSchema` di uno strumento non viene mai inviata, indipendentemente da ciò che contiene il record sottostante. ## `meta` | Campo | Tipo | Significato | | - | - | - | | `schemaVersion` | `2` | Incrementato ad ogni breaking change all'envelope o alla forma di una risorsa | | `timezone` | Nome IANA o `null` | Il fuso orario in cui è stato interpretato l'intervallo di date | | `dateRange` | object o `null` | L'intervallo risolto e inclusivo effettivamente applicato, come istanti UTC, più il suo `basis` | | `pagination` | object o `null` | Presente sui risultati paginati | | `warnings` | `string[]` | Avvertenze leggibili, ad esempio che le statistiche sono al lordo dei rimborsi | | `currencyCodes` | `string[]`, opzionale | Codici ISO 4217 distinti presenti nel risultato | `meta` è strict: non compaiono chiavi non documentate, e nuove chiavi arrivano con un bump di versione. ## Paginazione Le pagine partono da **1**. `limit` è limitato a 100 (25 per `list-top-products`) e ridotto silenziosamente se ne chiedi di più. `hasMore` e `nextPage` derivano dal fetch di una riga oltre la pagina, quindi sono sempre esatti. `total` è `null` quando lo strumento non conta, e può essere contrassegnato `totalIsEstimate: true` su grandi liste di ordini dove un conteggio esatto è troppo lento. Guida i loop da `hasMore`, non da `total`: ```javascript theme={null} let page = 1; do { const { data, meta } = await call("list-orders", { venueId, from, to, page, limit: 100 }); process(data.results); page = meta.pagination.nextPage; } while (page !== null); ``` Le liste sono live; un record creato tra due pagine può spostare le pagine successive. ## Date e fusi orari Gli **input** (`from`, `to`) accettano: * `YYYY-MM-DD`: una data di calendario locale nel fuso orario effettivo, inclusiva a entrambe le estremità (`to: "2026-09-18"` arriva fino a `23:59:59.999` di quel giorno); oppure * un datetime ISO con `Z` o un offset numerico e al massimo tre cifre frazionarie, ad esempio `2026-09-18T14:00:00+01:00`. I datetime senza offset vengono rifiutati. Il **fuso orario effettivo** è `timezone` se fornito, altrimenti il fuso orario del locale quando è dato `venueId`, altrimenti `UTC`. `meta.timezone` indica sempre quale è stato usato. Gli intervalli possono coprire al massimo **90 date di calendario locali**; gli intervalli più lunghi vengono rifiutati con `INVALID_INPUT`. Ogni strumento ha un intervallo di default (7 o 30 date) e un `basis` (`creation`, `fulfillment`, `refund` o `snooze_overlap`) che indica quale timestamp filtra l'intervallo; consulta [Strumenti](/docs/it/developers/mcp/tools). `meta.dateRange` ripete l'intervallo risolto in modo che un client possa mostrare esattamente ciò che è stato conteggiato. Gli **input di scrittura** (`startDate`, `endDate`, `expiresAt`) devono essere timestamp ISO completi con offset. I valori solo data non sono accettati per le scritture. ## Valuta Tutti gli importi sono interi in **unità minori della valuta** (pence, cent) e non vengono mai convertiti. La valuta viaggia con i dati: come campo `currency` su locali, ordini, conti e link, e come `meta.currencyCodes` per il risultato nel suo complesso. `codeAmount` su uno sconto percentuale è in decimi di percentuale, non in un importo di valuta. Le statistiche a livello di account e le query sui top-product su un account i cui locali usano più di una valuta vengono rifiutate (`INVALID_INPUT`); passa `venueId`. ## Immagini `get-payment-link-qr` è l'unico strumento che restituisce dati binari. Il suo array `content` contiene il blocco di testo JSON seguito da un blocco immagine MCP nativo: ```json theme={null} { "type": "image", "mimeType": "image/png", "data": "" } ``` `structuredContent` porta solo l'URL di checkout e i metadata del link; non c'è alcun campo base64 dentro `data`. ## Errori Una chiamata fallita **non** è un envelope. È un risultato `isError: true` il cui singolo blocco di testo è un oggetto `{ error }`, senza `structuredContent`. Consulta [Errori](/docs/it/developers/mcp/errors). ## Related topics - [Panoramica del merchant MCP](/docs/it/developers/mcp/overview.md) - [Formato del payload](/docs/it/developers/webhooks/payload-format.md) - [Endpoint di polling](/docs/it/developers/webhooks/advanced/polling-endpoints.md) - [2. Imposta gli orari di apertura](/docs/it/getting-started/launch/set-opening-hours.md) - [Cosa vede il tuo cliente](/docs/it/payment-links/what-your-customer-sees.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.