### Request Signature Generation Example

Source: https://www.donationalerts.com/apidoc/index

Demonstrates how to generate a request signature using SHA256 hashing. The process involves sorting request parameters alphabetically, appending the API client secret, and then hashing the resulting string.

```text
SHA256( abc + xyz + <API client secret> )
```

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

### Merchandise Creation Response Example

Source: https://www.donationalerts.com/apidoc/index

Provides an example of a successful response when creating merchandise. The response includes the unique ID, merchant details, product identifiers, pricing, and other attributes of the newly created merchandise.

```json
{
    "data": {
        "id": 3,
        "merchant": {
            "identifier": "MARKET_GAMES_MAIL_RU",
            "name": "Market games@mail.ru"
        },
        "identifier": "8082",
        "title": {
            "en_US": "Credit case",
            "ru_RU": "Кредитный кейс"
        },
        "is_active": 1,
        "is_percentage": 1,
        "currency": "USD",
        "price_user": 30,
        "price_service": 15,
        "url": "https://market.games.mail.ru/game/1?product_id=8082&user_id={user_id}",
        "img_url": "https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png",
        "end_at": null
    }
}
```

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

### OAuth Token Refresh Response Example

Source: https://www.donationalerts.com/apidoc/index

An example JSON response received after successfully refreshing an access token. It includes the token type, the new access token, its expiration time in seconds, and a refresh token.

```JSON
{
    "token_type": "Bearer",
    "access_token": "...msdisYBVnciOiJSUzI1NiIsImp0aSI6IjQxZDU0ZGQ2O...",
    "expires_in": 631151999,
    "refresh_token": "...173da4e0ff4d48c8cbde7a0071f770624a83259f0a11cd02ec1ce71fe924c4..."
}
```

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

### Make GET Request to DonationAlerts API

Source: https://www.donationalerts.com/apidoc/index

Demonstrates how to make a GET request to the DonationAlerts API to retrieve donation alerts. Requires an Authorization header with a Bearer token.

```curl
curl \
    -X GET https://www.donationalerts.com/api/v1/alerts/donations \
    -H "Authorization: Bearer <token>"
```

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

### Custom Alert Response Example (JSON)

Source: https://www.donationalerts.com/apidoc/index

This is an example of a successful response from the custom_alert endpoint, indicating a 201 Created status. The JSON object contains detailed information about the sent custom alert, including its unique ID, external ID, header, message, image URL, and timestamps for creation and display.

```json
{
    "data": {
        "id": 24,
        "external_id": "12",
        "header": "Custom header",
        "message": "Custom message",
        "image_url": "https://cdn.frankerfacez.com/emoticon/408827/4",
        "sound_url": null,
        "is_shown": 0,
        "created_at": "2020-09-24 12:04:23",
        "shown_at": null
    }
}
```

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

### GET /api/v1/user/oauth

Source: https://www.donationalerts.com/apidoc/index

Obtains user profile information. Requires user authorization with the `oauth-user-show` scope.

```APIDOC
## GET /api/v1/user/oauth

### Description
Obtains user profile information. Requires user authorization with the `oauth-user-show` scope.

### Method
GET

### Endpoint
`https://www.donationalerts.com/api/v1/user/oauth`

### Parameters
#### Query Parameters
- **id** (integer) - Required - The unique and unchangeable user identifier
- **code** (string) - Required - The unique user name
- **name** (string) - Required - The unique displayed user name
- **avatar** (string) - Required - The URL to the personalized graphical illustration
- **email** (string) - Required - The email address
- **socket_connection_token** (string) - Required - Centrifugo connection token

### Request Example
```bash
curl \
    -X GET https://www.donationalerts.com/api/v1/user/oauth \
    -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **data** (object) - Contains user profile information.
  - **id** (integer) - The unique user identifier
  - **code** (string) - The unique user name
  - **name** (string) - The unique displayed user name
  - **avatar** (string) - The URL to the personalized graphical illustration
  - **email** (string) - The email address
  - **socket_connection_token** (string) - Centrifugo connection token

#### Response Example
```json
{
    "data": {
        "id": 3,
        "code": "tris_the_jam_master",
        "name": "Tris_the_Jam_Master",
        "avatar": "https://static-cdn.jtvnw.net/jtv_user_pictures/tris_the_jam_master-profile_image-c084755ce36ab72b-300x300.jpeg",
        "email": "sergey@donationalerts.com",
        "socket_connection_token": "yeJ0eXTYOiJKV1RiLCKhbGciOiJIU4.iJIUfeyJzdeyJzd.GciJIUfiOas_FCvQTYAA8usfsTYYFD"
    }
}
```
```

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

