> ## Documentation Index
> Fetch the complete documentation index at: https://api-doc.xmenu.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Elenco ordini

> Recupera un elenco paginato di ordini del ristorante. È possibile filtrare gli ordini per intervallo di date.



## OpenAPI

````yaml openapi-it.json GET /orders/list
openapi: 3.1.0
info:
  title: xMenu API
  description: API Pubblica xMenu - Endpoint REST e notifiche webhook
  version: 1.0.0
servers:
  - url: https://app.xmenu.it/api
    description: xMenu API Production
security: []
paths:
  /orders/list:
    get:
      tags:
        - Consultazione Ordini
      summary: Elenco ordini
      description: >-
        Recupera un elenco paginato di ordini del ristorante. È possibile
        filtrare gli ordini per intervallo di date.
      operationId: ordersList
      parameters:
        - name: restuid
          in: query
          required: false
          schema:
            type: string
          description: >-
            Identificatore univoco ristorante (non richiesto con autenticazione
            `X-Client-Id`)
        - name: page
          in: query
          required: true
          schema:
            type: integer
            minimum: 1
          description: Numero di pagina da recuperare
        - name: pagesize
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
          description: 'Numero di risultati per pagina (default: 100, massimo: 100)'
        - name: date_from
          in: query
          required: false
          schema:
            type: string
            format: date
          description: 'Ordini dalla data specificata (formato: YYYY-MM-dd)'
        - name: date_to
          in: query
          required: false
          schema:
            type: string
            format: date
          description: 'Ordini fino alla data specificata (formato: YYYY-MM-dd)'
      responses:
        '200':
          description: Lista ordini recuperata con successo
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrdersListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      security:
        - apiKey: []
        - clientId: []
          clientSecret: []
        - oauth2: []
