### POST /websites/appmax_readme_io_reference/install

Source: https://appmax.readme.io/reference/instala%C3%A7%C3%A3o-do-aplicativo

Callback endpoint for application installation. Appmax sends application details and expects an external ID in return.

```APIDOC
## POST /websites/appmax_readme_io_reference/install

### Description
This endpoint is called by Appmax when a merchant installs your application. It receives authentication credentials and an optional external key. Your system should process this information and return a unique external ID.

### Method
POST

### Endpoint
/websites/appmax_readme_io_reference/install

### Parameters
#### Request Body
- **app_id** (string) - Required - The ID of the installed application.
- **client_id** (string) - Required - The client ID for authenticating with the Appmax API.
- **client_secret** (string) - Required - The client secret for authenticating with the Appmax API.
- **external_key** (string) - Optional - A key provided by the user for precise identification.

### Request Example
```json
{
  "app_id": "40ee00a1-6e69-44ce-b3fa-389cd3757982",
  "client_id": "1c0lbbbt5mah24j634f9tdpamv",
  "client_secret": "1dvsas7ts4fnkto10qfu44106bmg9e4fqhrq6270nv1v2topcf61",
  "external_key": ""
}
```

### Response
#### Success Response (200)
- **external_id** (string) - A unique ID stored in your database to identify the created link.

#### Response Example
```json
{
  "external_id": "37bb0791-ee0b-457d-860c-186e32978bcd"
}
```
```

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

### Authorize Application Installation

Source: https://appmax.readme.io/reference/instalacao-do-aplicativo

This endpoint generates a hash required to authorize the installation of an application and create merchant credentials. It requires the application's access token.

```APIDOC
## POST /app/authorize

### Description
Generates an authorization hash required for redirecting users to Appmax to authorize application installation and create merchant credentials. Requires a Bearer token obtained from the `/oauth2/token` endpoint.

### Method
POST

### Endpoint
https://api.appmax.com.br/app/authorize

### Parameters
#### Request Body
- **app_id** (string) - Required - The API key for your application.
- **external_key** (string) - Required - A key provided by the partner platform to identify the installation source.
- **url_callback** (string) - Required - The URL to redirect to after successful authorization.

### Request Example
```curl
curl --location 'https://api.appmax.com.br/app/authorize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer SEU_TOKEN' \
--data '{ 
    "app_id": "APP_ID",
    "external_key": "EXTERNAL_KEY",
    "url_callback": "URL_CALLBACK"
}'
```

### Response
#### Success Response (200)
- **data** (object)
  - **token** (string) - The generated authorization hash.

#### Response Example
```json
{
    "data": {
        "token": "12083w36219d223f33ecf48f2a7f5ccf143b0bc554"
    }
}
```

### Redirection URLs
Use the generated hash to redirect users to the Appmax platform for authorization.

* **Sandbox**: `https://breakingcode.sandboxappmax.com.br/appstore/integration/HASH`
* **Production**: `https://admin.appmax.com.br/appstore/integration/HASH`

Replace `HASH` with the token received in the response.
```

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

### Authorize Appmax Application Installation (cURL)

Source: https://appmax.readme.io/reference/instalacao-do-aplicativo

This snippet shows how to authorize the installation of an application by generating an authorization hash. It requires the application ID, an external key, and a callback URL. The generated hash is then used in a redirection URL to complete the merchant credential creation.

```curl
curl --location 'https://api.appmax.com.br/app/authorize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer SEU_TOKEN' \
--data '{
    "app_id": "APP_ID",
    "external_key": "EXTERNAL_KEY",
    "url_callback": "URL_CALLBACK"
}'
```

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

### App Installation and Authentication Flow

Source: https://appmax.readme.io/reference/faq

This section details the step-by-step process for installing and authenticating an application with Appmax, including API endpoints and required parameters.

```APIDOC
## App Installation and Authentication Flow

### Description
This flow outlines the necessary steps to integrate an application with Appmax, from obtaining an initial token to generating merchant API credentials. It addresses common issues like the "500 Internal Server Error" which often stem from skipping the user authorization step.

### Step 1: Obtain Application Token

#### Method
POST

#### Endpoint
`https://auth.sandboxappmax.com.br/oauth2/token`

#### Description
Use your application's credentials to obtain an access token. This token is required for subsequent API calls.

#### Request Body
- `grant_type` (string) - Required - Typically 'client_credentials'
- `client_id` (string) - Required - Your application's client ID
- `client_secret` (string) - Required - Your application's client secret