### Getting Access Token

Source: https://www.donationalerts.com/apidoc/index

Exchange the authorization code obtained after user consent for an access token and a refresh token.

```APIDOC
## Getting Access Token

### Description
Exchange the authorization code received after successful user authorization for an access token and a refresh token. This token is used to make authenticated requests to the DonationAlerts API on behalf of the user.

### Method
POST

### Endpoint
`https://www.donationalerts.com/oauth/token`

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - Must be set to `authorization_code`.
- **client_id** (integer) - Required - The application ID received from DonationAlerts.
- **client_secret** (string) - Required - The application secret received from DonationAlerts.
- **redirect_uri** (string) - Required - The URL where users were redirected after authorization.
- **code** (string) - Required - The authorization code received from the `/oauth/authorize` endpoint.

### Request Example
```
curl \
    -X POST https://www.donationalerts.com/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=authorization_code&client_id=<client_id>&client_secret=<client_secret>&redirect_uri=<redirect_uri>&code=<code>"
```

### Response
#### Success Response (200)
- **token_type** (string) - The type of token, usually `Bearer`.
- **expires_in** (integer) - The number of seconds until the access token expires.
- **access_token** (string) - The access token used for authenticating API requests.
- **refresh_token** (string) - A token used to obtain a new access token when the current one expires.

#### Response Example
```json
{
    "token_type": "Bearer",
    "access_token": "...msdisYBVnciOiJSUzI1NiIsImp0aSI6IjQxZDU0ZGQ2O...",
    "expires_in": 631151999,
    "refresh_token": "...173da4e0ff4d48c8cbde7a0071f770624a83259f0a11cd02ec1ce71fe924c4..."
}
```
```

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

### Get User Profile Information (API)

Source: https://www.donationalerts.com/apidoc/index

Retrieves the authenticated user's profile information. Requires the `oauth-user-show` scope for authorization. The response includes user ID, username, display name, avatar URL, email, and a socket connection token.

```curl
curl \
    -X GET https://www.donationalerts.com/api/v1/user/oauth \
    -H "Authorization: Bearer <token>"
```

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

### Get User Data from Promocode

Source: https://www.donationalerts.com/apidoc/index

Obtains user ID from an advertising promocode. This API is part of the Merchandise Advertisement API and can be used to get a user ID to pass to the Send Sale Alerts API.

```APIDOC
## GET /api/v1/merchandise/user

### Description
Obtains user ID from an advertising promocode. This API is part of the Merchandise Advertisement API.

### Method
GET

### Endpoint
https://www.donationalerts.com/api/v1/merchandise/user

### Parameters
#### Query Parameters
- **promocode** (string) - Required - User promocode
- **signature** (string) - Required - Request signature

### Request Example
```curl
curl \
-X GET https://www.donationalerts.com/api/v1/merchandise/user?promocode=test123&signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6 \
-H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **user_id** (integer) - DonationAlerts user ID to which this advertising promocode is referenced

#### Response Example
```json
{
    "data": {
        "user_id": 3
    }
}
```
```

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

### GET /oauth/authorize - Authorization Request

Source: https://www.donationalerts.com/apidoc/index

Initiates the OAuth authorization flow, redirecting the user to the DonationAlerts service to grant access to their account.

```APIDOC
## GET /oauth/authorize - Authorization Request

### Description
Initiates the OAuth authorization flow. The user is redirected to the DonationAlerts service to authenticate and authorize the application's access to their account. Upon successful authorization, the user is redirected back to the application's specified `redirect_uri` with an access token.

### Method
GET

### Endpoint
https://www.donationalerts.com/oauth/authorize

### Parameters
#### Query Parameters
- **client_id** (integer) - Required - The client ID received from DonationAlerts.
- **redirect_uri** (string) - Required - The URL in your application where users will be sent after authorization.
- **response_type** (string) - Required - Specifies that the application is requesting an access token; must be `token` for the implicit grant.
- **scope** (string) - Required - A space-delimited list of scopes the application is requesting.

### Request Example
(No explicit request body, parameters are in the URL)

### Response
#### Success Response (Implicit Grant)
Upon user authorization, the user-agent is redirected to the `redirect_uri` with the access token in the hash part of the URL.
- **access_token** (string) - The access token granted to the application.

#### Response Example
(Redirection to `redirect_uri` with fragment identifier)
`https://your-redirect-uri.com/callback#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&scope=read_profile`
```

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

### GET /api/v1/alerts/donations

Source: https://www.donationalerts.com/apidoc/index

Obtains an array of user donation alerts. Requires user authorization with the `oauth-donation-index` scope.

```APIDOC
## GET /api/v1/alerts/donations

