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

# Introduction

Operator Financial Reporting API is a collection of endpoints (currently available only in US region) that allows parking operators and data aggregators to fetch parking transactions report which will be generated in JSON or CSV formats.

## API Usage Workflow

1. Authenticate using the `auth/v1` endpoint to obtain a JWT token
2. Use the token in subsequent requests in the X-Authorization header
3. Generate a report using the `/report/generate` endpoint
4. Check report status using the URL returned in the response
5. Since reports take time to generate, the API follows a polling approach where users request a report, then periodically check its status until completion.
6. Download the completed report when status indicates it's ready

## Authentication of API user

API users must authenticate using JWT tokens passed in the `X-Authorization` header with the format `Bearer YOUR-JWT-TOKEN`. Tokens can be obtained from the `auth/v1` endpoint using client credentials (clientId and clientSecret).

For testing purposes, you can request test credentials from the support team.

## Error Handling

The API returns appropriate HTTP status codes and detailed error messages:

* 400: Bad Request - Invalid parameters or request structure
* 401: Unauthorized - Missing or invalid authentication token
* 403: Forbidden - Insufficient permissions for the requested operation
* 429: Too Many Requests - Rate limit exceeded
* 500: Internal Server Error - Something went wrong on the server side

**Important Note**: When checking report status, if the report generation fails, the API returns a 200 OK HTTP status code with a problem details object in the response body containing status code 400. Client applications should always check the response content type (application/problem+json) and examine the response body to properly handle error scenarios.

## Testing in Staging Environment

* URL: [https://operator-financial-reporting.staging.ezprk.dev](https://operator-financial-reporting.staging.ezprk.dev/)
* Database: Contains sample parking transactions for testing purposes
* Test Operator ID: 60879 (use this ID for testing report generation)
* Data Range: Test data is available for last two days, each day having 5 records
* Authentication: Use test credentials provided by the support team
* Rate Limits: 30 requests per 10 min in test environment

## Report Formats and Limitations

* Available formats: JSON or CSV
* Maximum report size: 100,000 records
* Historical data available: Up to 3 months from current date
* Default columns: Always included in the report
* Additional fields: Can be requested as needed

The report contains default columns and additional fields requested by the user.

## Response Format and Pagination

* All successful responses use HAL+JSON format with hypermedia links
* Long-running operations follow the HATEOAS pattern with self-referencing links
* Reports follow an asynchronous generation pattern with status polling

## Environment URLs

* Production US: [https://operator-financial-reporting.usa.ezprk.net](https://operator-financial-reporting.usa.ezprk.net/)
* Staging: [https://operator-financial-reporting.staging.ezprk.dev](https://operator-financial-reporting.staging.ezprk.dev/)