#### Request Example
```curl
curl --location 'https://auth.sandboxappmax.com.br/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: XSRF-TOKEN=26949a8d-9d53-44ff-845c-bd5a09cd1f34' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=YOUR_CLIENT_ID' \
--data-urlencode 'client_secret=YOUR_CLIENT_SECRET'
```

### Step 2: Generate Authorization Hash

#### Method
POST

#### Endpoint
`https://api.sandboxappmax.com.br/app/authorize`

#### Description
With the obtained token, make a POST request to generate an authorization hash. This hash is crucial for the merchant to authorize the app installation.

#### Parameters
##### Request Body
- `app_id` (string) - Required - Your application's ID
- `client_key` (string) - Required - Your application's client key
- `url_callback` (string) - Required - The callback URL for the integration

### Step 3: Redirect User for Installation Authorization

#### Method
GET (Redirect)

#### Endpoint
`https://breakingcode.sandboxappmax.com.br/appstore/integration/HASH`

#### Description
Redirect the user (merchant) to this URL using the authorization hash generated in the previous step. This is where the merchant explicitly authorizes the app installation.

### Step 4: Generate Merchant API Credentials

#### Method
POST

#### Endpoint
`https://api.sandboxappmax.com.br/app/client/generate`

#### Description
After the merchant authorizes the installation, use the same authorization hash in a POST request to generate the `client_id` and `client_secret` for the merchant's API usage.

#### Parameters
##### Request Body
- `hash` (string) - Required - The authorization hash obtained in Step 2

#### Response
##### Success Response (200)
- `client_id` (string) - The client ID for the merchant's API access
- `client_secret` (string) - The client secret for the merchant's API access

### Summary of Error Cause

The "500 Internal Server Error - an error occurred while integrating the app. Please try again" typically occurs because the crucial step of redirecting the user to authorize the app installation (Step 3) is omitted. Without this authorization, the merchant's API credentials cannot be generated, leading to integration failures.
```

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

### App Installation POST Request Payload (JSON)

Source: https://appmax.readme.io/reference/instala%C3%A7%C3%A3o-do-aplicativo

This JSON payload is sent via POST request to the merchant's validation URL when an application is installed. It includes the application ID, Appmax API credentials (client_id, client_secret), and an optional external_key for precise identification.

```json
{
  "app_id": "40ee00a1-6e69-44ce-b3fa-389cd3757982",
  "client_id": "1c0lbbbt5mah24j634f9tdpamv",
  "client_secret": "1dvsas7ts4fnkto10qfu44106bmg9e4fqhrq6270nv1v2topcf61",
  "external_key": ""
}
```

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

### Obtain Application Access Token

Source: https://appmax.readme.io/reference/instalacao-do-aplicativo

This endpoint is used to obtain an access token for your application. This token is required for subsequent authenticated requests.

```APIDOC
## POST /oauth2/token

### Description
Obtains an access token for your application, which is necessary for making authenticated requests to the Appmax API.

### Method
POST

### Endpoint
https://auth.appmax.com.br/oauth2/token

### Parameters
#### Query Parameters
- **grant_type** (string) - Required - Must be 'client_credentials'.
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.

### Request Example
```curl
curl --location 'https://auth.appmax.com.br/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET'
```

### Response
#### Success Response (200)
- **access_token** (string) - The obtained Bearer token.
- **token_type** (string) - The type of token, usually 'Bearer'.
- **expires_in** (integer) - The token's expiration time in seconds.

#### Response Example
```json
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp...",
    "token_type": "Bearer",
    "expires_in": 3600
}
```
```

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

### Store Identification During App Installation

Source: https://appmax.readme.io/reference/faq

Explains how the integration identifies the store installing the application and the associated flow.

```APIDOC
## Store Identification During App Installation

### Description
This section details how Appmax identifies the specific store (merchant) initiating an application installation and the corresponding API flow.

### Identification Process

When an application installation is initiated directly from an integration platform:

1.  **User Login:** The store's identification is established through the user's login on the external platform.

2.  **Initiate Installation:** Clicking "Install" on the integration platform triggers the generation of a token via the `/app/authorize` endpoint.
    *   **Endpoint:** `https://api.appmax.com.br/app/authorize`