### Description
Obtains an array of objects of user donation alerts list. Requires user authorization with the `oauth-donation-index` scope.

### Method
GET

### Endpoint
`https://www.donationalerts.com/api/v1/alerts/donations`

### Parameters
#### Query Parameters
- **id** (integer) - Required - The unique donation alert identifier
- **name** (string) - Required - Type of the alert. Always `donation` in this case
- **username** (string) - Required - The name of the user who sent the donation and the alert
- **message_type** (string) - Required - The message type. The possible values are `text` for a text messages and `audio` for an audio messages
- **message** (string) - Required - The message sent along with the donation and the alert
- **amount** (number) - Required - The donation amount
- **currency** (string) - Required - The currency code (ISO 4217 formatted)
- **is_shown** (integer) - Required - A flag indicating whether the alert was shown in the streamer's widget
- **created_at** (string) - Required - The donation date and time (YYYY-MM-DD HH.MM.SS formatted)
- **shown_at** (string, null) - Required - Date and time indicating when the alert was shown (YYYY-MM-DD HH.MM.SS formatted). Or `null` if the alert is not shown yet

### Request Example
```bash
curl \
    -X GET https://www.donationalerts.com/api/v1/alerts/donations \
    -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **data** (array) - An array of donation alert objects.
  - **id** (integer) - The unique donation alert identifier
  - **name** (string) - Type of the alert
  - **username** (string) - The name of the user who sent the donation
  - **message_type** (string) - The message type (`text` or `audio`)
  - **message** (string) - The message sent with the donation
  - **amount** (number) - The donation amount
  - **currency** (string) - The currency code
  - **is_shown** (integer) - Flag indicating if the alert was shown
  - **created_at** (string) - Donation date and time
  - **shown_at** (string, null) - Date and time the alert was shown, or null
- **links** (object) - Pagination links.
  - **first** (string) - URL for the first page of results
  - **last** (string) - URL for the last page of results
  - **prev** (string|null) - URL for the previous page
  - **next** (string|null) - URL for the next page
- **meta** (object) - Pagination metadata.
  - **current_page** (integer) - The current page number
  - **from** (integer) - The starting item number on the current page
  - **last_page** (integer) - The total number of pages
  - **path** (string) - The base URL for the paginated results
  - **per_page** (integer) - The number of items per page
  - **to** (integer) - The ending item number on the current page
  - **total** (integer) - The total number of items

#### Response Example
```json
{
    "data": [
        {
            "id": 30530030,
            "name": "donation",
            "username": "Ivan",
            "message_type": "text",
            "message": "Hello!",
            "amount": 500,
            "currency": "RUB",
            "is_shown": 1,
            "created_at": "2019-09-29 09:00:00",
            "shown_at": null
        }
    ],
    "links": {
        "first": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "last": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://www.donationalerts.com/api/v1/alerts/donations",
        "per_page": 30,
        "to": 1,
        "total": 1
    }
}
```
```

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

### HTTP Error Response Example

Source: https://www.donationalerts.com/apidoc/index

Illustrates a typical HTTP 401 Unauthorized error response from the DonationAlerts API. This includes the status line, headers, and a JSON body indicating the authentication failure.

```http
HTTP/1.1 401 Unauthorized
Server: nginx/1.13.5
Content-Type: application/json
```

```json
{
    "message": "Unauthenticated."
}
```

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

### Send Custom Alert Request (cURL)

Source: https://www.donationalerts.com/apidoc/index

This snippet demonstrates how to send a POST request to the custom_alert endpoint using cURL. It includes necessary headers like Authorization and Content-Type, and provides example form data for the alert. The request requires the `oauth-custom_alert-store` scope for authorization.

```curl
curl \
    -X POST https://www.donationalerts.com/api/v1/custom_alert \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "external_id=12&header=Custom%20header&message=Custom%20message&image_url=https%3A%2F%2Fcdn.frankerfacez.com%2Femoticon%2F408827%2F4"
```

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

