> ## Documentation Index
> Fetch the complete documentation index at: https://support.zonely.gen.tr/llms.txt
> Use this file to discover all available pages before exploring further.

# Zonely API Reference

> Public and integration endpoints for license checks, update listeners, announcements, giveaways, rewards, and user token actions.

# Zonely API Reference

This page lists the lightweight API routes used by Zonely integrations, product license checks, update listeners, announcements, giveaways, season rewards, and user token actions.

Use these endpoints when an external product, game server, integration, or licensed script needs to communicate with your Zonely installation.

<Info>
  All endpoints on this page use the `GET` method unless a future system page states otherwise.
</Info>

## Base URL

Replace `https://your-domain.com` with the domain where Zonely is installed:

```txt theme={null}
https://your-domain.com/Files/Api/...
```

Some routes forward the request to an internal handler such as `license.php`, `builtbybit.php`, `broadcast.php`, `giveaway.php`, or `controller.php`. The internal target is shown so you can understand which part of the system receives the request.

## Before You Use The API

* Use `https://` whenever possible.
* Keep `obf_password`, `token`, and license-related values private.
* URL-encode values that may contain spaces, slashes, special characters, or non-English characters.
* Test each endpoint with a browser, Postman, Insomnia, or a small server-side request before using it in production.
* If an endpoint uses `{ip}`, pass the real requester or server IP expected by your license logic.

<Warning>
  Do not expose private license keys, product IDs, or user tokens in public client-side JavaScript unless the specific integration is designed for public use.
</Warning>

## Endpoint Summary

| Endpoint                                                                          | Method | Purpose                                                             |
| --------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------- |
| `/Files/Api/license/{obf_password}/{product_id}/{ip}`                             | `GET`  | Checks a product license by encrypted password, product ID, and IP. |
| `/Files/Api/builtbybit/{obf_password}/{product_id}/{ip}`                          | `GET`  | Checks a BuiltByBit-linked license route.                           |
| `/Files/Api/builtbybit/license/{obf_password}/{product_id}/{ip}`                  | `GET`  | Alternative BuiltByBit license route.                               |
| `/Files/Api/broadcasts`                                                           | `GET`  | Returns or forwards license announcement data.                      |
| `/Files/Api/giveaway`                                                             | `GET`  | Runs the giveaway check endpoint.                                   |
| `/Files/Controllers/ControllersAll.php?main=RewardDistribute&container=Seasons`   | `GET`  | Runs season-end reward distribution.                                |
| `/Files/Api/upgrades/hook/{product_ids}/{version}`                                | `GET`  | Checks update hook data for one or more products.                   |
| `/Files/Api/upgrades/version/{product_id}`                                        | `GET`  | Legacy update version listener.                                     |
| `/Files/Api/upgrades/listener/{product_ids}/{version}`                            | `GET`  | New update listener route.                                          |
| `/Files/Api/activecode/{product_id}`                                              | `GET`  | Checks active code information for a product.                       |
| `/Files/Api/user/token/{token}/lang/{lang}/discord/{discord}`                     | `GET`  | Sends token, language, and Discord data to the user controller.     |
| `/Files/Api/user/token/{token}/lang/{lang}/subname/{subname}/lastname/{lastname}` | `GET`  | Sends token, language, and name information to the user controller. |

## License Verification

Use this endpoint when a product or external script needs to verify a Zonely license.

```http theme={null}
GET /Files/Api/license/{obf_password}/{product_id}/{ip}
```

Internal target:

```txt theme={null}
license.php?passwordOBF=...&productid=...&wlicenseIP=...
```

| Parameter      | Description                                               |
| -------------- | --------------------------------------------------------- |
| `obf_password` | Encrypted password key used by the license check.         |
| `product_id`   | Unique product identifier.                                |
| `ip`           | Requester or server IP address used by the license logic. |

## BuiltByBit License Verification

Use this endpoint for BuiltByBit-linked license verification.

```http theme={null}
GET /Files/Api/builtbybit/{obf_password}/{product_id}/{ip}
```

Internal target:

```txt theme={null}
builtbybit.php?passwordOBF=...&productid=...&wlicenseIP=...
```