3.  **Merchant Authorization Redirect:** The merchant is then redirected to the Appmax App Store integration flow.
    *   **Endpoint:** `https://admin.appmax.com.br/appstore/integration/TOKEN_GERADO` (where `TOKEN_GERADO` is the hash from the previous step).
    *   **Action:** During this redirection, the merchant must provide their store name and select their registered company on Appmax (requires an existing Appmax account and login).

4.  **Generate Merchant Credentials:** After the merchant authorizes the installation, the same short-lived hash is used to generate the merchant's API credentials.
    *   **Endpoint:** `https://api.appmax.com.br/app/client/generate`

### Credential Lifespan

- The authorization hash can only be used **once**.
- However, the generated `client_id` and `client_secret` credentials are **valid indefinitely** until the application is uninstalled.
```

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

### Configure Recurring Order with Subscription Object (JSON)

Source: https://appmax.readme.io/reference/como-criar-recorrencia-na-appmax

Example of a JSON payload for creating a recurring order. It includes the `subscription` object within `payment_data` to define the recurrence period and count. This structure is compatible with both tokenized and non-tokenized credit cards, as well as Pix payments.

```json
{
    "order_id": 99,
    "payment_data": {
        //credit_card, pix..
        "subscription": {
            "interval": "month",
            "interval_count": 1
        }
    }
}
```

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

### CURL Example for OAuth2 Token Request

Source: https://appmax.readme.io/reference/faq

This example demonstrates how to correctly request an OAuth2 token using CURL. It specifies the correct endpoint for authentication and includes necessary headers and data parameters for the request. This is crucial for resolving '403 Forbidden' errors related to the /oauth2/token endpoint.

```curl
curl --location 'https://auth.sandboxappmax.com.br/oauth2/token' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--header 'Cookie: XSRF-TOKEN=26949a8d-9d53-44ff-845c-bd5a09cd1f34' \

--data-urlencode 'grant_type=client_credentials' \

--data-urlencode 'client_id=CLIENT_ID' \

--data-urlencode 'client_secret=CLIENT_SECRET'
```

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

### Installation Validation

Source: https://appmax.readme.io/reference/fluxo-de-autentica%C3%A7%C3%A3o-e-autoriza%C3%A7%C3%A3o-na-api-da-appmax

This endpoint is called when a merchant installs the application. It receives installation details and should respond with a 200 status code and an external_id.

```APIDOC
## POST /validation/url (Assumed Endpoint)

### Description
This endpoint is called by Appmax upon application installation by a merchant. It receives application and merchant identification details and expects a 200 OK response with an `external_id`.

### Method
POST

### Endpoint
[URL specified in the 'URL de validação' field during app creation]

### Parameters
#### Request Body
- **app_id** (string) - Required - The ID of the application.
- **client_id** (string) - Required - The merchant's client ID.
- **client_secret** (string) - Required - The merchant's client secret.
- **external_key** (string) - Optional - A key provided by users for precise identification.

### Request Example
```json
{
  "app_id": "APP_ID",
  "client_id": "MERCHANT_CLIENT_ID",
  "client_secret": "MERCHANT_CLIENT_SECRET",
  "external_key": "EXTERNAL_KEY"
}
```

### Response
#### Success Response (200)
- **external_id** (string) - A unique ID for the installation, to be stored in your database.

#### Response Example
```json
{
  "external_id": "37bb0791-ee0b-457d-860c-186e32978bcd"
}
```
```

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

### Authorize App Installation

Source: https://appmax.readme.io/reference/fluxo-de-autentica%C3%A7%C3%A3o-e-autoriza%C3%A7%C3%A3o-na-api-da-appmax

This endpoint is used to authorize the application installation and generate a hash for redirecting to create merchant credentials. It requires the application's access token.

```APIDOC
## POST /app/authorize

### Description
Authorizes the application installation and generates a hash for merchant credential creation.

### Method
POST

### Endpoint
https://api.appmax.com.br/app/authorize

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer token obtained from the `/oauth2/token` endpoint.

#### Request Body
- **app_id** (string) - Required - The ID of your application.
- **external_key** (string) - Required - An external key for identification.
- **url_callback** (string) - Required - The callback URL for the integration.