### Get User ID from Promocode (cURL)

Source: https://www.donationalerts.com/apidoc/index

Retrieves a user ID based on a provided promocode. This is part of the Merchandise Advertisement API and requires a Bearer token for authentication. The request includes the promocode and a signature for verification.

```curl
curl \
-X GET https://www.donationalerts.com/api/v1/merchandise/user?promocode=test123&signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6 \
-H "Authorization: Bearer <token>"
```

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

### Create Merchandise with cURL

Source: https://www.donationalerts.com/apidoc/index

Demonstrates how to create a new merchandise item using a cURL command. This includes specifying product details, pricing, and locale-specific titles. Ensure you replace `<token>` with your actual API bearer token.

```curl
curl --location --request POST 'https://www.donationalerts.com/api/v1/merchandise' \
--header 'Authorization: Bearer <token>' \
--form 'merchant_identifier=MARKET_GAMES_MAIL_RU' \
--form 'merchandise_identifier=8082' \
--form 'title[en_US]=Credit case' \
--form 'title[ru_RU]=Кредитный кейс' \
--form 'is_active=1' \
--form 'is_percentage=1' \
--form 'currency=USD' \
--form 'price_user=30' \
--form 'price_service=15' \
--form 'url=https://market.games.mail.ru/game/1?product_id=8082&user_id={user_id}' \
--form 'img_url=https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png' \
--form 'signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6'
```

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

### Update or Create Merchandise using cURL

Source: https://www.donationalerts.com/apidoc/index

This cURL command demonstrates how to update an existing merchandise item or create a new one if it doesn't exist. It includes parameters for title, activation status, pricing, currency, and URLs. The `signature` parameter is required for authentication.

```curl
curl --location --request PUT 'https://www.donationalerts.com/api/v1/merchandise/MARKET_GAMES_MAIL_RU/8082' \
--header 'Authorization: Bearer <token>' \
--form 'title[en_US]=Credit case' \
--form 'title[ru_RU]=Кредитный кейс' \
--form 'is_active=1' \
--form 'is_percentage=1' \
--form 'currency=USD' \
--form 'price_user=30' \
--form 'price_service=15' \
--form 'url=https://market.games.mail.ru/game/1?product_id=8082&user_id={user_id}' \
--form 'img_url=https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png' \
--form 'signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6'
```

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

### Application Registration

Source: https://www.donationalerts.com/apidoc/index

Developers must register their application to obtain client credentials (client ID and client secret) necessary for API authentication.

```APIDOC
## Application Registration

### Description
Register your application to obtain unique client credentials (client ID and client secret). The `client_id` is public and used for identifying your application, while the `client_secret` is private and used for authenticating your application when accessing user data.

### Method
POST

### Endpoint
/oauth/register (Implied, not explicitly provided)

### Parameters
No explicit parameters mentioned for registration, but it results in the issuance of `client_id` and `client_secret`.

### Response
- **client_id** (string) - A unique identifier for your application.
- **client_secret** (string) - A secret key for your application's authentication.
```

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

### Connecting to Private Channels (WebSocket)

Source: https://www.donationalerts.com/apidoc/index

Establishes a connection to subscribed private channels using the obtained channel name and token via an existing WebSocket connection.

```APIDOC
## Connecting to Private Channels (WebSocket)

### Description
Sends a message via an established WebSocket connection to connect to a specific private channel using its associated token.

### Method
WebSocket Message

### Endpoint
(Via existing WebSocket connection)

### Request Body
- **params** (object) - Required - Parameters for the connection.
  - **channel** (string) - Required - The name of the private channel to connect to.
  - **token** (string) - Required - The Centrifugo connection token for the private channel.
- **method** (integer) - Required - Method identifier (1 for connection).
- **id** (integer) - Required - Message identifier.

### Request Example
```json
{
  "params": {
    "channel": "$alerts:donation_<user_id>",
    "token": "<connection_token>"
  },
  "method": 1,
  "id": 2
}
```

### Response
#### Success Response
- **result** (object) - Confirmation of successful channel connection.
  - **type** (integer) - Type of the result message.
  - **channel** (string) - The name of the connected channel.
  - **data** (object) - Additional data related to the connection.
    - **info** (object) - Connection information.
      - **user** (string) - User identifier.
      - **client** (string) - Client identifier.

#### Response Example
```json
{
  "result": {
    "type": 1,
    "channel": "$alerts:donation_3",
    "data": {
      "info": {
        "user": "1",
        "client": "d558c046-c679-43e3-a62d-65989ab55f7c"
      }
    }
  }
}
```
```

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

