> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference reporter

> Export newsletter, order, customer, and statistics data through the Admin Interface API reporter and track progress with status codes per service.

The reporting API provides the option to export data for certain services (e.g. newsletter subscribers or orders). The export can be performed in different formats, depending on the respective service.

In addition, the API returns status information about the progress of the export process. The following overview shows which services are currently supported and how the status codes are to be interpreted.

***

## Supported methods

List of all supported methods.

| **Command/Info** | **Endpoints** | **GET**               | **POST**              | **PUT**             | **DELETE**            |
| ---------------- | ------------- | --------------------- | --------------------- | ------------------- | --------------------- |
| **Export**       | report/       | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="check" /> |

## General

### Supported services and formats

The `report/` endpoint provides a uniform interface for exporting data from the shop system. The API allows you to start export processes, query their progress and cancel them if necessary.

The export function is currently supported for the following services:

| **Service**            | **Supported formats** |
| ---------------------- | --------------------- |
| `adminUser`            | `json`, `csv`         |
| `category`             | `json`, `csv`         |
| `customerAccount`      | `json`, `csv`         |
| `dataFeed`             | `json`, `csv`         |
| `dataFeedTemplate`     | `json`, `csv`         |
| `inquiry`              | `json`, `csv`, `xml`  |
| `inventory`            | `json`, `csv`         |
| `order`                | `json`, `xml`         |
| `newsletterSubscriber` | `json`, `csv`         |
| `product`              | `json`, `csv`         |
| `productRating`        | `json`, `csv`         |
| `seoViews`             | `json`, `csv`         |
| `transaction`          | `json`, `csv`         |
| `voucher`              | `json`, `csv`         |
| `voucherPreset`        | `json`, `csv`         |
| `voucherTemplate`      | `json`, `csv`         |

### Status values of the export process

Export processes run asynchronously in the background. During the export, the current `Reportstatus` is updated continuously. The status of an export operation can take the following values:

| **Value** | **Name**   | **Meaning**                                         |
| --------- | ---------- | --------------------------------------------------- |
| `0`       | `Ready`    | The export process is ready to be executed.         |
| `1`       | `Starting` | The process has been started but has not yet begun. |
| `2`       | `Running`  | The export is currently being executed.             |
| `3`       | `Paused`   | The export is currently paused.                     |
| `4`       | `Canceled` | The export process was canceled manually.           |
| `5`       | `Finished` | The export was completed successfully.              |
| `6`       | `Error`    | An error occurred during the export.                |

## Methods for data export

### GET report/\{service}/status

This endpoint can be used to query the current status of an export process. This includes, among other things, progress, number of processed entries, start and end times, and the link to the exported file (if the export has been completed).

For the export, read permissions for the respective service must be available.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/report/order/status
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "duration": 0,
    "end": "",
    "fileName": "orders_947bbbc6b27914ea35c0.json",
    "fileUrl": "https://content.<your-shop>.de/report/orders_947bbbc6b27914ea35c0.json",
    "hasProgress": false,
    "lastError": "",
    "percentage": 100,
    "processed": 4,
    "start": "2025-02-19T09:15:15.000000000Z",
    "status": 2,
    "total": 4
}
```

#### Error codes

| **Error**               | **Type**        | **Reason**                                                     |
| ----------------------- | --------------- | -------------------------------------------------------------- |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                         |
| 403 Forbidden           |                 | You do not have the required permissions to start the service. |
| 400 Bad Request         |                 | `service` is unknown.                                          |
| 503 Service Unavailable | "internalError" | Redis did not return a status.                                 |

### POST report/\{service}/start

This endpoint starts the export process for the specified service.

Optionally, filters and the desired output format (`json`, `csv` etc.) can be specified via query parameters.

To trigger the export, read permissions for the respective service must be available.

If an export process for the service is already running, it is canceled automatically before the new export is started.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/report/order/start?format=json&filter_gte[createdAt]=2024-11-01T00:00:00.000Z
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "duration": 0,
    "end": "",
    "fileName": "orders_947bbbc6b27914ea35c0.json",
    "fileUrl": "https://content.<your-shop>.de/report/orders_947bbbc6b27914ea35c0.json",
    "hasProgress": false,
    "lastError": "",
    "percentage": 100,
    "processed": 4,
    "start": "2025-02-19T09:15:15.000000000Z",
    "status": 2,
    "total": 4
}
```