### Request Example
```curl
curl --location 'https://api.appmax.com.br/app/authorize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer SEU_TOKEN' \
--data '{
    "app_id": "APP_ID",
    "external_key": "EXTERNAL_KEY",
    "url_callback": "URL_CALLBACK"
}'
```
```

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

### Obtain Appmax Access Token (cURL)

Source: https://appmax.readme.io/reference/instalacao-do-aplicativo

This snippet demonstrates how to obtain an access token for your application using a POST request to the Appmax authentication endpoint. It requires client credentials and returns a Bearer token that is valid for a specified duration.

```curl
curl --location 'https://auth.appmax.com.br/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET'
```

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

### Appmax API Response Examples

Source: https://appmax.readme.io/reference/cria%C3%A7%C3%A3o-de-destinat%C3%A1rio-recipient-via-fast-onboarding

This snippet shows example JSON responses from the Appmax API. It includes a successful response for recipient creation (201) and error responses for missing authentication (403) and validation errors (422). The 422 response details specific fields that are missing or invalid.

```json
{
    "data": {
        "recipient_hash": "bbd96f57-3e3c-5ea1-aa60-cb2518578faf"
    }
}
```

```json
{
  "message": "Missing Authentication Token"
}
```

```json
{
    "account.name": [
        "O campo account.name é obrigatório."
    ],
    "account.cpf": [
        "O campo account.cpf é obrigatório."
    ],
    "account.email": [
        "O campo account.email é obrigatório."
    ],
    "account.phone": [
        "O campo account.phone é obrigatório."
    ],
    "account.dateOfBirth": [
        "O campo account.date of birth é obrigatório."
    ],
    "company.companyName": [
        "O campo company.company name é obrigatório."
    ],
    "company.companyDocumentNumber": [
   		 	"O campo company.company document number é obrigatório.",
       	"O valor indicado para o campo company.company document number já se encontra utilizado."
    ],
    "company.companyPostcode": [
        "O campo company.company postcode é obrigatório."
    ],
    "company.companyAddress": [
        "O campo company.company address é obrigatório."
    ],
    "company.companyAddressNumber": [
        "O campo company.company address number é obrigatório."
    ],
    "company.companyAddressState": [
        "O campo company.company address state é obrigatório."
    ],
    "company.companyCity": [
        "O campo company.company city é obrigatório."
    ],
    "company.personType": [
        "O campo company.person type é obrigatório."
    ],
    "company.companyAddressNeighborhood": [
        "O campo company.company address neighborhood é obrigatório."
    ],
    "triage.revenue": [
        "O campo triage.revenue é obrigatório."
    ],
    "triage.storeUrl": [
        "O campo triage.store url é obrigatório."
    ]
}
```

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

### Simulate Recipient Withdrawal Anticipation (GET)

Source: https://appmax.readme.io/reference/simular-antecipacao-de-saque-do-recebedor-recipient

This endpoint simulates a withdrawal anticipation request for a specific recipient. It requires an authorization token and the withdrawal value in cents as a query parameter. The response includes estimated values for the anticipation or error messages for invalid requests.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "API AppStore",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.appmax.com.br/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "oauth2",
        "flows": {}
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/recipient/{recipient_hash}/withdraw-request/anticipation/simulate": {
      "get": {
        "summary": "11.6 Simular Antecipação de Saque do Recebedor",
        "description": "Este endpoint permite simular uma solicitação de antecipação de saque para um recipient específico e retorna os valores estimados.",
        "operationId": "simular-antecipacao-de-saque-do-recebedor-recipient",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "description": "Informa que o cliente espera receber a resposta no formato JSON.",
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "description": "Indica que o corpo da requisição está sendo enviado no formato JSON.",
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Token de autorização do seu aplicativo",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "value",
            "in": "query",
            "description": "Valor do saque a ser utilizado na simulação de antecipação ( Em centavos )",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"data\": {\n        \"value\": 10000,\n        \"net_value\": 4700,\n        \"withdraw_tax\": 300,\n        \"tax_percentage\": 300\n    }\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "value": {
                          "type": "integer",
                          "example": 10000,
                          "default": 0
                        },
                        "net_value": {
                          "type": "integer",
                          "example": 4700,
                          "default": 0
                        },
                        "withdraw_tax": {
                          "type": "integer",
                          "example": 300,
                          "default": 0
                        },
                        "tax_percentage": {
                          "type": "integer",
                          "example": 300,
                          "default": 0
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"error\": \"Insufficient balance\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Insufficient balance"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "403",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"error\": \"Recipient does not belong to this company\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Recipient does not belong to this company"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "404",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{
  "error": "Recipient not found"
}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Recipient not found"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

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

### GET /recipient/{recipient_hash}/withdraw-request/anticipation/simulate

Source: https://appmax.readme.io/reference/simular-antecipacao-de-saque-do-recebedor-recipient

Simulates a withdrawal anticipation request for a specific recipient, returning estimated values.

```APIDOC
## GET /recipient/{recipient_hash}/withdraw-request/anticipation/simulate