### Centrifugo Client Initialization Response

Source: https://www.donationalerts.com/apidoc/index

Illustrates the expected JSON response from the Centrifugo WebSocket server after successfully connecting and sending the initial connection message. It provides the Centrifugo client ID (UUIDv4) and the server version.

```json
{
    "id": 1,
    "result": {
        "client": "d558c046-c679-43e3-a62d-65989ab55f7c",
        "version": "2.2.1"
    }
}
```

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

### Donation Alerts List

Source: https://www.donationalerts.com/apidoc/index

Retrieves a list of donation alerts. Supports pagination.

```APIDOC
## GET /api/v1/alerts/donations

### Description
Retrieves a list of donation alerts. This endpoint supports pagination.

### Method
GET

### Endpoint
`https://www.donationalerts.com/api/v1/alerts/donations`

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve. Defaults to the first page if not specified.

### Request Example
```bash
curl \
    -X GET https://www.donationalerts.com/api/v1/alerts/donations?page=2 \
    -H "Authorization: Bearer <token>"
```

### Response
#### Success Response (200)
- **data** (array) - An array of donation alert objects.
- **links** (object) - Pagination links (first, last, prev, next).
- **meta** (object) - Pagination metadata (current_page, from, last_page, path, per_page, to, total).

#### Response Example
```json
{
    "data": [
        {
            "id": 30530030,
            "name": "donation",
            "username": "Ivan",
            "message": "Hello!",
            "amount": 500,
            "currency": "RUB",
            "is_shown": 1,
            "created_at": "2019-09-29 09:00:00",
            "shown_at": null
        }
    ],
    "links": {
        "first": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "last": "https://www.donationalerts.com/api/v1/alerts/donations?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "path": "https://www.donationalerts.com/api/v1/alerts/donations",
        "per_page": 30,
        "to": 1,
        "total": 1
    }
}
```
```

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

### Authorization Request

Source: https://www.donationalerts.com/apidoc/index

Initiate the OAuth 2.0 authorization flow by redirecting users to the authorization endpoint with specified parameters.

```APIDOC
## Authorization Request

### Description
Redirect users to this endpoint to request authorization for your application to access their DonationAlerts data. The user will log in and be prompted to grant or deny access.

### Method
GET

### Endpoint
`https://www.donationalerts.com/oauth/authorize`

### Parameters
#### Query Parameters
- **client_id** (integer) - Required - The client ID received from DonationAlerts upon registration.
- **redirect_uri** (string) - Required - The URL in your application where users will be redirected after authorization.
- **response_type** (string) - Required - Must be set to `code` to request an authorization code grant.
- **scope** (string) - Required - A space-delimited list of permissions your application is requesting (e.g., `user:profile`, `donations:read`).
```

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

### POST /api/v1/merchandise

Source: https://www.donationalerts.com/apidoc/index

Creates new merchandise. This endpoint allows merchants to add new items to their DonationAlerts store, specifying details such as identifier, title, pricing, and availability.

```APIDOC
## POST /api/v1/merchandise

### Description
Creates new merchandise. This API is a part of the Merchandise Advertisement API.

### Method
POST

### Endpoint
https://www.donationalerts.com/api/v1/merchandise

### Parameters
#### Query Parameters
- **merchant_identifier** (string) - Required - Merchant's ID on DonationAlerts
- **merchandise_identifier** (string) - Required - Up to 16 characters long unique merchandise ID generated by the merchant
- **title** (array) - Required - Array of up to 1024 characters long strings representing the name of the merchandise in different locales. At minimum, a title for the `en_US` locale is required
- **is_active** (integer) - Optional - A value containing 0 or 1. Determines whether the merchandise is available for purchase or not. Default value: 0
- **is_percentage** (integer) - Optional - A value containing 0 or 1. Determines whether the `price_service` and `price_user` parameters are recognized as amounts in a currency of the `currency` parameter or calculated as a percent of the sale's total. Default value: 0
- **currency** (string) - Required - One of the available currencies of merchandise. All revenue calculations will be performed according this value
- **price_user** (number) - Required - Amount of revenue added to streamer for each sale of the merchandise
- **price_service** (number) - Required - Amount of revenue added to DonationAlerts for each sale of the merchandise
- **url** (string) - Optional - Up to 128 characters long URL to the merchandise's web page. You may include the `{user_id}` and `{user_merchandise_promocode}` patterns in the URL that will be replaced in a UI with the user's ID and user's merchandise promocode
- **img_url** (string) - Optional - Up to 128 characters long URL to the merchandise's image
- **end_at_ts** (integer) - Optional - Date and time when the merchandise becomes inactive represented as Unix timestamp
- **signature** (string) - Required - Request signature

