### Make GET Request with cURL

Source: https://apis.e-conomic.com/index

Illustrates how to perform a GET request to the accounting years API using the cURL command-line tool. This example shows how to include the required authentication and accept headers directly in the command.

```bash
curl -H "X-AppSecretToken: demo" -H "X-AgreementGrantToken: demo" https://apis.e-conomic.com/accountingyearsapi/v2.0.1/the_resource

```

--------------------------------

### Make GET Request with jQuery

Source: https://apis.e-conomic.com/index

Demonstrates how to make a GET request to the accounting years API using jQuery's AJAX method. It includes setting necessary headers for authentication and content type, and handling the response by displaying it as a JSON string.

```javascript
$.ajax({
    url: "https://apis.e-conomic.com/accountingyearsapi/v2.0.1/the_resource",
    dataType: "json",
    headers: {
        'X-AppSecretToken': "demo",
        'X-AgreementGrantToken': "demo",
        'Accept': "application/json"
    },
    type: "GET"
})
    .always(function (data) {
    $("#output").text(JSON.stringify(data, null, 4));
});

```

--------------------------------

### GET /accountingYears/periods

Source: https://apis.e-conomic.com/index

Retrieves a paginated list of AccountingYearPeriods. Supports filtering, pagination, and sorting.

```APIDOC
## GET /accountingYears/periods

### Description
Use this endpoint to load a page of AccountingYearPeriods. Supports filtering, pagination, and sorting.

### Method
GET

### Endpoint
https://apis.e-conomic.com/accountingyearsapi/v2.0.1/accountingYears/periods

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Use this parameter to set the filtering for fields.
- **pageSize** (integer) - Optional - Default: 20. Use this parameter to set the page size. Max: 100.
- **skipPages** (integer) - Optional - Default: 0. Use this parameter to set number of pages to skip.
- **sort** (string) - Optional - Use this parameter to set the sort fields and direction.

### Responses
#### Success Response (200)
- **cursor** (string or null) - Continuation cursor for retrieving the next page of results. Not returned if there are no more items.
- **items** (Array of objects or null) - An array of AccountingYearPeriod objects. Max items returned is 1000.

##### Response Schema (items object):
- **dateFrom** (string) - Required - The first date in the period.
- **dateTo** (string) - Required - The last date in the period.
- **isBarred** (boolean) - Required - Whether the period is barred or not.
- **isClosed** (boolean) - Required - Whether the period is closed or not.
- **periodNumber** (integer) - Required - The unique number of the accounting year.
- **objectVersion** (string or null) - The object version, required for PUT requests.
- **year** (string or null) - The year of the period.

#### Error Responses
- **400 Bad Request**: Your request does not pass our validation. Check the errors array for more details.
- **401 Unauthorized Access**: Please consult the e-conomic API documentation for authorization details.
- **403 Access Forbidden**: You do not have access to this resource based on your granted roles.
- **429 Too Many Requests**: You have exceeded your API quota. Please wait before making further requests.
- **500 Internal Server Error**: An unexpected error occurred. Please contact api@e-conomic.com with details.

### Request Example
```json
{
  "cursor": "234",
  "items": [
    {
      "id": "13",
      "name": "Patrick"
    },
    {
      "id": "16",
      "name": "John"
    }
  ]
}
```

### Response Example (200 OK)
```json
{
  "cursor": "some-continuation-cursor",
  "items": [
    {
      "dateFrom": "2023-01-01T00:00:00Z",
      "dateTo": "2023-12-31T23:59:59Z",
      "isBarred": false,
      "isClosed": false,
      "periodNumber": 1,
      "objectVersion": "1",
      "year": "2023"
    }
  ]
}
```
```

--------------------------------

### GET /AccountingYears/paged

Source: https://apis.e-conomic.com/index

Retrieves a paginated list of accounting years. Supports filtering, sorting, and pagination.

```APIDOC
## GET /AccountingYears/paged

### Description
Retrieves a page of accounting years. This endpoint supports filtering, setting the page size, and skipping pages for pagination.

### Method
GET

### Endpoint
https://apis.e-conomic.com/accountingyearsapi/v2.0.1/AccountingYears/paged

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Use this parameter to set the filtering for fields. Refer to filtering instructions.
- **pageSize** (integer) - Optional - Sets the page size for the results. Defaults to 20. Maximum value is 100.
- **skipPages** (integer) - Optional - Sets the number of pages to skip. Defaults to 0.
- **sort** (string) - Optional - Sets the sort fields and direction. Refer to sort instructions.

### Request Example
```
(No request body for this endpoint)
```

### Response
#### Success Response (200)
An array of accounting year objects. Each object contains:
- **year** (string or null): The year of the accounting year. Read-only.
- **dateFrom** (string <date-time>): The first date in the accounting year.
- **dateTo** (string <date-time>): The last date in the accounting year.
- **isClosed** (boolean): Whether the accounting year is closed.
- **objectVersion** (string or null): The object version, required for PUT requests.

#### Response Example
```json
[
  {
    "year": "2023",
    "dateFrom": "2023-01-01T00:00:00Z",
    "dateTo": "2023-12-31T23:59:59Z",
    "isClosed": false,
    "objectVersion": "12345"
  }
]
```

#### Error Responses
- **400**: Bad request. Your request does not pass our validation. Check the errors array for more details.
- **401**: Unauthorized access. Please refer to the e-conomic API documentation for authorization.
- **403**: Access forbidden. You may not have the necessary permissions.
- **429**: Too many requests. You have exceeded your API quota.
- **500**: Internal server error. An unexpected error occurred.
```

