Request Structure

7 min

Every request is a POST to the GraphQL endpoint (extension.apiURL).

POST https://sandbox.expressoft.eu/connect/api/interopgql
Authorization: Bearer <token>
Content-Type: application/json

Query

query GetOrganizations {
  miscellaneous {
    organizations {
      key
      name
      fiscalCode
    }
  }
}

cURL

curl --location 'https://sandbox.expressoft.eu/connect/api/interopgql' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{"query": "query GetOrganizations { miscellaneous { organizations { key name fiscalCode } } }"}'

Response

{
  "data": {
    "miscellaneous": {
      "organizations": [
        {
          "key": "00000000-0000-0000-0000-000000000001",
          "name": "Example Organization SRL",
          "fiscalCode": "12345678"
        }
      ]
    }
  }
}

Entry points

The schema has two roots, Queries (read) and Mutations (write). Each is organized in categories.

Query category	Contains
documents	Purchase invoices, sale invoices, transfers, consumption notes, production notes, inventory adjustments, business days, physical stocks
miscellaneous	Organizations, locations, payment methods, warehouses, currencies, consumption types, document cursors
products	Products (paged list)
companies	Companies, company categories
pms	Hotel module data: invoices, business days, receipts

Mutation category	Contains
documents	purchaseInvoiceCreate: create a purchase invoice
miscellaneous	changeDocumentCursor: change the position of the document sync cursor

Lists and paging

Most lists use cursor paging (the Relay style). They accept first, after, last and before, and return a connection:

totalCount
pageInfo {
  hasNextPage
  endCursor
}
items {
  key
}

To read the next page, send the endCursor of the previous page as after. Stop when hasNextPage is false.

The document lists also accept these filters:

Argument	Filters by
organization	The organization (a key, from miscellaneous.organizations).
dateBegin, dateEnd	The date of the document.
key	The key of one document.
nOK	The documents marked as NOK. See Document Cursor and Incremental Sync.

The PMS lists use page paging instead: cursor, pageSize, and a response with totalRecords and items. See PMS.

Mutation results

purchaseInvoiceCreate returns a wrapper:

result { key }
errorCode
errorMessage
errorData

errorCode is null when the operation succeeds. See Errors & Troubleshooting.

Common mistakes

Mistake	What happens
GET request on the endpoint	404
No Authorization header, or an expired token	An authorization error, no data
A user without the Accounting permission	An authorization error: Required claim 'ConnectAccounting' is not present
Unknown field or wrong type in the query	HTTP 200 with an errors array at the top level