### Request Example
```curl
curl --location --request POST 'https://www.donationalerts.com/api/v1/merchandise' \
--header 'Authorization: Bearer <token>' \
--form 'merchant_identifier=MARKET_GAMES_MAIL_RU' \
--form 'merchandise_identifier=8082' \
--form 'title[en_US]=Credit case' \
--form 'title[ru_RU]=Кредитный кейс' \
--form 'is_active=1' \
--form 'is_percentage=1' \
--form 'currency=USD' \
--form 'price_user=30' \
--form 'price_service=15' \
--form 'url=https://market.games.mail.ru/game/1?product_id=8082&user_id={user_id}' \
--form 'img_url=https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png' \
--form 'signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6'
```

### Response
#### Success Response (201)
- **data** (object) - Contains the details of the created merchandise.
  - **id** (integer) - Unique merchandise ID on DonationAlerts
  - **merchant** (object) - Object carrying `identifier` and `name` fields that contains information about the merchant
    - **identifier** (string) - Unique merchandise ID on the merchant's online store
  - **identifier** (string) - Unique merchandise ID on the merchant's online store
  - **title** (object) - Object carrying merchandise's titles in different locales
  - **is_active** (integer) - A flag indicating whether the merchandise is available for purchase or not
  - **is_percentage** (integer) - A flag indicating whether the `price_service` and `price_user` parameters should be recognized as absolute values of the `currency` currency or as a percent of the sale's total
  - **currency** (string) - The currency code of the merchandise (ISO 4217 formatted)
  - **price_user** (number) - Amount of revenue added to streamer for each sale of the merchandise
  - **price_service** (number) - Amount of revenue added to DonationAlerts for each sale of the merchandise
  - **url** (string, null) - URL to the merchandise's web page. Or `null` if URL is not set
  - **img_url** (string, null) - URL to the merchandise's image. Or `null` if image is not set
  - **end_at** (string, null) - Date and time indicating when the merchandise becomes inactive (YYYY-MM-DD HH.MM.SS formatted). Or `null` if end date is not set

#### Response Example
```json
{
    "data": {
        "id": 3,
        "merchant": {
            "identifier": "MARKET_GAMES_MAIL_RU",
            "name": "Market games@mail.ru"
        },
        "identifier": "8082",
        "title": {
            "en_US": "Credit case",
            "ru_RU": "Кредитный кейс"
        },
        "is_active": 1,
        "is_percentage": 1,
        "currency": "USD",
        "price_user": 30,
        "price_service": 15,
        "url": "https://market.games.mail.ru/game/1?product_id=8082&user_id={user_id}",
        "img_url": "https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png",
        "end_at": null
    }
}
```
```

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

### Send Merchandise Sale Alert (cURL)

Source: https://www.donationalerts.com/apidoc/index

Creates a new merchandise sale alert. This API is part of the Merchandise Advertisement API and requires various parameters including user ID, external sale ID, merchant and merchandise identifiers, amount, currency, and a request signature. Authentication is done via a Bearer token.

```curl
curl --location --request POST 'https://www.donationalerts.com/api/v1/merchandise_sale' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'user_id=3' \
--data-urlencode 'amount=100' \
--data-urlencode 'currency=RUB' \
--data-urlencode 'merchant_identifier=MARKET_GAMES_MAIL_RU' \
--data-urlencode 'merchandise_identifier=3372' \
--data-urlencode 'external_id=1' \
--data-urlencode 'bought_amount=2' \
--data-urlencode 'username=John' \
--data-urlencode 'message=This is a test message' \
--data-urlencode 'signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6'
```

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

### Send Sale Alerts

Source: https://www.donationalerts.com/apidoc/index

Creates a new merchandise sale alert. This API is part of the Merchandise Advertisement API.

```APIDOC
## POST /api/v1/merchandise_sale

### Description
Creates new merchandise sale alert. This API is part of the Merchandise Advertisement API.

### Method
POST