--------------------------------

### GET /AccountingYears/count

Source: https://apis.e-conomic.com/index

Retrieves the count of all accounting years available.

```APIDOC
## GET /AccountingYears/count

### Description
Retrieves the count of all accounting years available.

### Method
GET

### Endpoint
https://apis.e-conomic.com/accountingyearsapi/v2.0.1/AccountingYears/count

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **count** (integer) - The number of accounting years.

#### Response Example
```json
0
```
```

--------------------------------

### Retrieve Accounting Year Periods (GET /accountingYears/periods)

Source: https://apis.e-conomic.com/index

Retrieves a paginated list of accounting year periods. Supports filtering, pagination (pageSize, skipPages), and sorting. Requires specific authorization tokens.

```json
{
  "cursor": "234",
  "items": [
    {
      "id": "13",
      "name": "Patrick"
    },
    {
      "id": "16",
      "name": "John"
    }
  ]
}
```

--------------------------------

### Retrieve Accounting Years (GET /AccountingYears/paged)

Source: https://apis.e-conomic.com/index

Retrieves a paginated list of accounting years. Supports filtering, pagination (pageSize, skipPages), and sorting. Requires AppSecretToken and AgreementGrantToken for authorization.

```javascript
const options = {
  method: 'GET',
  headers: {
    'X-AppSecretToken': 'YOUR_APP_SECRET_TOKEN',
    'X-AgreementGrantToken': 'YOUR_AGREEMENT_GRANT_TOKEN'
  }
};

fetch('https://apis.e-conomic.com/accountingyearsapi/v2.0.1/AccountingYears/paged?filter=year.eq.2023&pageSize=50&skipPages=0&sort=year.asc', options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));
```

--------------------------------

### GET /AccountingYears/count

Source: https://apis.e-conomic.com/index

Retrieves the total number of accounting years. Supports filtering.

```APIDOC
## GET /AccountingYears/count

### Description
Retrieves the total number of accounting years available. This endpoint supports filtering.

### Method
GET

### Endpoint
https://apis.e-conomic.com/accountingyearsapi/v2.0.1/AccountingYears/count

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Use this parameter to set the filtering for fields. Refer to filtering instructions.

### Request Example
```
(No request body for this endpoint)
```

### Response
#### Success Response (200)
An integer representing the total count of accounting years.

#### Error Responses
- **400**: Bad request. Your request does not pass our validation. Check the errors array for more details.
- **401**: Unauthorized access. Please refer to the e-conomic API documentation for authorization.
- **403**: Access forbidden. You may not have the necessary permissions.
- **429**: Too many requests. You have exceeded your API quota.
- **500**: Internal server error. An unexpected error occurred.
```

--------------------------------

### GET /accountingYears/periods/paged

Source: https://apis.e-conomic.com/index

Retrieves the number of AccountingYearPeriods. Supports filtering.

```APIDOC
## GET /accountingYears/periods/paged

### Description
Call this endpoint to get the number of AccountingYearPeriods. You can use filtering as well.

### Method
GET

### Endpoint
https://apis.e-conomic.com/accountingyearsapi/v2.0.1/accountingYears/periods/paged

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Use this parameter to set the filtering for fields.

### Responses
#### Success Response (200)
- Returns an array of AccountingYearPeriod objects. The primary use is to determine the count, but the full objects are returned.

##### Response Schema (Array elements):
- **periodNumber** (integer) - Required - The unique number of the accounting year.
- **year** (string) - Required - The year of the period.
- **dateFrom** (string) - Required - The first date in the period.
- **dateTo** (string) - Required - The last date in the period.
- **isClosed** (boolean) - Required - Whether the period is closed or not.
- **isBarred** (boolean) - Required - Whether the period is barred or not.
- **objectVersion** (string) - Optional - The object version, required for PUT requests.

#### Error Responses
- **400 Bad Request**: Your request does not pass our validation. Check the errors array for more details.
- **401 Unauthorized Access**: Please consult the e-conomic API documentation for authorization details.
- **403 Access Forbidden**: You do not have access to this resource based on your granted roles.
- **429 Too Many Requests**: You have exceeded your API quota. Please wait before making further requests.
- **500 Internal Server Error**: An unexpected error occurred. Please contact api@e-conomic.com with details.

### Response Example (200 OK)
```json
[
  {
    "periodNumber": 0,
    "year": "string",
    "dateFrom": "2019-08-24T14:15:22Z",
    "dateTo": "2019-08-24T14:15:22Z",
    "isClosed": true,
    "isBarred": true,
    "objectVersion": "string"
  }
]
```
```

