---
title: Request Structure
slug: devdocs/vFbp-request-structure
docTags: 
createdAt: 2026-10-22T08:35:59.012Z
---

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

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

**Query**

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

**cURL**

```bash
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**

```json
{
  "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:

```graphql
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:

```graphql
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                            |