### Endpoint
https://www.donationalerts.com/api/v1/merchandise_sale

### Parameters
#### Query Parameters
- **user_id** (integer) - Required - DonationAlerts' user ID to which this merchandise sale referenced
- **external_id** (string) - Required - Up to 32 characters long unique sale ID generated by the developer
- **merchant_identifier** (string) - Required - Merchant's ID on DonationAlerts
- **merchandise_identifier** (string) - Required - Merchant's merchandise ID which was bought by the customer
- **amount** (number) - Required - Grand total of the sale
- **currency** (string) - Required - One of the available currencies of merchandise sale indicating the currency of `amount`
- **bought_amount** (integer) - Optional - Total number of bought items. Default value: 1
- **username** (string) - Optional - The name of the customer
- **message** (string) - Optional - The message sent by the customer while purchasing the merchandise
- **signature** (string) - Required - Request signature

### Request Example
```curl
curl --location --request POST 'https://www.donationalerts.com/api/v1/merchandise_sale' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'user_id=3' \
--data-urlencode 'amount=100' \
--data-urlencode 'currency=RUB' \
--data-urlencode 'merchant_identifier=MARKET_GAMES_MAIL_RU' \
--data-urlencode 'merchandise_identifier=3372' \
--data-urlencode 'external_id=1' \
--data-urlencode 'bought_amount=2' \
--data-urlencode 'username=John' \
--data-urlencode 'message=This is a test message' \
--data-urlencode 'signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6'
```

### Response
#### Success Response (201)
- **id** (integer) - The unique merchandise sale alert identifier
- **name** (string) - Type of the generated alert
- **external_id** (string) - Unique sale ID generated by the developer
- **username** (string, null) - The name of the customer. Or `null` if customer is unknown
- **message** (string, null) - The message sent by the customer while purchasing the merchandise. Or `null` if text was not provided
- **amount** (number) - Grand total amount of the sale
- **currency** (string) - The currency code of the merchandise sale (ISO 4217 formatted)
- **bought_amount** (integer) - Total number of bought items
- **is_shown** (integer) - A flag indicating whether the alert was shown in the streamer's widget
- **created_at** (string) - The date and time (YYYY-MM-DD HH.MM.SS formatted) when sale alert was created
- **shown_at** (string, null) - Date and time indicating when the alert was shown (YYYY-MM-DD HH.MM.SS formatted). Or `null` if the alert is not shown yet

#### Response Example
```json
{
    "data": {
        "id": 153,
        "name": "merchandise-sale",
        "external_id": 1,
        "username": "John",
        "message": "This is a test message",
        "amount": 100,
        "currency": "RUB",
        "bought_amount": 2,
        "created_at": "2020-11-15 11:36:14",
        "is_shown": 0,
        "shown_at": null
    }
}
```
```

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

### POST /api/v1/custom_alert

Source: https://www.donationalerts.com/apidoc/index

Sends a custom alert to the authorized user. Requires user authorization with the `oauth-custom_alert-store` scope.

```APIDOC
## POST /api/v1/custom_alert

### Description
Sends a custom alert to the authorized user. Requires user authorization with the `oauth-custom_alert-store` scope.

### Method
POST

### Endpoint
https://www.donationalerts.com/api/v1/custom_alert

### Parameters
#### Query Parameters
- **external_id** (string) - Required - Up to 32 characters long unique alert ID generated by the application developer.
- **header** (string) - Required - Up to 255 characters long string that will be displayed as a header.
- **message** (string) - Required - Up to 300 characters long string that will be displayed inside the message box.
- **is_shown** (integer) - Optional - A value containing 0 or 1. Determines whether the alert should be displayed or not. Default value: 0.
- **image_url** (string) - Optional - Up to 255 characters long URL to the image file that will displayed along with the custom alert.
- **sound_url** (string) - Optional - Up to 255 characters long URL to the sound file that will played when displaying the custom alert.

### Request Example
```curl
    -X POST https://www.donationalerts.com/api/v1/custom_alert \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "external_id=12&header=Custom%20header&message=Custom%20message&image_url=https%3A%2F%2Fcdn.frankerfacez.com%2Femoticon%2F408827%2F4"
```