--------------------------------

### Get Subscription Count

Source: https://apis.e-conomic.com/index

Retrieves the total number of items in the subscriptions collection. This can be used for pagination calculations.

```APIDOC
## GET /subscriptions/count

### Description
Retrieves the count of items in the subscriptions collection. Useful for implementing pagination.

### Method
GET

### Endpoint
/subscriptionsapi/v1.0.0/subscriptions/count

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **count** (integer) - The number of subscriptions.

#### Response Example
{
  "count": 150
}
```

--------------------------------

### Retrieve Item Count

Source: https://apis.e-conomic.com/index

Endpoint to get the total number of items available for a given resource. Useful for calculating total pages for classic pagination.

```APIDOC
## Retrieve Item Count

### Description
Get the total number of items available for a specific resource. This is useful for calculating the total number of pages required for classic pagination or for displaying item counts.

### Method
GET

### Endpoint
`/{ITEM}/count`

### Parameters
No parameters required.

### Request Example
```
GET https://apis.e-conomic.com/subscriptionsapi/v1.0.0/subscriptions/count
```

### Response
#### Success Response (200)
- **count** (integer) - The total number of items.

#### Response Example
```json
{
  "count": 2056
}
```
```

--------------------------------

### API Update Conflict Response Example

Source: https://apis.e-conomic.com/index

Illustrates the JSON response received when an update operation fails due to a conflict, typically because the object has been modified since it was last retrieved. This includes a message, developer hint, log ID, timestamp, and the property that caused the conflict.

```JSON
{
  "message": "Update conflict. Version does not match.",
  "developerHint": "The resource has been updated by another user. Retrieve the resource/object and try the update again. This is needed in order to prevent you from rolling back another user's update.",
  "logId": "09580053-1141-4e7f-85e1-bed8600e0278",
  "logTimeUtc": "2021-11-04T09:07:56",
  "property": "version"
}
```

--------------------------------

### Get Subscription Count

Source: https://apis.e-conomic.com/index

Retrieves the total number of subscriptions. This can be used for pagination calculations. The endpoint returns a count of items in the collection.

```HTTP
GET https://apis.e-conomic.com/subscriptionsapi/v1.0.0/subscriptions/count
```

--------------------------------

### GET /accountingYears/periods/count

Source: https://apis.e-conomic.com/index

Retrieves the count of accounting year periods. Supports filtering for specific fields.

```APIDOC
## GET /accountingYears/periods/count

### Description
Retrieves the count of accounting year periods. This endpoint supports filtering based on specific fields.

### Method
GET

### Endpoint
https://apis.e-conomic.com/accountingyearsapi/v2.0.1/accountingYears/periods/count

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Use this parameter to set the filtering for fields. Filtering instructions are provided separately.

### Response
#### Success Response (200)
- **integer** (<int32>) - The count of accounting year periods.

#### Error Responses
- **400 Bad Request**: Your request does not pass our validation. Check the errors array for more details.
- **401 Unauthorized Access**: Please refer to e-conomic API documentation for authorization instructions.
- **403 Access Forbidden**: You may not have the necessary permissions for this resource.
- **429 Too Many Requests**: You have exceeded your API quota. Please wait and try again.
- **500 Internal Server Error**: An unexpected error occurred. Please contact support with log ID and agreement number.
```

--------------------------------

### GET /AccountingYearPeriods

Source: https://apis.e-conomic.com/index

Retrieve all AccountingYearPeriods in bulk. This endpoint supports pagination using the `cursor` parameter and filtering via the `filter` parameter. The maximum number of items returned per call is typically 1000, as defined by the `x-cursor-page-size` extension.

```APIDOC
## Retrieve all AccountingYearPeriods

### Description
Use this endpoint to retrieve a collection of all accounting (year) periods associated with an agreement. The endpoint supports cursor-based pagination and filtering for efficient data retrieval.

### Method
`GET`

### Endpoint
`/AccountingYearPeriods`

### Query Parameters

*   **`cursor`** (string)
    *   **Constraints:** 0 to 50 characters.
    *   **Description:** Use this parameter to specify the continuation cursor for retrieving the next set of data. Refer to the [pagination instructions](link-to-pagination-instructions) for details.

*   **`filter`** (string)
    *   **Description:** Use this parameter to apply filtering criteria to the results. Refer to the [filtering instructions](link-to-filtering-instructions) for syntax and available fields.

### Request Headers

*   **`X-AppSecretToken`** (string, Required)
    *   Your application's secret token.
*   **`X-AgreementGrantToken`** (string, Required)
    *   The agreement grant token.

### Pagination

The maximum number of items returned in a single call is determined by the `x-cursor-page-size` extension in the OpenAPI specification. The default is typically 1000, but may be smaller in specific cases.

### Responses

*   **`200 OK`**
    *   **Description:** Successfully retrieved the list of AccountingYearPeriods.
    *   **Content:** A JSON object containing a collection of AccountingYearPeriods, potentially including a `nextCursor` if more data is available.

    ```json
    {
      "collection": [
        {
          "id": "string",
          "name": "string",
          "startDate": "YYYY-MM-DD",
          "endDate": "YYYY-MM-DD",
          "accountingYear": {
            "id": "string",
            "name": "string"
          }
        }
        // ... more accounting year periods
      ],
      "nextCursor": "string" // Present if there are more results
    }
    ```

### Authorizations

Requires `SuperUser` or `Bookkeeping` application roles. Authentication is performed using `X-AppSecretToken` and `X-AgreementGrantToken` headers.
```