### Description
This endpoint allows simulating a withdrawal anticipation request for a specific recipient and returns the estimated values.

### Method
GET

### Endpoint
https://api.appmax.com.br/v1/recipient/{recipient_hash}/withdraw-request/anticipation/simulate

### Parameters
#### Path Parameters
- **recipient_hash** (string) - Required - The unique hash of the recipient.

#### Query Parameters
- **value** (string) - Required - The withdrawal amount to be used in the anticipation simulation (in cents).

#### Header Parameters
- **Accept** (string) - Optional - Specifies that the client expects the response in JSON format. Default: `application/json`.
- **Content-Type** (string) - Optional - Indicates that the request body is sent in JSON format. Default: `application/json`.
- **Authorization** (string) - Required - Authorization token for your application.

### Request Example
```json
{
  "example": "GET /v1/recipient/some_hash/withdraw-request/anticipation/simulate?value=10000"
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the simulation results.
  - **value** (integer) - The original withdrawal value (in cents).
  - **net_value** (integer) - The net value after taxes (in cents).
  - **withdraw_tax** (integer) - The withdrawal tax amount (in cents).
  - **tax_percentage** (integer) - The tax percentage applied.

#### Response Example (200)
```json
{
    "data": {
        "value": 10000,
        "net_value": 4700,
        "withdraw_tax": 300,
        "tax_percentage": 300
    }
}
```

#### Error Response (400)
- **error** (string) - Description of the error. Example: `Insufficient balance`.

#### Response Example (400)
```json
{
  "error": "Insufficient balance"
}
```

#### Error Response (403)
- **error** (string) - Description of the error. Example: `Recipient does not belong to this company`.

#### Response Example (403)
```json
{
    "error": "Recipient does not belong to this company"
}
```

#### Error Response (404)
- **error** (string) - Description of the error. Example: `Recipient not found`.

#### Response Example (404)
```json
{
    "error": "Recipient not found"
}
```
```

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

### Recurring Payments with Credit Card and Pix

Source: https://appmax.readme.io/reference/como-criar-recorrencia-na-appmax

To enable recurring payments for credit card and Pix transactions, include the `subscription` object within the `payment_data` payload. This object specifies the recurrence interval and count.

```APIDOC
## POST /api/orders (Example for Credit Card/Pix)

### Description
This endpoint is used to create an order with recurring payment information.

### Method
POST

### Endpoint
/api/orders

### Parameters
#### Request Body
- **order_id** (integer) - Required - The unique identifier for the order.
- **payment_data** (object) - Required - Contains payment details.
  - **subscription** (object) - Required - Defines the recurring payment schedule.
    - **interval** (string) - Required - The period of recurrence. Valid values: `month`, `year`.
    - **interval_count** (integer) - Required - The number of cycles for the interval. Valid values: 1 to 12.

### Request Example
```json
{
    "order_id": 99,
    "payment_data": {
        "subscription": {
            "interval": "month",
            "interval_count": 1
        }
    }
}
```

### Response
#### Success Response (200)
- **order_id** (integer) - The ID of the created order.
- **status** (string) - The status of the order.

#### Response Example
```json
{
    "order_id": 99,
    "status": "pending"
}
```
```

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

### Create Split Order - POST Request (OpenAPI)

Source: https://appmax.readme.io/reference/criar-split-de-pedido