#### Error codes

| **Error**               | **Type**                        | **Reason**                                                                                                                        |
| ----------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                                 | Not authorized: you are not logged in.                                                                                            |
| 403 Forbidden           |                                 | You do not have the required permissions to read the service's data.                                                              |
| 400 Bad Request         |                                 | `service` is unknown. <br /> The service does not support the `format`.                                                           |
| 503 Service Unavailable | "Service currently unavailable" | The export process could not be triggered.                                                                                        |
| 503 Service Unavailable | "internalError"                 | Redis did not return a status. <br /> The status could not be updated in Redis. <br /> The status has not changed for 10 seconds. |

### POST report/\{service}/pause

This endpoint can be used to pause a running export process for the specified service.

To pause the process, read permissions for the respective service must be available.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/report/order/pause
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "duration": 0,
    "end": "",
    "fileName": "orders_947bbbc6b27914ea35c0.json",
    "fileUrl": "https://content.<your-shop>.de/report/orders_947bbbc6b27914ea35c0.json",
    "hasProgress": false,
    "lastError": "",
    "percentage": 100,
    "processed": 4,
    "start": "2025-02-19T09:15:15.000000000Z",
    "status": 3,
    "total": 4
}
```

#### Error codes

| **Error**               | **Type**        | **Reason**                                                                                              |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                                                                  |
| 403 Forbidden           |                 | You do not have the required permissions to start the service.                                          |
| 400 Bad Request         |                 | `service` is unknown.                                                                                   |
| 404 Not found           |                 | The process is not running.                                                                             |
| 503 Service Unavailable | "internalError" | Redis did not return a status. <br /> Redis cannot be reached. <br /> The process could not be stopped. |

### POST report/\{service}/resume

This endpoint can be used to resume a paused export process for the specified service.

To resume the process, read permissions for the respective service must be available.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/report/order/resume
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "duration": 0,
    "end": "",
    "fileName": "orders_947bbbc6b27914ea35c0.json",
    "fileUrl": "https://content.<your-shop>.de/report/orders_947bbbc6b27914ea35c0.json",
    "hasProgress": false,
    "lastError": "",
    "percentage": 100,
    "processed": 4,
    "start": "2025-02-19T09:15:15.000000000Z",
    "status": 2,
    "total": 4
}
```

#### Error codes

| **Error**               | **Type**        | **Reason**                                                                                              |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                                                                  |
| 403 Forbidden           |                 | You do not have the required permissions to start the service.                                          |
| 400 Bad Request         |                 | `service` is unknown.                                                                                   |
| 404 Not found           |                 | The process has not been paused.                                                                        |
| 503 Service Unavailable | "internalError" | Redis did not return a status. <br /> Redis cannot be reached. <br /> The process could not be stopped. |

### DELETE report/\{service}/cancel

This endpoint can be used to cancel a running export process for the specified service prematurely.

To end the process, read permissions for the respective service must be available.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/report/order/cancel
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "duration": 0,
    "end": "2025-02-19T09:15:15.000000000Z",
    "fileName": "orders_947bbbc6b27914ea35c0.json",
    "fileUrl": "https://content.<your-shop>.de/report/orders_947bbbc6b27914ea35c0.json",
    "hasProgress": false,
    "lastError": "",
    "percentage": 100,
    "processed": 4,
    "start": "2025-02-19T09:15:15.000000000Z",
    "status": 4,
    "total": 4
}
```

#### Error codes

| **Error**               | **Type**        | **Reason**                                                                                              |
| ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized        |                 | Not authorized: you are not logged in.                                                                  |
| 403 Forbidden           |                 | You do not have the required permissions to start the service.                                          |
| 400 Bad Request         |                 | `service` is unknown.                                                                                   |
| 404 Not found           |                 | The process is not running.                                                                             |
| 503 Service Unavailable | "internalError" | Redis did not return a status. <br /> Redis cannot be reached. <br /> The process could not be stopped. |

## Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6)

Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.