### Response
#### Success Response (201)
- **data** (object) - Contains the details of the created custom alert.
  - **id** (integer) - The unique custom alert identifier.
  - **external_id** (string) - Unique alert ID generated by the application developer.
  - **header** (string) - Text that will be displayed as a header.
  - **message** (string) - Text that will be displayed inside the message box.
  - **image_url** (string) - URL to the image file that will displayed along with the custom alert.
  - **sound_url** (string, null) - URL to the sound file that will played when displaying the custom alert, or null if not provided.
  - **is_shown** (integer) - A flag indicating whether the alert was shown in the streamer's widget.
  - **created_at** (string) - The date and time (YYYY-MM-DD HH.MM.SS formatted) when custom alert was created.
  - **shown_at** (string, null) - Date and time indicating when the alert was shown (YYYY-MM-DD HH.MM.SS formatted), or null if the alert is not shown yet.

#### Response Example
```json
{
    "data": {
        "id": 24,
        "external_id": "12",
        "header": "Custom header",
        "message": "Custom message",
        "image_url": "https://cdn.frankerfacez.com/emoticon/408827/4",
        "sound_url": null,
        "is_shown": 0,
        "created_at": "2020-09-24 12:04:23",
        "shown_at": null
    }
}
```
```

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

### Authorization Request URL for Implicit Grant

Source: https://www.donationalerts.com/apidoc/index

This snippet shows the structure of the URL used to request authorization from a user for the implicit grant type. It includes the client ID, redirect URI, response type, and requested scopes.

```URL
https://www.donationalerts.com/oauth/authorize?client_id=<client_id>&redirect_uri=<redirect_uri>&response_type=token&scope=<scope>
```

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

### Update Merchandise using cURL

Source: https://www.donationalerts.com/apidoc/index

This snippet demonstrates how to update merchandise details using a PUT request with cURL. It includes parameters for title in different locales, activation status, pricing, currency, and a signature for authentication. The request body is form-urlencoded.

```curl
curl --location --request PUT 'https://www.donationalerts.com/api/v1/merchandise/3' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'title[en_US]=Credit case' \
--data-urlencode 'title[ru_RU]=Кредитный кейс' \
--data-urlencode 'is_active=1' \
--data-urlencode 'is_percentage=1' \
--data-urlencode 'currency=USD' \
--data-urlencode 'price_user=30' \
--data-urlencode 'price_service=15' \
--data-urlencode 'url=https://market.games.mail.ru/game/1?product_id=8082' \
--data-urlencode 'img_url=https://market.games.mail.ru/s3/media/product/picture/2020/7/a5077d65bed0439dd78a01d12cee948d.png' \
--data-urlencode 'signature=0d02b19c49ebbefb86d6bfa8b250d597da8e31a612ec57c315160a0ddc1a76f6'
```

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

### Successful Private Channel Connection Confirmation

Source: https://www.donationalerts.com/apidoc/index

This snippet represents the confirmation message received after successfully connecting to a private channel. It includes details about the connection type, channel, and associated data.

```json
{
   "result": {
        "type": 1,
        "channel": "$alerts:donation_3",
        "data": {
            "info": {
                "user": "1",
                "client": "d558c046-c679-43e3-a62d-65989ab55f7c"
            }
        }
    }
}
```

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

### Exchange Authorization Code for Access Token (cURL)

Source: https://www.donationalerts.com/apidoc/index

This snippet demonstrates how to exchange an authorization code for an access token using a cURL request. It requires the `grant_type`, `client_id`, `client_secret`, `redirect_uri`, and the obtained `code`. The API responds with a JSON object containing the `token_type`, `access_token`, `expires_in`, and `refresh_token`.

```curl
curl \
    -X POST https://www.donationalerts.com/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=authorization_code&client_id=<client_id>\
&client_secret=<client_secret>&redirect_uri=<redirect_uri>&code=<code>"
```

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

### Connect to Private Channels via WebSocket

Source: https://www.donationalerts.com/apidoc/index

This snippet shows the JSON message format required to connect to a subscribed private channel over an established WebSocket connection. It includes the channel name and the obtained connection token.

```json
{
    "params": {
        "channel": "$alerts:donation_<user_id>",
        "token": "<connection_token>"
    },
    "method": 1,
    "id": 2
}
```

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

### Paginate DonationAlerts API Request

Source: https://www.donationalerts.com/apidoc/index

Shows how to retrieve a specific page of donation alerts from the DonationAlerts API by adding the 'page' parameter to the query. This is useful for handling large datasets.

```curl
curl \
    -X GET https://www.donationalerts.com/api/v1/alerts/donations?page=2 \
    -H "Authorization: Bearer <token>"
```