Defines the OpenAPI specification for creating a split order. It includes details on the endpoint, HTTP method, parameters (headers, path), request body schema, and possible responses (201, 422, 500) with example payloads.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "API AppStore",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.appmax.com.br/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "oauth2",
        "flows": {}
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/orders/{orderId}/split-order": {
      "post": {
        "summary": "11.4 Criar Split de Pedido",
        "description": "Criar split de pedido",
        "operationId": "criar-split-de-pedido",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "description": "Informa que o cliente espera receber a resposta no formato JSON.",
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          },
          {
            "name": "Content-Type",
            "in": "header",
            "description": "Indica que o corpo da requisição está sendo enviado no formato JSON.",
            "schema": {
              "type": "string",
              "default": "application/json"
            }
          },
          {
            "name": "orderId",
            "in": "path",
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 1
            },
            "required": true
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "Token de autorização do seu aplicativo",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "RAW_BODY": {
                    "type": "string",
                    "default": "{   \"split\": [     {       \"amount\": 1000,       \"recipient_hash\": \"d9bd0dae-3274-5e5a-939f-f50d867eb652\"     },   ] }",
                    "format": "json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "201",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n\t\"message\": \"Split order created successfully\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": {
                      "type": "string",
                      "example": "Split order created successfully"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "422",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"split\": [\n        \"O campo split é obrigatório.\"\n    ],\n    \"split.0.amount\": [\n        \"O campo split.0.amount é obrigatório.\"\n    ],\n    \"split.0.recipient_id\": [\n        \"O campo split.0.recipient_hash é obrigatório.\"\n    ]\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "split": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "example": "O campo split é obrigatório."
                      }
                    },
                    "split.0.amount": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "example": "O campo split.0.amount é obrigatório."
                      }
                    },
                    "split.0.recipient_id": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "example": "O campo split.0.recipient_hash é obrigatório."
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "500",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"error\": \"Internal Server Error\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "example": "Internal Server Error"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

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

### POST /websites/appmax_readme_io_reference/simulate_withdrawal_anticipation

Source: https://appmax.readme.io/reference/simular-antecipacao-de-saque-do-recebedor-recipient

Simula a antecipação de um saque para um recebedor, retornando os valores estimados.

```APIDOC
## POST /websites/appmax_readme_io_reference/simulate_withdrawal_anticipation

### Description
Este endpoint permite simular uma solicitação de antecipação de saque para um recipient específico e retorna os valores estimados. Nenhuma solicitação de saque é criada; o endpoint é exclusivamente informativo.

### Method
POST

### Endpoint
/websites/appmax_readme_io_reference/simulate_withdrawal_anticipation

### Parameters
#### Request Body
- **value** (decimal) - Required - Valor bruto considerado na simulação

### Request Example
```json
{
  "value": 1000.50
}
```

### Response
#### Success Response (200)
- **value** (decimal) - Valor bruto considerado na simulação
- **net_value** (decimal) - Valor líquido que seria recebido
- **withdraw_tax** (decimal) - Valor da taxa de antecipação aplicada
- **tax_percentage** (decimal) - Percentual da taxa de antecipação

#### Response Example
```json
{
  "value": 1000.50,
  "net_value": 950.25,
  "withdraw_tax": 50.25,
  "tax_percentage": 5.02
}
```
```

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

### Generate App Token

Source: https://appmax.readme.io/reference/fluxo-de-autentica%C3%A7%C3%A3o-e-autoriza%C3%A7%C3%A3o-na-api-da-appmax

Example JSON response containing the token (hash) required for user redirection to Appmax for installation authorization. This token is a unique identifier for the authorization process.

```json
{
    "data": {
        "token": "12083w36219d223f33ecf48f2a7f5ccf143b0bc554"
    }
}
```

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

### Troubleshooting 401 Error for Customer Creation

Source: https://appmax.readme.io/reference/faq

Guidance on resolving 401 Unauthorized errors when attempting to create a customer.

```APIDOC
## Troubleshooting 401 Error for Customer Creation

### Description
This guide helps resolve "401 Unauthorized" errors encountered when creating a customer via the API.

### Potential Causes and Solutions

1.  **Token Validity:**
    *   **Check:** Ensure the access token used in the request is still valid and has not expired.
    *   **Action:** If expired, obtain a new token following the authentication flow.

2.  **Token Generation Source:**
    *   **Check:** Verify that the token used for the request was generated using the merchant's credentials *after* the app installation and authorization process was successfully completed.
    *   **Action:** Ensure you are using `client_id` and `client_secret` obtained from the `/app/client/generate` endpoint for the specific merchant.
```

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

### Production Environment Details

Source: https://appmax.readme.io/reference/differences-between-appmax-environments-sandbox-and-production

Details for accessing the Production environment for transacting with real customers, including authentication and API endpoints.

```APIDOC
## Production Environment

### Description
Used to transact with real customers. Standard authentication and API URLs are used.

### Authentication Endpoint
`https://auth.appmax.com.br`

### API Endpoint
`https://api.appmax.com.br`