--------------------------------

### GET /accountingYears/periods/{number}

Source: https://apis.e-conomic.com/index

Retrieves a single AccountingYearPeriod by its unique number. Provides details about the accounting period.

```APIDOC
## GET /accountingYears/periods/{number}

### Description
Use this endpoint to load a single AccountingYearPeriod by its number. This provides detailed information about a specific accounting period.

### Method
GET

### Endpoint
https://apis.e-conomic.com/accountingyearsapi/v2.0.1/accountingYears/periods/{number}

### Parameters
#### Path Parameters
- **number** (integer, <int32>) - Required - The unique number identifying the accounting year period.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **periodNumber** (integer, <int32>) - The unique number of the accounting year period.
- **year** (string or null) - The year associated with the accounting period.
- **dateFrom** (string, <date-time>) - The start date of the accounting period.
- **dateTo** (string, <date-time>) - The end date of the accounting period.
- **isClosed** (boolean) - Indicates if the accounting period is closed.
- **isBarred** (boolean) - Indicates if the accounting period is barred.
- **objectVersion** (string or null) - The object version, used for updates to ensure data consistency.

#### Response Example
```json
{
  "periodNumber": 0,
  "year": "string",
  "dateFrom": "2019-08-24T14:15:22Z",
  "dateTo": "2019-08-24T14:15:22Z",
  "isClosed": true,
  "isBarred": true,
  "objectVersion": "string"
}
```

#### Error Responses
- **400 Bad Request**: Your request does not pass our validation. Check the errors array for more details.
- **401 Unauthorized Access**: Please refer to e-conomic API documentation for authorization instructions.
- **403 Access Forbidden**: You may not have the necessary permissions for this resource.
- **404 Resource Not Found**: The requested resource does not exist.
- **429 Too Many Requests**: You have exceeded your API quota. Please wait and try again.
- **500 Internal Server Error**: An unexpected error occurred. Please contact support with log ID and agreement number.
```

--------------------------------

### Idempotency Tokens

Source: https://apis.e-conomic.com/index

Idempotency tokens ensure the integrity of operations by preventing duplicate requests. Use the `Idempotency-Key` header with a unique value for each request. Retrying a failed request with the same key will result in the original response being returned from cache (valid for one hour). The `X-ResultFromCache` header indicates a cached response. This feature is not available for GET requests. You are responsible for generating and managing these keys.

```APIDOC
## Idempotency Tokens

### Description
Idempotency tokens prevent duplicate operations by ensuring that a request is processed only once, even if sent multiple times. This is particularly useful for handling network failures.

### Header
`Idempotency-Key`: A unique key (string) generated by the client for each specific request.

### Behavior
- If a request with a given `Idempotency-Key` has already been processed, the API will return the cached response from the original operation.
- The cache for idempotency keys is valid for **one hour**.
- A response from the cache is indicated by the `X-ResultFromCache: true` header.

### Limitations
- Not available for GET requests.
- Clients are responsible for generating and managing the `Idempotency-Key` values.

### Example Usage (Conceptual)
```
POST /api/some-operation
Idempotency-Key: a-unique-client-generated-id-12345
Content-Type: application/json

{ ... request body ... }
```

### Response Header
`X-ResultFromCache`: `true` if the response was served from cache, otherwise absent.
```

--------------------------------

### GET /AccountingYears/{year}

Source: https://apis.e-conomic.com/index

Retrieves a single accounting year based on the provided year identifier. The year parameter can be a single year or a span of years encoded with '_6_'.

