Skip to main content
Version: 2026.001.000

GraphQL API

The Smart WebAPI GraphQL endpoint is implemented using Microsoft Data API builder (DAB). The GraphQL API exposes all DTO entities made available by the integration services; see Swagger for the list of integration services. The available entities are not determined by a separately published schema. DAB provides the GraphQL layer and translates queries into operations against the underlying data source. Field names and relationships must match the GraphQL contract exposed by the endpoint.

Endpoint and request​

Send GraphQL requests using POST to:

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

The request body is JSON with a query property. If the query declares variables, pass their values separately in the variables property. For example:

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 } } }"
}

Use the Bearer token obtained during the login flow. As with the other WebAPI endpoints, provide Authorization-Scope with the environment value required by the service. For details, see the authentication guide. Do not embed tokens in the query or expose them in client-side logs.

Query behavior​

  • A GraphQL operation selects only the entities and fields needed by the client. Field names and relationships must match the schema exposed by the endpoint.
  • Use GraphQL variables for dynamic values, such as the $id parameter in the example, and provide them in the JSON variables object. This avoids building query strings by concatenating user input.
  • Aliases rename fields in the response; they do not change the underlying entity or field. For example, Righe: and Testata: name the two result fields, while NumDoc: renames DocumentId inside the grouped result.
  • filter restricts results, orderBy defines their order, and first limits the number of records returned. See the DAB documentation for filtering, sorting, and page size.
  • When a paginated result includes hasNextPage: true, use its endCursor as the after argument in the next request. See GraphQL pagination.
  • A response contains data when results are available and may contain errors when one or more fields fail. Check errors in addition to the HTTP status; a successful HTTP transport alone does not guarantee that every field resolved successfully.

Example: grouped order lines and document headers​

The query below groups order lines by document and item, and retrieves up to five document headers in the selected date range.

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
  }
}

Pass a value for $id in the request body, for example "variables": { "id": 100 }, using a value compatible with the Decimal scalar. In the Testata result, hasNextPage and endCursor support retrieval of subsequent pages.

Note: count(field: DO30_ID) counts matching values; the alias quantitaTotale does not make it a quantity sum. To calculate a total quantity, use sum on the appropriate quantity field if that field and aggregation are available in the published schema. DAB aggregation support depends on the database provider: see GraphQL aggregation and DAB feature availability. Verify groupBy, aggregation fields, and relationships against the schema of the target environment.

Further reading​