### Authorization Redirect
`https://admin.appmax.com.br/appstore/integration/HASH`
```

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

### Calculate Installment Values using cURL

Source: https://appmax.readme.io/reference/421c%C3%A1lculo-de-parcelas

This cURL command demonstrates how to call the Appmax API to calculate installment values. It sends a POST request to the /v1/payments/installments endpoint with the desired number of installments, total value, and settings flag. The API returns the total value with applied interest for different installment types.

```curl
curl --request POST \
     --url https://api.appmax.com.br/v1/payments/installments \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data \
'{
  "installments": 10,
  "total_value": 10000,
  "settings": true
}'
```

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

### Sandbox Environment Details

Source: https://appmax.readme.io/reference/differences-between-appmax-environments-sandbox-and-production

Details for accessing the Sandbox environment for testing integrations, including authentication and API endpoints.

```APIDOC
## Sandbox Environment

### Description
Used to test integrations before going live and before being approved in homologation. Authentication and API use different subdomains.

### Authentication Endpoint
`https://auth.sandboxappmax.com.br`

### API Endpoint
`https://api.sandboxappmax.com.br`

### Authorization Redirect
`https://breakingcode.sandboxappmax.com.br/appstore/integration/HASH`
```

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

### POST /v1/payments/installments

Source: https://appmax.readme.io/reference/421c%C3%A1lculo-de-parcelas

This endpoint calculates installment values with interest rates applied according to the payment configuration set in Appmax. It returns the total value with interest for each installment modality (PP and AM).

```APIDOC
## POST /v1/payments/installments

### Description
Calculates installment values with applied interest rates based on Appmax payment configurations. Returns the total value with interest for each installment modality (PP - 'Simples por Parcela' and AM - 'Financiamento'). The integration should then divide this total value to determine the exact amount per installment.

### Method
POST

### Endpoint
/v1/payments/installments

### Parameters
#### Query Parameters
None

#### Request Body
- **installments** (integer) - Required - The number of installments (1 to 12).
- **total_value** (integer) - Required - The total base value for the calculation.
- **settings** (boolean) - Required - If true, uses the payment settings configured in Appmax.

### Request Example
```json
{
  "installments": 10,
  "total_value": 10000,
  "settings": true
}
```

### Response
#### Success Response (200)
- **amount** (integer) - The total value with interest applied.
- **installments** (array) - An array of installment objects, each containing:
  - **number** (integer) - The installment number.
  - **amount** (integer) - The amount for that specific installment.
  - **interest_amount** (integer) - The interest amount for that installment.
  - **type** (string) - The installment modality ('PP' or 'AM').

#### Response Example
```json
{
  "amount": 11500,
  "installments": [
    {
      "number": 1,
      "amount": 1150,
      "interest_amount": 150,
      "type": "PP"
    },
    {
      "number": 2,
      "amount": 1150,
      "interest_amount": 150,
      "type": "PP"
    }
    // ... more installments
  ]
}
```
```

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

### Appmax Authentication and Authorization Flow

Source: https://appmax.readme.io/reference/faq

This section outlines the correct sequence of steps for authenticating and authorizing an app with Appmax. It details obtaining an app token, generating an authorization hash, redirecting the user for installation approval, and finally generating merchant API credentials. Missing the user redirection step is identified as a common cause for '500 Internal Server Error'.

```text
1. Obtain App Token:
   POST to https://auth.sandboxappmax.com.br/oauth2/token
   Use app credentials.

2. Generate Authorization Hash:
   POST to https://api.sandboxappmax.com.br/app/authorize
   Parameters: app_id, client_key, url_callback

3. Redirect User for Installation Authorization:
   Redirect to https://breakingcode.sandboxappmax.com.br/appstore/integration/HASH
   Essential for merchant to authorize installation.

4. Generate Merchant API Credentials:
   POST to https://api.sandboxappmax.com.br/app/client/generate
   Uses the same HASH from step 3.
   Returns client_id and client_secret.
```

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

### Installation Health Check

Source: https://appmax.readme.io/reference/criar-credenciais-do-merchant

This section details the health check process that occurs when a merchant installs your application. Appmax sends a POST request to your specified validation URL with essential credentials.

```APIDOC
## POST /validation/url (Your Validation URL)

### Description
Receives installation details from Appmax for health check verification. Your endpoint should respond with an HTTP 200 and an `external_id`.

### Method
POST

### Endpoint
[Your specified Validation URL]