```APIDOC
## GET /AccountingYears/{year}

### Description
Use this endpoint to retrieve a single accounting year. When fetching accounting years that span across years, use `_6_` as a delimiter between the years. Ex: `2024/2025` becomes `2024_6_2025` when used as path params in this endpoint. See Custom resource encoding for more info.

### Method
GET

### Endpoint
https://apis.e-conomic.com/accountingyearsapi/v2.0.1/AccountingYears/{year}

### Parameters
#### Path Parameters
- **year** (string) - Required - The identifier for the accounting year. Use `_6_` as a delimiter for year spans (e.g., `2024_6_2025`).

### Request Example
```
(No request body for GET request)
```

### Response
#### Success Response (200)
- **dateFrom** (string) - The first date in the accounting year.
- **dateTo** (string) - The last date in the accounting year.
- **isClosed** (boolean) - Whether the accounting year is closed or not.
- **objectVersion** (string or null) - The object version, required for PUT requests.
- **year** (string or null) - The year of the accounting year.

#### Response Example
```json
{
  "year": "string",
  "dateFrom": "2019-08-24T14:15:22Z",
  "dateTo": "2019-08-24T14:15:22Z",
  "isClosed": true,
  "objectVersion": "string"
}
```

#### Error Responses
- **400**: Bad request. Your request does not pass our validation. Check the errors array for more details.
- **401**: Unauthorized access.
- **403**: Access forbidden.
- **404**: Resource not found.
- **429**: Too many requests. You have made too many calls towards our API. You are over your quota.
- **500**: Internal server error. Something went wrong but the error has been logged.
```

--------------------------------

### Retrieve Page of Accounting Year Periods (GET /accountingYears/periods/paged)

Source: https://apis.e-conomic.com/index

Retrieves a single page of AccountingYearPeriods. This endpoint is used to load data in chunks, with default pageSize of 20 and no pages skipped by default. It returns an array of period objects.

```json
[
  {
    "periodNumber": 0,
    "year": "string",
    "dateFrom": "2019-08-24T14:15:22Z",
    "dateTo": "2019-08-24T14:15:22Z",
    "isClosed": true,
    "isBarred": true,
    "objectVersion": "string"
  }
]
```

--------------------------------

### Get Count of Accounting Years

Source: https://apis.e-conomic.com/index

Retrieves the total count of accounting years available. This endpoint returns a simple integer count and is useful for understanding the scale of data. No specific authorization details are provided beyond the general API access.

```json
{
  "description": "Response Schema: application/json"
}
```

```http
GET https://apis.e-conomic.com/accountingyearsapi/v2.0.1/AccountingYears/count

### Response samples
* 200
* 400
* 401
* 403
* 429
* 500
```

--------------------------------

### Retrieve Single Accounting Year (GET Request)

Source: https://apis.e-conomic.com/index

This snippet demonstrates how to retrieve a specific accounting year using its identifier. It highlights the custom encoding required for years spanning across calendar years (e.g., '2024/2025' becomes '2024_6_2025'). The response includes details like date range, closed status, and object version.

```http
GET https://apis.e-conomic.com/accountingyearsapi/v2.0.1/AccountingYears/{year}

---

### Responses
**200**
Success
```json
{
  "year": "string",
  "dateFrom": "2019-08-24T14:15:22Z",
  "dateTo": "2019-08-24T14:15:22Z",
  "isClosed": true,
  "objectVersion": "string"
}
```
```

--------------------------------

### Classic Pagination

Source: https://apis.e-conomic.com/index

Alternative pagination method using `skippages` and `pagesize` query parameters. Suitable for UI elements like lists and tables, but limited to 10,000 items.

```APIDOC
## Classic Pagination

### Description
Retrieve specific pages of items using classic pagination. This method is suitable for UI components that require explicit page navigation. It is limited to a maximum of 10,000 items.

### Method
GET

### Endpoint
`/{ITEM}/paged?skippages={SKIP_PAGES_VALUE}&pagesize={PAGE_SIZE_VALUE}`

### Parameters
#### Query Parameters
- **skippages** (integer) - Optional - The number of pages to skip.
- **pagesize** (integer) - Optional - The number of items to return per page (default is 20, max is 100).

### Request Example
```
GET https://apis.e-conomic.com/subscriptionsapi/v1.0.0/subscriptions/paged?skippages=5&pagesize=50&sort=-number
```

### Response
#### Success Response (200)
- **items** (array) - An array of items for the specified page.

#### Response Example
```json
{
  "items": [
    { "id": 101, "name": "Subscription 101" },
    { "id": 102, "name": "Subscription 102" }
  ]
}
```

### Note
If no parameters are used, the endpoint returns 20 items by default. The `pagesize` can be increased up to 100 items.
```

--------------------------------

### Implementation Specifics: Booleans and Nulling

Source: https://apis.e-conomic.com/index

Details how boolean values and null values are handled in API requests and responses.

```APIDOC
## Implementation Specifics

### Booleans
- Booleans are generally only included in responses when their value is `true`. `false` boolean values are omitted.
- This same logic applies to write operations (POST and PUT): omit boolean fields if their value is `false`.

### Nulling
- The API generally does not accept `null` as a value and will return a validation exception.
- To nullify a property, exclude it from the JSON payload in write operations (POST and PUT).
```

--------------------------------

### Cursor-based Pagination

Source: https://apis.e-conomic.com/index

Recommended approach for retrieving collections of items. Uses a `cursor` query parameter to load subsequent pages of results. Suitable for very large datasets.

