Passa al contenuto principale
Versione: 2026.001.000

API GraphQL

L'endpoint GraphQL di Smart WebAPI è implementato tramite Microsoft Data API builder (DAB). L'API GraphQL espone tutte le entità DTO rese disponibili dai servizi di integrazione; per l'elenco dei servizi consultare Swagger. La disponibilità delle entità non è determinata da uno schema pubblicato separatamente. DAB fornisce il livello GraphQL e traduce le query in operazioni sulla sorgente dati sottostante. I nomi dei campi e le relazioni devono corrispondere al contratto GraphQL esposto dall'endpoint.

Endpoint e richiesta​

Inviare le richieste GraphQL con il metodo POST al seguente endpoint:

https://tse.smart-api.teamsystem.cloud/core/graphql

Il corpo della richiesta deve essere in formato JSON e contenere la proprietà query. Se la query dichiara variabili, passare i relativi valori separatamente nella proprietà variables. Esempio:

POST https://tse.smart-api.teamsystem.cloud/core/graphql
Authorization: Bearer <access-token>
Authorization-Scope: <environment>
Content-Type: application/json
Accept: application/json

{
  "query": "query { documentoTestataMGs(first: 5) { items { Id DocumentNumber } } }"
}

Usare il token Bearer ottenuto durante il flusso di autenticazione. Come per gli altri endpoint WebAPI, specificare Authorization-Scope con il valore dell'ambiente richiesto dal servizio. Per i dettagli, consultare la guida all'autenticazione. Non inserire i token nella query né esporli nei log lato client.

Comportamento delle query​

  • Un'operazione GraphQL seleziona solo le entità e i campi necessari al client. I nomi dei campi e delle relazioni devono corrispondere allo schema esposto dall'endpoint.
  • Usare le variabili GraphQL per i valori dinamici, ad esempio il parametro $id nell'esempio, e passarle nella proprietà JSON variables. In questo modo si evita di costruire query concatenando input dell'utente.
  • Gli alias rinominano i campi nella risposta, ma non modificano l'entità o il campo sottostante. Ad esempio, Righe: e Testata: assegnano un nome ai due campi restituiti, mentre NumDoc: rinomina DocumentId nel risultato raggruppato.
  • filter limita i risultati, orderBy ne definisce l'ordinamento e first imposta il numero massimo di record restituiti. Consultare la documentazione DAB per filtri, ordinamento e dimensione della pagina.
  • Se un risultato paginato include hasNextPage: true, usare il relativo endCursor come argomento after nella richiesta successiva. Vedere la documentazione sulla paginazione GraphQL.
  • La risposta contiene data quando sono disponibili risultati e può contenere errors se la risoluzione di uno o più campi non riesce. Verificare errors oltre allo stato HTTP: una richiesta HTTP completata correttamente non garantisce che tutti i campi siano stati risolti.

Esempio: righe raggruppate e testate documento​

La query seguente raggruppa le righe per documento e articolo e recupera fino a cinque testate documento nell'intervallo di date specificato.

query RigheRaggruppatePerDocumentoEArticolo($id: Decimal!) {
  Righe: documentoCorpoMGs(filter: { NetAmount: { gt: $id } }) {
    groupBy(fields: [DocumentId, ItemCode]) {
      records: fields {
        NumDoc: DocumentId
        Articolo: ItemCode
      }
      aggregations {
        quantitaTotale: count(field: DO30_ID)
      }
    }
  }
  Testata: documentoTestataMGs(
    first: 5
    orderBy: { DocumentDate: DESC }
    filter: { DocumentDate: { gte: "2021-01-01T00:00:00Z", lte: "2026-09-21T23:59:59Z" } }
  ) {
    items {
      Id
      DocumentNumber
      DocumentDate
      DocumentoTestataMG_CustomerSupplierCO {
        CustomerSupplierCO_GeneralMasterDataFKCO {
          LegalName
          VatNumber
        }
      }
    }
    hasNextPage
    endCursor
  }
}

Passare un valore per $id nel corpo della richiesta, ad esempio "variables": { "id": 100 }, usando un valore compatibile con lo scalare Decimal. Nel risultato Testata, hasNextPage ed endCursor consentono di recuperare le pagine successive.

Nota: count(field: DO30_ID) conta i valori corrispondenti; l'alias quantitaTotale non trasforma il conteggio in una somma delle quantità. Per calcolare una quantità totale, usare sum sul campo quantità appropriato, se il campo e l'aggregazione sono disponibili nello schema pubblicato. Il supporto alle aggregazioni di DAB dipende dal provider del database: consultare la documentazione sulle aggregazioni GraphQL e sulla disponibilità delle funzionalità DAB. Verificare groupBy, i campi di aggregazione e le relazioni nello schema dell'ambiente di destinazione.

Approfondimenti​