### Parameters
#### Request Body
- **app_id** (string) - Required - The ID of your application.
- **client_id** (string) - Required - The merchant's client ID.
- **client_secret** (string) - Required - The merchant's client secret.
- **external_key** (string) - Optional - A key provided by the user for precise identification.

### Request Example
```json
{
  "app_id": "APP_ID",
  "client_id": "MERCHANT_CLIENT_ID",
  "client_secret": "MERCHANT_CLIENT_SECRET",
  "external_key": "EXTERNAL_KEY"
}
```

### Response
#### Success Response (200)
- **external_id** (string) - A unique ID for the installation, to be stored in your database.

#### Response Example
```json
{
  "external_id": "37bb0791-ee0b-457d-860c-186e32978bcd"
}
```
```

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

### POST /websites/appmax_readme_io_reference/solicitar-antecipacao-saque

Source: https://appmax.readme.io/reference/solicitar-antecipacao-de-saque-do-rebedor-recipient

Cria uma solicitação de antecipação de saque para um recebedor.

```APIDOC
## POST /websites/appmax_readme_io_reference/solicitar-antecipacao-saque

### Description
Este endpoint é responsável por criar uma solicitação de antecipação de saque para um recebedor, utilizando saldo do tipo “a liberar” (TO_RELEASE).

### Method
POST

### Endpoint
/websites/appmax_readme_io_reference/solicitar-antecipacao-saque

### Parameters
#### Request Body
- **recipient_id** (int) - Required - Identificador do recebedor.
- **value** (int) - Required - Valor bruto solicitado (em centavos).

### Request Example
```json
{
  "recipient_id": 12345,
  "value": 10000
}
```

### Response
#### Success Response (200)
- **withdraw_request_id** (int) - Identificador da solicitação de saque criada.
- **status** (int) - Status atual da solicitação.
- **value** (int) - Valor bruto solicitado (em centavos).
- **withdraw_tax** (int) - Taxa de antecipação aplicada (em centavos).
- **net_value** (int) - Valor líquido a receber após descontos.

#### Response Example
```json
{
  "withdraw_request_id": 98765,
  "status": 1,
  "value": 10000,
  "withdraw_tax": 500,
  "net_value": 9500
}
```
```

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

### Troubleshooting 403 Error on /oauth2/token

Source: https://appmax.readme.io/reference/faq

Guidance on resolving 403 Forbidden errors specifically when accessing the /oauth2/token endpoint.

```APIDOC
## Troubleshooting 403 Error on /oauth2/token

### Description
This guide addresses "403 Forbidden" errors occurring when attempting to access the `/oauth2/token` endpoint, often due to incorrect endpoint usage.

### Cause of Error

The 403 error on this endpoint typically indicates that the request is being made to the wrong base URL. Authentication-related calls, such as obtaining a token, should use the `auth.sandboxappmax.com.br` domain, while API calls using the generated token should use `api.sandboxappmax.com.br`.

### Correct Endpoint Usage

- **Authentication Endpoint (for token generation):**
  `https://auth.sandboxappmax.com.br/oauth2/token`

- **API Endpoint (for using the token):**
  `https://api.sandboxappmax.com.br/...`

### Example CURL Request for Token Generation

```curl
curl --location 'https://auth.sandboxappmax.com.br/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cookie: XSRF-TOKEN=26949a8d-9d53-44ff-845c-bd5a09cd1f34' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=CLIENT_ID' \
--data-urlencode 'client_secret=CLIENT_SECRET'
```
```

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

### Health Check Payload for App Installation

Source: https://appmax.readme.io/reference/criar-credenciais-do-merchant

This JSON payload is sent to the merchant's validation URL during the app installation process. It includes essential information like app_id, merchant credentials (client_id, client_secret), and an optional external_key for precise identification.

```json
{
  "app_id": "APP_ID",
  "client_id": "MERCHANT_CLIENT_ID",
  "client_secret": "MERCHANT_CLIENT_SECRET",
  "external_key": "EXTERNAL_KEY"
}
```

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

### Exemplo de Resposta de Sucesso (JSON)

Source: https://appmax.readme.io/reference/criar-um-upsell-na-appmax

Estrutura de resposta JSON esperada quando um upsell é criado com sucesso (código 201). Contém uma mensagem de sucesso e uma URL de redirecionamento.

```json
{
  "data": {
    "message": "Transação efetuada com sucesso",
    "redirect_url": "example.com/order/success-by-order?hash=40001142025031-1715608804-0190017001715608804"
  }
}

```