```APIDOC
## Cursor-based Pagination

### Description
Retrieve collections of items using cursor-based pagination. This method is recommended for its performance and ability to handle large datasets. A `cursor` parameter is used to fetch the next set of items.

### Method
GET

### Endpoint
`/{ITEM}?cursor={CURSOR_VALUE}`

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - The identifier of the first item on the next set of items.

### Request Example
```
GET https://apis.e-conomic.com/subscriptionsapi/v1.0.0/subscriptions?cursor=34781
```

### Response
#### Success Response (200)
- **items** (array) - An array of items.
- **cursor** (string) - An identifier for the next set of items. Absent if there are no more items.

#### Response Example
```json
{
  "items": [
    { "id": 1, "name": "Subscription 1" },
    { "id": 2, "name": "Subscription 2" }
  ],
  "cursor": "87695"
}
```

### Note
The maximum number of items returned in a single call is defined in the `x-cursor-page-size` extension of the response type (usually 1000).
```

--------------------------------

### POST /AccountingYears

Source: https://apis.e-conomic.com/index

Creates a single accounting year. Requires dateFrom, dateTo, and isClosed.

```APIDOC
## POST /AccountingYears

### Description
Use this endpoint to create a single AccountingYear.

### Method
POST

### Endpoint
https://apis.e-conomic.com/accountingyearsapi/v2.0.1/AccountingYears

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **dateFrom** (string) - Required - The first date in the accounting year.
- **dateTo** (string) - Required - The last date in the accounting year.
- **isClosed** (boolean) - Required - Whether the accounting year is closed or not.
- **objectVersion** (string or null) - Optional - The object version, required for PUT requests to help ensure that updates made by others don’t get overwritten by your update request.

### Request Example
```json
{
  "dateFrom": "2019-08-24T14:15:22Z",
  "dateTo": "2019-08-24T14:15:22Z",
  "isClosed": false
}
```

### Response
#### Success Response (201)
- **year** (string or null) - The year of the accounting year. Read-only.

#### Response Example
```json
{
  "year": "string"
}
```
```

--------------------------------

### Object Versioning for Updates

Source: https://apis.e-conomic.com/index

Explains the ObjectVersion mechanism used to prevent concurrent update conflicts.

```APIDOC
## Object Version

`ObjectVersion` is a mechanism to ensure updates are applied only to the latest state of an object, preventing race conditions.

- **Mandatory in PUT Requests**: The `ObjectVersion` property is required for all PUT requests.
- **Retrieve and Include**: Retrieve the `ObjectVersion` during a GET request and include it in your subsequent PUT request.
- **Conflict Handling**: If the object has been modified between the GET and PUT requests, the PUT request will fail with a `409 Conflict` error.

### Example Conflict Response
```json
{
  "message": "Update conflict. Version does not match.",
  "developerHint": "The resource has been updated by another user. Retrieve the resource/object and try the update again. This is needed in order to prevent you from rolling back another user's update.",
  "logId": "09580053-1141-4e7f-85e1-bed8600e0278",
  "logTimeUtc": "2021-11-04T09:07:56",
  "property": "version"
}
```
```

--------------------------------

### Create Accounting Year

Source: https://apis.e-conomic.com/index

Creates a single accounting year. Requires 'X-AppSecretToken' and 'X-AgreementGrantToken' for authorization. The request body must include 'dateFrom', 'dateTo', and 'isClosed'. Responses include a success message with the created year or various error codes.

```json
{
  "description": "Request Body schema: application/json",
  "dateFrom": "string <date-time>",
  "dateTo": "string <date-time>",
  "isClosed": "boolean"
}
```

```json
{
  "description": "Response Schema: application/json",
  "year": "string or null"
}
```

```http
POST https://apis.e-conomic.com/accountingyearsapi/v2.0.1/AccountingYears

### Request samples
* Payload
```json
{
  "dateFrom": "2019-08-24T14:15:22Z",
  "dateTo": "2019-08-24T14:15:22Z",
  "isClosed": false
}
```

### Response samples
* 201
* 400
* 401
* 403
* 429
* 500
```

--------------------------------

### Authentication Headers

Source: https://apis.e-conomic.com/index

Accessing e-conomic API endpoints requires specific authentication headers. These include `X-AppSecretToken`, which identifies your application, and `X-AgreementGrantToken`, which authenticates the agreement grant. Both are security-sensitive and must be obtained through the documented token creation process.

```APIDOC
## Authentication Headers

### Description
To authenticate requests to the e-conomic API, you must include two specific headers: `X-AppSecretToken` and `X-AgreementGrantToken`. These tokens are generated following the instructions provided in the documentation and ensure secure access to your data.

### Required Headers:

1.  **`X-AppSecretToken`**
    *   **Type:** API Key
    *   **Description:** Your application's secret token, used to identify and authorize your application.

2.  **`X-AgreementGrantToken`**
    *   **Type:** API Key
    *   **Description:** The token representing the grant for a specific agreement, used to authorize access to data associated with that agreement.

### Obtaining Tokens
Refer to the authentication guide [here](link-to-token-creation-instructions) for detailed steps on how to create and manage these tokens.

### Example Request Snippet
```
POST /api/endpoint
X-AppSecretToken: YOUR_APP_SECRET_TOKEN
X-AgreementGrantToken: YOUR_AGREEMENT_GRANT_TOKEN
Content-Type: application/json