components:
  schemas:
    OrdersListResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
          description: >-
            Risultato dell'operazione: `true` se ha avuto successo, `false` se è
            fallita
        error:
          type: string
          description: >-
            Codice errore se l'operazione è fallita.


            Vedi [Codici errore](/docs/it/overview/error-codes) per i codici
            errore generali che possono verificarsi.
        message:
          type: string
          description: Descrizione leggibile dell'errore se l'operazione è fallita
        page:
          type: integer
          description: Numero di pagina corrente (1-n)
        pagesize:
          type: integer
          description: Numero massimo di elementi per pagina
        total_count:
          type: integer
          description: Conteggio totale dei risultati
        more:
          type: boolean
          description: '`false` = ultima pagina; `true` = esistono ulteriori risultati'
        orders:
          type: array
          description: Array di oggetti ordine
          items:
            $ref: '#/components/schemas/Order'
    Order:
      type: object
      description: Oggetto ordine contenente tutti i dettagli dell'ordine
      required:
        - uid
        - token
        - date
        - date_iso
        - number
        - order_number
        - client
        - details
        - dmethod
        - fee
        - payment_method
        - paid
        - total
        - currency
        - closed
      properties:
        uid:
          type: string
          description: Identificatore univoco dell'ordine
        token:
          type: string
          description: Token dell'ordine
        date:
          type: string
          description: Timestamp di arrivo dell'ordine
        date_iso:
          type: string
          format: date-time
          description: Data e ora di arrivo dell'ordine in formato ISO 8601
        subrestaurant_code:
          type: string
          description: Codice del sotto-ristorante (per configurazioni multi-locale)
        subrestaurant_uid:
          type: string
          description: Identificatore univoco del sotto-ristorante
        number:
          type: integer
          description: Numero sequenziale giornaliero interno
        order_number:
          type: string
          description: Numero completo dell'ordine (es. LOC-42)
        client:
          $ref: '#/components/schemas/Client'
        details:
          type: array
          description: Prodotti ordinati con opzioni e quantità
          items:
            $ref: '#/components/schemas/OrderDetail'
        customfields:
          type: array
          description: Campi personalizzati dell'ordine compilati
          items:
            $ref: '#/components/schemas/OrderCustomField'
        notes:
          type: string
          description: Note del cliente
        dmethod:
          type: string
          enum:
            - '0'
            - '1'
            - 0t
            - '20'
            - 0e-{id}
            - dcf-{id}
          description: |-
            Codice metodo di consegna:
            - `0`: Ritiro
            - `1`: Consegna a domicilio
            - `0t`: Ordine al tavolo
            - `20`: Ritiro presso un punto consegna
            - `0e-{id}`: Evento (es. 0e-123)
            - `dcf-{id}`: Metodo personalizzato (es. dcf-456)
        pickup:
          $ref: '#/components/schemas/PickupInfo'
        delivery:
          $ref: '#/components/schemas/DeliveryInfo'
        payment_method:
          type: string
          enum:
            - cash
            - paypal
            - stripe
            - satispay
            - xpay
            - day
            - edenred
            - postfinance
            - postfinance_new
            - invoice
          description: |-
            Metodo di pagamento utilizzato per l'ordine:
            - `cash`: Alla consegna
            - `paypal`: PayPal
            - `stripe`: Stripe
            - `satispay`: Satispay
            - `xpay`: Nexi XPay
            - `day`: Buoni pasto Day
            - `edenred`: Buoni pasto Edenred
            - `postfinance`: PostFinance
            - `postfinance_new`: PostFinance (nuovo)
            - `invoice`: Fattura a fine mese
        payment_method_sub:
          type: string
          enum:
            - cash
            - card
            - ticketrest
            - ticketrest-paper
            - ticketrest-electronic
          description: >-
            Sotto-metodo di pagamento per dettagli aggiuntivi (usato quando
            payment_method è cash):

            - `cash`: Contanti

            - `card`: Bancomat/Carta

            - `ticketrest`: Ticket Restaurant

            - `ticketrest-paper`: Ticket Restaurant cartaceo

            - `ticketrest-electronic`: Ticket Restaurant elettronico
        paid:
          type: boolean
          description: Stato del pagamento (true se già pagato online)
        coupon:
          $ref: '#/components/schemas/Coupon'
        total:
          type: number
          description: Importo totale dell'ordine
        confirmation:
          $ref: '#/components/schemas/Confirmation'
        currency:
          type: string
          description: Codice valuta (es. EUR)
        closed:
          type: boolean
          description: 'Stato dell''ordine: false se attivo, true se archiviato'
    Client:
      type: object
      description: Dati del cliente
      required:
        - uid
        - first_name
        - last_name
        - phone
        - email
      properties:
        uid:
          type: string
          description: Identificatore univoco del cliente
        first_name:
          type: string
          description: Nome del cliente
        last_name:
          type: string
          description: Cognome del cliente
        phone:
          type: string
          description: Numero di telefono del cliente
        email:
          type: string
          format: email
          description: Indirizzo email del cliente
    OrderDetail:
      type: object
      description: Prodotto ordinato con opzioni e quantità
      required:
        - product
        - options
        - price
        - price_options
        - quantity
        - total
      properties:
        product:
          $ref: '#/components/schemas/Product'
        options:
          type: array
          description: Opzioni prodotto selezionate
          items:
            $ref: '#/components/schemas/Option'
        price:
          type: number
          description: Prezzo unitario base
        price_options:
          type: number
          description: Prezzo incluse le opzioni selezionate
        quantity:
          type: integer
          description: Quantità ordinata
        free_quantity:
          type: integer
          description: Quantità gratuita (da promozioni)
        total:
          type: number
          description: Totale della riga
        notes:
          type: string
          description: Note specifiche del cliente per il prodotto
    OrderCustomField:
      type: object
      description: Campo personalizzato dell'ordine compilato
      required:
        - uid
        - name
        - type
        - value
      properties:
        uid:
          type: string
          description: UID campo personalizzato
        name:
          type: string
          description: >-
            Nome campo personalizzato. Se il nome del campo ha traduzioni,
            questo è il valore nella lingua predefinita del ristorante.
        type:
          type: string
          enum:
            - text
            - select
            - dateselect
          description: |-
            Tipo campo personalizzato:
            - `text` = Campo di testo libero
            - `select` = Menu a tendina con opzioni predefinite
            - `dateselect` = Selettore di data
        value:
          type: string
          description: >-
            Valore salvato del campo personalizzato. Per i campi `select` è la
            chiave dell'opzione selezionata (vedi `display_value` per
            l'etichetta); per i campi `dateselect` è la data salvata.
        display_value:
          type: string
          description: >-
            Versione leggibile di `value`, restituita solo quando differisce dal
            `value` grezzo. Per i campi `dateselect` è la data formattata in
            forma estesa. Per i campi `select` è l'etichetta dell'opzione
            selezionata; viene omessa quando quell'opzione non esiste più (es. è
            stata rimossa dopo l'invio dell'ordine), quindi i consumatori devono
            usare come fallback la chiave grezza in `value`.
    PickupInfo:
      type: object
      description: Informazioni sull'orario di ritiro
      required:
        - date
        - date_iso
      properties:
        date:
          type: string
          description: Data e ora programmate per il ritiro
        date_iso:
          type: string
          format: date-time
          description: Data e ora programmate per il ritiro in formato ISO 8601
    DeliveryInfo:
      type: object
      description: Informazioni su orario e indirizzo di consegna
      required:
        - date
        - address
        - fee
      properties:
        date:
          type: string
          description: >-
            Data e ora programmate per la consegna, oppure 'asap' per consegna
            immediata
        date_iso:
          type: string
          format: date-time
          description: >-
            Data e ora programmate per la consegna in formato ISO 8601 (assente
            se date è 'asap')
        address:
          $ref: '#/components/schemas/Address'
        deliverypoint:
          $ref: '#/components/schemas/Deliverypoint'
        fee:
          type: number
          description: Costo di consegna
    Coupon:
      type: object
      description: Dettagli del coupon sconto applicato
      required:
        - code
        - description
        - discount
        - auto
      properties:
        code:
          type: string
          description: Codice coupon
        description:
          type: string
          description: Descrizione del coupon
        discount:
          type: number
          description: Importo dello sconto
        auto:
          type: boolean
          description: Indica se il coupon è stato applicato automaticamente
    Confirmation:
      type: object
      description: >-
        Dettagli del sistema di conferma ordine (presente solo quando il sistema
        di conferma è attivo)
      required:
        - confirmed
        - countdown_time
        - countdown_started
        - closed
      properties:
        confirmed:
          type: boolean
          description: Se l'ordine è stato confermato
        date:
          type: string
          description: Data e ora confermate per consegna/ritiro
        date_iso:
          type: string
          format: date-time
          description: Data e ora confermate in formato ISO 8601
        text:
          type: string
          description: Messaggio di conferma inviato al cliente
        countdown_time:
          type: integer
          description: Tempo del conto alla rovescia in minuti
        countdown_started:
          oneOf:
            - type: string
            - type: boolean
              const: false
          description: >-
            Data e ora di inizio del countdown, oppure false se il countdown non
            è stato avviato
        countdown_started_iso:
          type: string
          format: date-time
          description: Data e ora di inizio del countdown in formato ISO 8601
        countdown_end:
          type: string
          description: Data e ora di scadenza del countdown
        countdown_end_iso:
          type: string
          format: date-time
          description: Data e ora di scadenza del countdown in formato ISO 8601
        timeout:
          type: boolean
          description: Se l'ordine è scaduto (non confermato in tempo)
        closed:
          type: boolean
          description: Se l'ordine è chiuso/archiviato
    Product:
      type: object
      description: Informazioni sul prodotto
      required:
        - uid
        - name
        - price
      properties:
        uid:
          type: string
          description: Identificatore univoco del prodotto
        name:
          type: string
          description: Nome del prodotto
        price:
          type: number
          description: Prezzo base del prodotto
        category:
          type: string
          description: Nome della categoria
        category_uid:
          type: string
          description: Identificatore univoco della categoria
        offline_uid:
          type: string
          description: Identificatore sistema gestionale/POS esterno
        ext_id:
          $ref: '#/components/schemas/ExtId'
    Option:
      type: object
      description: Opzione prodotto con valori selezionati
      required:
        - uid
        - name
        - type
        - values
      properties:
        uid:
          type: string
          description: Identificatore univoco dell'opzione
        name:
          type: string
          description: Titolo dell'opzione
        type:
          type: string
          enum:
            - single
            - multiple
          description: |-
            Tipo di opzione:
            - `single`: Scelta singola
            - `multiple`: Scelta multipla
        ext_id:
          $ref: '#/components/schemas/ExtId'
        values:
          type: array
          description: Valori opzione selezionati
          items:
            $ref: '#/components/schemas/OptionValue'
    Address:
      type: object
      description: Indirizzo di consegna
      required:
        - street
        - number
        - city
        - province
        - zip
        - country
        - place_id
        - lat
        - lng
        - kms
      properties:
        street:
          type: string
          description: Nome della via
        number:
          type: string
          description: Numero civico
        doorbell:
          type: string
          description: Nome sul campanello
        floor:
          type: string
          description: Piano
        city:
          type: string
          description: Città
        quarter:
          type: string
          description: Quartiere
        province:
          type: string
          description: Provincia
        zip:
          type: string
          description: CAP
        country:
          type: string
          description: Paese
        place_id:
          type: string
          description: Identificatore univoco dell'indirizzo validato
        lat:
          type: number
          description: Coordinata latitudine
        lng:
          type: number
          description: Coordinata longitudine
        kms:
          type: number
          description: Distanza in chilometri dal ristorante
    Deliverypoint:
      type: object
      description: Punto di consegna preconfigurato
      required:
        - name
        - full_address
      properties:
        name:
          type: string
          description: Nome del punto di consegna
        full_address:
          type: string
          description: Indirizzo completo del punto di consegna
    ExtId:
      type: string
      description: >-
        Disponibile in caso di richiesta con autenticazione via API Client: ID
        esterno passato in fase di importazione menu
    OptionValue:
      type: object
      description: Valore opzione selezionato
      required:
        - uid
        - name
        - price_operator
        - price_operand
        - quantity
      properties:
        uid:
          type: string
          description: Identificatore univoco del valore opzione
        name:
          type: string
          description: Nome del valore opzione
        price_operator:
          type: string
          enum:
            - +
            - '-'
            - '*'
            - /
          description: |-
            Operatore modifica prezzo:
            - `+`: Addizione
            - `-`: Sottrazione
            - `*`: Moltiplicazione
            - `/`: Divisione
        price_operand:
          type: number
          description: Valore modifica prezzo
        quantity:
          type: integer
          description: Quantità selezionata
        offline_uid:
          type: string
          description: Identificatore sistema gestionale/POS esterno
        ext_id:
          $ref: '#/components/schemas/ExtId'
  responses:
    Unauthorized:
      description: Autenticazione fallita.
      content:
        application/json:
          schema:
            oneOf:
              - type: object
                description: >-
                  Formato errore standard (quando si usa autenticazione API Key
                  o Client ID/Secret)
                required:
                  - success
                  - error
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    description: Sempre false per gli errori
                  error:
                    type: string
                    enum:
                      - RESTAURANT_NOT_FOUND
                      - INVALID_KEY
                      - INVALID_AUTH
                    description: Codice errore
                  message:
                    type: string
                    description: Descrizione errore leggibile
              - type: object
                description: >-
                  Formato errore OAuth (quando si usa l'autenticazione Bearer
                  token)
                required:
                  - error
                properties:
                  error:
                    type: string
                    enum:
                      - invalid_token
                      - invalid_request
                    description: Codice errore OAuth (RFC 6749)
                  error_description:
                    type: string
                    description: Descrizione errore leggibile
          examples:
            standard:
              summary: Formato errore standard (API Key / Client ID+Secret)
              value:
                success: false
                error: INVALID_KEY
                message: La chiave API fornita non è valida
            oauth:
              summary: Formato errore OAuth (Bearer token)
              value:
                error: invalid_token
                error_description: Access token non valido o scaduto
    Forbidden:
      description: Autorizzazione fallita - permessi insufficienti o accesso negato.
      content:
        application/json:
          schema:
            oneOf:
              - type: object
                description: >-
                  Formato errore standard (quando si usa autenticazione API Key
                  o Client ID/Secret)
                required:
                  - success
                  - error
                properties:
                  success:
                    type: boolean
                    enum:
                      - false
                    description: Sempre false per gli errori
                  error:
                    type: string
                    enum:
                      - API_DISABLED
                      - INSUFFICIENT_SCOPE
                      - UNAUTHORIZED
                    description: Codice errore
                  message:
                    type: string
                    description: Descrizione errore leggibile
              - type: object
                description: >-
                  Formato errore OAuth (quando si usa l'autenticazione Bearer
                  token)
                required:
                  - error
                properties:
                  error:
                    type: string
                    enum:
                      - insufficient_scope
                      - invalid_request
                    description: Codice errore OAuth (RFC 6749)
                  error_description:
                    type: string
                    description: Descrizione errore leggibile
          examples:
            standard:
              summary: Formato errore standard (API Key / Client ID+Secret)
              value:
                success: false
                error: API_DISABLED
                message: L'accesso API non è abilitato per il ristorante
            oauth:
              summary: Formato errore OAuth (Bearer token)
              value:
                error: insufficient_scope
                error_description: 'Permessi mancanti richiesti: write:orders'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Chiave API del ristorante. Può essere ottenuta da Strumenti > Accesso
        API nella dashboard xMenu.
    clientId:
      type: apiKey
      in: header
      name: X-Client-Id
      description: >-
        Client ID per l'autenticazione API Client (deve essere usato insieme al
        Client Secret)
    clientSecret:
      type: apiKey
      in: header
      name: X-Client-Secret
      description: >-
        Client Secret per l'autenticazione API Client (deve essere usato insieme
        al Client ID)
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://app.xmenu.it/oauth/token
          scopes: {}
      description: >-
        Autenticazione OAuth 2.0 utilizzando il flusso client credentials. Il
        token di accesso deve essere incluso nell'header Authorization come
        Bearer token.

````