Required parameters are the same as the main license verification route.

### Alternative BuiltByBit Route

Some integrations may use the longer BuiltByBit license path:

```http theme={null}
GET /Files/Api/builtbybit/license/{obf_password}/{product_id}/{ip}
```

Internal target:

```txt theme={null}
license.php?passwordOBF=...&productid=...&wlicenseIP=...
```

## Announcements And Giveaway

### License Announcements

```http theme={null}
GET /Files/Api/broadcasts
```

Internal target:

```txt theme={null}
broadcast.php
```

Use this route when licensed products or integrations need to fetch announcement data.

### Giveaway Check

```http theme={null}
GET /Files/Api/giveaway
```

Internal target:

```txt theme={null}
giveaway.php
```

Use this route for giveaway-related checks or integration listeners.

## Season Reward Distribution

```http theme={null}
GET /Files/Controllers/ControllersAll.php?main=RewardDistribute&container=Seasons
```

This route runs the season reward distribution flow.

<Warning>
  Run this endpoint intentionally. If your installation uses scheduled tasks, make sure the route is called only at the correct season-end time.
</Warning>

## Update And Version Routes

### Update Hook

```http theme={null}
GET /Files/Api/upgrades/hook/{product_ids}/{version}
```

Internal target:

```txt theme={null}
license.php?productids=...&productUpdate=...
```

| Parameter     | Description                                               |
| ------------- | --------------------------------------------------------- |
| `product_ids` | One product ID or a supported product ID list.            |
| `version`     | Current version value sent by the product or integration. |

### Legacy Update Version

```http theme={null}
GET /Files/Api/upgrades/version/{product_id}
```

Internal target:

```txt theme={null}
license.php?productidListener=...
```

Use this only when an older integration expects the legacy version route.

### New Update Listener

```http theme={null}
GET /Files/Api/upgrades/listener/{product_ids}/{version}
```

Internal target:

```txt theme={null}
license.php?heidiaListenerproductids=...&heidiaListenerProductUpdate=...
```

Use this route for newer product update listeners.

### Active Code Verification

```http theme={null}
GET /Files/Api/activecode/{product_id}
```

Internal target:

```txt theme={null}
license.php?productidListeners=...
```

Use this route when an integration needs to check active code data for a product.

## User Token Routes

### Token With Discord

```http theme={null}
GET /Files/Api/user/token/{token}/lang/{lang}/discord/{discord}
```

Internal target:

```txt theme={null}
controller.php?token=...&lang=...&discord=...
```

| Parameter | Description                                              |
| --------- | -------------------------------------------------------- |
| `token`   | User token or integration token.                         |
| `lang`    | Language code, such as `en` or `tr`.                     |
| `discord` | Discord identifier or value expected by the integration. |

### Token With Name Information

```http theme={null}
GET /Files/Api/user/token/{token}/lang/{lang}/subname/{subname}/lastname/{lastname}
```

Internal target:

```txt theme={null}
controller.php?token=...&lang=...&subname=...&lastname=...
```

| Parameter  | Description                                                                 |
| ---------- | --------------------------------------------------------------------------- |
| `token`    | User token or integration token.                                            |
| `lang`     | Language code, such as `en` or `tr`.                                        |
| `subname`  | First name, subtitle name, or custom name value expected by the controller. |
| `lastname` | Last name value expected by the controller.                                 |

## Testing Checklist

Before using an endpoint in production:

* Confirm the domain and route are correct.
* Replace every placeholder value.
* Test with the same product ID and IP that the real integration will use.
* Check whether the endpoint returns the expected response or forwards to the expected internal handler.
* Keep a note of the request URL used by the external product or server.

## Common Issues

**The endpoint returns an unexpected result**\
Check the product ID, encrypted password value, IP value, and whether the related product/license record exists.

**The request works in the browser but not in the external product**\
Check firewall rules, SSL configuration, user agent restrictions, and whether the external product encodes URL parameters correctly.

**A user token route does not update the account**\
Check that the token is valid, the language code is supported, and the Discord/name values are passed in the expected format.

**A season or reward endpoint runs at the wrong time**\
Review the scheduled task or external trigger that calls the route.