{ ... request body ... }
```
```

--------------------------------

### Accounting Year API

Source: https://apis.e-conomic.com/index

This section details the API endpoints for managing accounting years, including creating, retrieving by ID, and deleting accounting years. It also covers authentication and versioning.

```APIDOC
## POST /accountingyearsapi/v2.0.1/accountingyears

### Description
Creates a new accounting year.

### Method
POST

### Endpoint
/accountingyearsapi/v2.0.1/accountingyears

### Parameters
#### Query Parameters
- **Number** (integer) - Required - The year for which to create the accounting year.

#### Request Body
- **Number** (integer) - Required - The year for which to create the accounting year.

### Request Example
```json
{
  "Number": 2025
}
```

### Response
#### Success Response (200)
- **Number** (integer) - The year of the created accounting year.

#### Response Example
```json
{
  "Number": 2025
}
```

## GET /accountingyearsapi/v2.0.1/accountingyears/{id}

### Description
Retrieves a specific accounting year by its ID.

### Method
GET

### Endpoint
/accountingyearsapi/v2.0.1/accountingyears/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the accounting year to retrieve.

### Request Example
```
curl -H "X-AppSecretToken: demo" -H "X-AgreementGrantToken: demo" https://apis.e-conomic.com/accountingyearsapi/v2.0.1/accountingyears/1
```

### Response
#### Success Response (200)
- **Number** (integer) - The year of the accounting year.

#### Response Example
```json
{
  "Number": 2025
}
```

## DELETE /accountingyearsapi/v2.0.1/accountingyears/{id}

### Description
Deletes a specific accounting year by its ID.

### Method
DELETE

### Endpoint
/accountingyearsapi/v2.0.1/accountingyears/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the accounting year to delete.

### Request Example
```
curl -X DELETE -H "X-AppSecretToken: demo" -H "X-AgreementGrantToken: demo" https://apis.e-conomic.com/accountingyearsapi/v2.0.1/accountingyears/1
```

### Response
#### Success Response (204)
No content is returned upon successful deletion.

```

--------------------------------

### OpenAPI Schema Usage

Source: https://apis.e-conomic.com/index

Explains the use of 'required' and 'readonly' properties in API requests and responses, consistent with OpenAPI specifications.

```APIDOC
## Required and Readonly Properties

- **Required**: Properties marked as `required` must be included with a value in POST and PUT requests.
- **Readonly**: Properties marked as `readonly` should either be omitted from POST/PUT requests or match the value received in GET requests. These properties are typically generated by the system.
```

--------------------------------

### Filtering API Collections

Source: https://apis.e-conomic.com/index

Filter collection endpoints using the `filter` query parameter. Supports various operators like equals, like, and logical AND/OR. String comparisons are case-insensitive.

```APIDOC
## GET /api/collections

### Description
Filter collection endpoints to retrieve specific resources based on property values and conditions.

### Method
GET

### Endpoint
`/api/collections?filter=<filter_string>`

### Parameters
#### Query Parameters
- **filter** (string) - Required - A filter string composed of property names, operators, and values. Supports logical operators AND/OR and wildcard matching for substring searches.

#### Query Parameter Details:
- **Property Name**: The name of the property to filter on.
- **Operator Syntax**: Operators are appended to the property name with a '$' separator (e.g., `name$eq`, `city$like`).
  - Supported Operators:
    - `$eq`: Equals
    - `$ne`: Not equals
    - `$gt`: Greater than
    - `$gte`: Greater than or equal
    - `$lt`: Less than
    - `$lte`: Less than or equal
    - `$like`: Substring match (supports wildcards '*'). If no wildcard is used, it defaults to a 'contains' match.
    - `$and`: Logical AND operator to chain predicates.
    - `$or`: Logical OR operator to chain predicates.
    - `$in`: Checks if a value is within a list. Syntax: `property$in:[value1,value2]`.
    - `$nin`: Checks if a value is not within a list. Syntax: `property$nin:[value1,value2]`.
    - `$null`: Filters for null values. Syntax: `property$null:`.
- **Value**: The value to compare against. Should be URL encoded.
- **Logical Operators**: Chain predicates using `$and` or `$or`. Parentheses `()` can be used to control operator affinity. Example: `?filter=name$eq:Joe$and:(city$like:*port$or:age$lt:40)`

#### URL Encoding
All filter strings must be URL encoded.

#### Escaping Special Characters
To include special characters literally within a filter value, use the following escape sequences:
- `$$`: Escapes '$'
- `$(`: Escapes '('
- `$)`: Escapes ')'
- `$*`: Escapes '*'
- `$,`: Escapes ','
- `$[`: Escapes '['
- `$]`: Escapes ']'

### Request Example
```
GET /api/users?filter=name$eq:John Doe
GET /api/users?filter=age$gt:30$and:city$like:*port
GET /api/users?filter=status$in:[active,pending]
GET /api/users?filter=email$null:
```

### Response
#### Success Response (200)
- **Resources**: (Array) - A list of resources matching the filter criteria.

#### Response Example
```json
[
  {
    "id": 1,
    "name": "John Doe",
    "city": "New York"
  }
]
```
```

--------------------------------

### Sorting API Collections

Source: https://apis.e-conomic.com/index

Sort collection endpoints using the `sort` query parameter. Supports ascending, descending, and multi-property sorting. Can enforce alphabetical sorting for numeric values.

```APIDOC
## GET /api/collections

### Description
Sort collection endpoints to order resources based on specified properties.

### Method
GET

### Endpoint
`/api/collections?sort=<sort_string>`

### Parameters
#### Query Parameters
- **sort** (string) - Optional - A comma-separated string defining the sorting order. Prepend with `-` for descending order, `~` for alphabetical sorting of numeric values.

#### Query Parameter Details:
- **Ascending Order**: Prepend property name with nothing (default). Example: `name`
- **Descending Order**: Prepend property name with `-`. Example: `-name`
- **Alphabetical Sorting**: Prepend property name with `~` to sort numbers alphabetically. Example: `~age`
- **Multiple Properties**: Separate property names with commas. Mixing directions is allowed. Example: `-name,age`

### Request Example
```
GET /api/users?sort=name
GET /api/users?sort=-age
GET /api/users?sort=~name,-age
```

### Response
#### Success Response (200)
- **Resources**: (Array) - A list of resources sorted according to the specified criteria.

#### Response Example
```json
[
  {
    "id": 2,
    "name": "Jane Smith",
    "age": 25
  },
  {
    "id": 1,
    "name": "John Doe",
    "age": 30
  }
]
```
```

--------------------------------

### HTTP Status Codes

Source: https://apis.e-conomic.com/index

Details the various HTTP status codes returned by the e-conomic API, along with their meanings and descriptions.

```APIDOC
## HTTP Status Codes

The e-conomic API returns the following HTTP status codes:

- **200 OK**: Indicates that the request was successful.
- **201 Created**: Returned when a resource is successfully created. Includes the created resource in the body and a location header.
- **204 No Content**: Returned when there is no content to return in the response.
- **400 Bad Request**: The request was malformed, potentially due to failed validation or filtering on non-filterable fields. A developer hint may be included.
- **401 Unauthorized**: The provided credentials were invalid or missing. Also returned if an agreement has revoked access.
- **403 Forbidden**: Access to the requested resource is denied, even if authorized, based on the roles requested during the grant.
- **404 Not Found**: The requested resource does not exist. This could be due to deletion or an incorrect URL. Ensure you are using provided links and not concatenating URLs.
- **405 Method Not Allowed**: The HTTP method used is not supported for the requested endpoint (e.g., PUT on a collection resource).
- **409 Conflict**: The request could not be completed due to a conflict with the current state of the target resource. Retrieve the resource and try again.
- **415 Unsupported Media Type**: The API only accepts JSON. Requesting a different media type will result in this status code.
- **500 Internal Server Error**: An error occurred on the server side. Try again or contact support.
```

--------------------------------

### Custom Extensions in OpenAPI Specification

Source: https://apis.e-conomic.com/index

The OpenAPI specification includes custom extensions, prefixed with `x-`, that provide additional information for developers consuming the API. These extensions include `x-required-roles` for endpoint authorization, `x-error-codes` for potential errors, and `x-cursor-page-size` for controlling pagination results.

```APIDOC
## Custom Extensions in OpenAPI Specification

### Description
Custom extensions, prefixed with `x-`, are available within the OpenAPI specification to provide developers with additional context and control over API interactions.

### Available Extensions:

1.  **`x-required-roles`**
    *   **Description:** Specifies the list of application roles required to access a particular group of endpoints.
    *   **Format:** Array of strings (e.g., `["SuperUser", "Bookkeeping"]`)

2.  **`x-error-codes`**
    *   **Description:** Lists the potential error codes that can be returned from a specific set of endpoints.
    *   **Format:** Array of strings or objects detailing error codes and their meanings.

3.  **`x-cursor-page-size`**
    *   **Description:** Defines the maximum number of items that can be returned in a single `CursorResults` response. This helps manage pagination.
    *   **Format:** Integer (e.g., `1000`)

### Usage
These extensions are embedded within the OpenAPI specification file and can be inspected by API consumers to understand authorization requirements, anticipate errors, and configure pagination efficiently.
```

--------------------------------

### Resource Encoding

Source: https://apis.e-conomic.com/index

Specifies that all non-alphanumeric characters in resource URLs are URL-encoded.

```APIDOC
## Resource Encoding

All non-alphanumeric characters in resource URLs are standard URL encoded. Please refer to standard URL encoding.
```