### Install InvoiceBox MCP server with npx

Source: https://docs.invoicebox.ru/mcp/demo

Run this command to install and start the InvoiceBox MCP server. It appears in Claude Desktop, Cursor, or any MCP-compatible client. The server starts in read-only mode; write tools are enabled separately.

```bash
npx -y @invoicebox/mcp-server
```

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

### Install SDK with Composer

Source: https://docs.invoicebox.ru/docs/merchant/sdk/php

Install the Invoicebox PHP SDK via Composer. Requires PHP 7.4 or later.

```bash
composer require invoicebox/sdk-php

```

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

### onPaymentResult usage example

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Example of registering a handler to navigate to a result screen based on the payment status returned.

```javascript
invoiceboxMinapp.onPaymentResult((status) => {
   navigateTo('PaymentResultScreen', { status });
});
```

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

### onLink Usage Example

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Demonstrates opening a URL in the parent window context.

```javascript
// На платёжной странице будет открыта новая вкладка с Google страницей
// это никак не повлияет на работу мини-приложения
invoiceboxMinapp.onLink("https://www.google.ru");
```

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

### Collection response example

Source: https://docs.invoicebox.ru/docs/api

Example of a successful JSON response for a collection of entities.

```json
{
  "data" : [
      {
        "id" : 1,
        "title": "Apple"
      },
      {
        "id" : 2,
        "title" : "Orange"
      },
      {
        "id" : 3,
        "title" : "Passion fruit"
      }
    ]
}
```

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

### getInitialData usage example

Source: https://docs.invoicebox.ru/llms-marketplace.txt

Example usage of getInitialData. The output shows a sample response object with the buyer's data.

```ts
invoiceboxMinapp.getInitialData().then(console.log);

/*
{
    minappType: 'suborder',
    orderContainerId: '3c15a3d1-3da8-4ba8-87e5-2dba828299fa',
    shopId: 123,
    userEmail: 'email@example.com',
    userName: 'Иван Иванов',
    userPhone: '+71231234567',
    fullHeight: false,
    locale: 'ru';
}
*/
```

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

### onCheckout Usage Example

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Demonstrates using onCheckout within a promise chain after receiving a payment URL.

```javascript
createOrderRequest(someData).then((response) => {
  invoiceboxMinapp.onCheckout(response.data.url);
});
```

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

### OrderResponse example

Source: https://docs.invoicebox.ru/docs/merchant/order/merchant-move

Example response body conforming to the OrderResponse schema, containing order details such as id, amount, status, and customer information.

```json
{
  "data": {
    "id": "01771534-1a57-f184-dee3-ebeb91dded75",
    "description": "string",
    "currencyId": "RUB",
    "amount": 100.5,
    "vatAmount": 100.5,
    "basketItems": [
      {
        "sku": "string",
        "name": "string",
        "groupName": "string",
        "measure": "string",
        "measureCode": "string",
        "originCountry": "string",
        "originCountryCode": "string",
        "grossWeight": 100.5,
        "netWeight": 100.5,
        "quantity": 100.5,
        "amount": 100.5,
        "amountWoVat": 100.5,
        "totalAmount": 100.5,
        "totalVatAmount": 100.5,
        "vatCode": "RUS_VAT22",
        "type": "string",
        "gtdNumber": "string",
        "paymentType": "string",
        "excise": 100.5,
        "metaData": {},
        "tnved": "string",
        "rnpt": "string",
        "gtin": "string",
        "category": "string",
        "categoryType": "string",
        "serviceDate": "2026-08-03T12:00:00+03:00"
      }
    ],
    "merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "status": "string",
    "shipmentStatus": "string",
    "subtype": "string",
    "processingStatus": "string",
    "createdAt": "2026-08-03T12:00:00+03:00",
    "merchantOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "merchantOrderIdVisible": "string",
    "expirationDate": "2026-08-03T12:00:00+03:00",
    "metaData": {},
    "customerData": {},
    "notificationUrl": "string",
    "orderSetting": {
      "roundPolicy": "string",
      "disableValidate": false
    },
    "internalProperty": {
      "guarantee": false,
      "hold": false,
      "rtp": false,
      "agent": false,
      "rtpExternal": false
    },
    "tags": {},
    "shopId": 1,
    "sourceId": "l3",
    "paidAt": "2026-08-03T12:00:00+03:00",
    "parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "returnUrl": "string",
    "successUrl": "string",
    "failUrl": "string",
    "paymentUrl": "string",
    "paymentUrlType": "redirect",
    "paymentPageUrl": "string",
    "customer": {
      "type": "string",
      "name": "string",
      "phone": "string",
      "email": "string",
      "vatNumber": "string",
      "countryId": "01771534-1a57-f184-dee3-ebeb91dded75",
      "registrationAddress": "string",
      "taxRegistrationReasonCode": "string"
    },
    "languageId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "contactId": 1,
    "contactCounterpartyId": 1,
    "processable": false,
    "userAccountId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "invoiceSetting": {
      "customerLocked": false,
      "customerLockedFields": {},
      "customerHiddenFields": {},
      "paymentMethodIdLocked": false,
      "paymentMethodId": 1,
      "savePaymentData": false,
      "clientId": "01771534-1a57-f184-dee3-ebeb91dded75",
      "paymentToken": "string",
      "paymentMethodCode": "string",
      "paymentMethodAutosubmit": false,
      "bankDetailId": 1
    },
    "orderContainerId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "paymentInfo": {},
    "holdTill": "2026-08-03T12:00:00+03:00",
    "additionalOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "shipmentTotalAmount": "string",
    "shipmentTotalVatAmount": "string"
  },
  "metaData": {
    "totalCount": 1,
    "pageSize": 1,
    "page": 1
  },
  "extendedData": [
    {
      "type": "string",
      "data": {}
    }
  ]
}
```

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

### onUnavailable Usage Example

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Demonstrates calling onUnavailable to close the mini-app.

```javascript
invoiceboxMinapp.onUnavailable();
```

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

### Single entity response example

Source: https://docs.invoicebox.ru/docs/api

Example of a successful JSON response for a single entity request.

```json
{
  "data" : {
    "id" : 1,
    "title" : "New title"
  }
}
```

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

### Error response example

Source: https://docs.invoicebox.ru/docs/api

Example of an error response returned when an HTTP status code >= 400 occurs.

```json
{
  "error":{
    "message" : "Error",
    "code" : "unauthorized"
  }
}
```

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

### onDone usage example

Source: https://docs.invoicebox.ru/llms-marketplace.txt

Example usage of onDone. The method is called with the payment URL from the response after creating an order.

```ts
createOrderRequest(someData).then((response) => {
  invoiceboxMinapp.onDone(response.data.url);
});
```

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

### getMetaDataValues usage example

Source: https://docs.invoicebox.ru/llms-marketplace.txt

Example usage of getMetaDataValues. The output shows the retrieved values for the keys flightNumber and departureTime.

```ts
invoiceboxMinapp
  .getMetaDataValues(["flightNumber", "departureTime"])
  .then(console.log);

/*
  ['NDJ37S', '2022-03-04T20:15:00+03:00']
*/
```

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

### Response JSON schema for merchant order creation

Source: https://docs.invoicebox.ru/docs/merchant/order/create

Shows the expected response body when creating a merchant order. Uses placeholder values like 'string' and example UUIDs, with a note that return addresses in the example are replaced with 'shop.example.com' for demonstration.

```json
{
  "data": {
    "id": "01771534-1a57-f184-dee3-ebeb91dded75",
    "description": "string",
    "currencyId": "RUB",
    "amount": 100.5,
    "vatAmount": 100.5,
    "basketItems": [
      {
        "sku": "string",
        "name": "string",
        "groupName": "string",
        "measure": "string",
        "measureCode": "string",
        "originCountry": "string",
        "originCountryCode": "string",
        "grossWeight": 100.5,
        "netWeight": 100.5,
        "quantity": 100.5,
        "amount": 100.5,
        "amountWoVat": 100.5,
        "totalAmount": 100.5,
        "totalVatAmount": 100.5,
        "vatCode": "RUS_VAT22",
        "type": "string",
        "gtdNumber": "string",
        "paymentType": "string",
        "excise": 100.5,
        "metaData": {},
        "tnved": "string",
        "rnpt": "string",
        "gtin": "string",
        "category": "string",
        "categoryType": "string",
        "serviceDate": "2026-08-03T12:00:00+03:00"
      }
    ],
    "merchantId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "status": "string",
    "shipmentStatus": "string",
    "subtype": "string",
    "processingStatus": "string",
    "createdAt": "2026-08-03T12:00:00+03:00",
    "merchantOrderId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "merchantOrderIdVisible": "string",
    "expirationDate": "2026-08-03T12:00:00+03:00",
    "metaData": {},
    "customerData": {},
    "notificationUrl": "string",
    "orderSetting": {
      "roundPolicy": "string",
      "disableValidate": false
    },
    "internalProperty": {
      "guarantee": false,
      "hold": false,
      "rtp": false,
      "agent": false,
      "rtpExternal": false
    },
    "tags": {},
    "shopId": 1,
    "sourceId": "l3",
    "paidAt": "2026-08-03T12:00:00+03:00",
    "parentId": "01771534-1a57-f184-dee3-ebeb91dded75",
    "returnUrl": "string",
    "successUrl": "string",
    "failUrl": "string",
    "paymentUrl": "string",
    "paymentUrlType": "redirect",
    "paymentPageUrl": "string",
    "customer": {
      "type": "string",
      "name": "string",
      "phone": "string",
      "email": "string",
      "vatNumber": "string",
      "countryId": "01771534-1a57-f184-fee3-ebeb91dded75",
      "registrationAddress": "string",
      "taxRegistrationReasonCode": "string"
    },
    "languageId": "01771534-1a57-f184-fee3-deeb91dded75",
    "contactId": 1,
    "contactCounterpartyId": 1,
    "processable": false,
    "userAccountId": "01771534-1a57-f184-fee3-deeb91dded75",
    "invoiceSetting": {
      "customerLocked": false,
      "customerLockedFields": {},
      "customerHiddenFields": {},
      "paymentMethodIdLocked": false,
      "paymentMethodId": 1,
      "savePaymentData": false,
      "clientId": "01771534-1a57-f184-fee3-deeb91dded75",
      "paymentToken": "string",
      "paymentMethodCode": "string",
      "paymentMethodAutosubmit": false,
      "bankDetailId": 1
    },
    "orderContainerId": "01771534-1a57-f184-fee3-deeb91dded75",
    "paymentInfo": {},
    "holdTill": "2026-08-03T12:00:00+03:00",
    "additionalOrderId": "01771534-1a57-f184-fee3-ebeb91dded75",
    "shipmentTotalAmount": "string",
    "shipmentTotalVatAmount": "string"
  },
  "metaData": {
    "totalCount": 1,
    "pageSize": 1,
    "page": 1
  },
  "extendedData": [
    {
      "type": "string",
      "data": {}
    }
  ]
}
```

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

### Get Order Information via GET

Source: https://docs.invoicebox.ru/docs/merchant/order/update

Retrieves information about a specific order using its unique identifier.

```curl
curl -X GET 'https://api.invoicebox.ru/v3/billing/api/order/order/<id>' \
  -H 'Authorization: Bearer <ВАШ_ТОКЕН>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp 1.0'
```

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

### onError Usage Examples

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Demonstrates calling onError with a custom message or the default error message.

```javascript
// Пользователь увидит "Ошибка создания заказа"
invoiceboxMinapp.onError("Ошибка создания заказа");

// Пользователь увидит "Что-то пошло не так"
invoiceboxMinapp.onError();
```

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

### Получение списка заказов (GET /v3/billing/api/order/order)

Source: https://docs.invoicebox.ru/docs/merchant/order/create

Получение списка заказов магазина через GET /v3/billing/api/order/order. Требуется авторизация Bearer-токеном и заголовки Content-Type и User-Agent.

```curl
curl -X GET 'https://api.invoicebox.ru/v3/billing/api/order/order' \
  -H 'Authorization: Bearer <ВАШ_ТОКЕН>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp 1.0'

```

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

### Проверка доступа: GET /security/api/auth/auth

Source: https://docs.invoicebox.ru/quickstart

Проверяет доступ с демо-токеном, возвращает идентификатор пользователя. Используйте перед созданием заказа.

```bash
curl -X GET 'https://api.invoicebox.ru/v3/security/api/auth/auth' \
  -H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e' \
  -H 'User-Agent: MyApp 1.0'
```

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

### Create order with InvoiceboxClient

Source: https://docs.invoicebox.ru/docs/merchant/sdk/php

Create an order with the Invoicebox SDK. The example initializes the client, optionally checks authentication, creates a customer (private or legal), builds a basket item, sends a createOrder request, and prints the payment URL if successful. Replace the placeholder auth token and shop ID with real values.

```php
$client = new InvoiceboxClient(
    '*auth токен*',
    'v3',
    null,
    HttpClient::create(),
);

/**
 * Проверка авторизации (необязательный шаг, для тестирования наличия доступа)
 */
$result = $client->checkAuth();

if ($result->getUserId()) {
    echo "Успешная авторизация \n";
}


// Покупатель юр.лицо
//$customer = new LegalCustomer(
//    'OOO TEST',
//    '78121111111',
//    'test@test.test',
//    '7804445210',
//    '123321, Улица, 1, 1'
//);

// Покупатель физ.лицо
$customer = new PrivateCustomer(
    'name',
    '78121111111',
    'test@test.test',
);


$basketItems[] = new BasketItem(
    "12312", /* Идентификатор заказа (необходим для создания возврата) */
    'Тест',
    'шт.',
    '796',
    1.0,
    1000.00,
    1000,
    1000.00,
    0,
    VatCode::VATNONE,
    BasketItemType::COMMODITY,
    PaymentType::FULL_PREPAYMENT
);

$request = new CreateOrderRequest(
    'Описание заказа',
    'ffffffff-ffff-ffff-ffff-ffffffffffff', // id магазина
    strval(random_int(1,2000)),
    1000.00,
    0,
    'RUB',
    new \DateTime('tomorrow'),
    $basketItems,

);

$result = $client->createOrder($request);

if ($result->getPaymentUrl()) {
    echo sprintf('Заказ успешно создан - ссылка на оплату - %s', $result->getPaymentUrl());
}

/* Redirect to: $result->getPaymentUrl() */

```

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

### Update Order Request Example

Source: https://docs.invoicebox.ru/docs/merchant/order/update

Example of a PUT request to update an order with a specific UUID. The request body includes the updated amount and basket items.

```http
PUT /v3/billing/api/order/order/019fc671-6d37-77e0-6080-fec092bf521f
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
Content-Type: application/json
User-Agent: MyApp 1.0
Accept: application/json

{
  "amount": 15000,
  "vatAmount": 0,
  "basketItems": [
    {
      "sku": "5fe0adcfa7fb4",
      "name": "Бронирование номера, продление на сутки",
      "measure": "шт.",
      "measureCode": "796",
      "quantity": 1,
      "amount": 15000,
      "amountWoVat": 15000,
      "totalAmount": 15000,
      "totalVatAmount": 0,
      "vatCode": "RUS_VAT0",
      "type": "service",
      "paymentType": "full_prepayment"
    }
  ]
}
```

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

### onHeightChange usage example

Source: https://docs.invoicebox.ru/llms-marketplace.txt

Example usage of onHeightChange. The component observes its own height and calls onHeightChange whenever it changes.

```ts
const Conatiner = ({ children }: { children: ReactNode }) => {
  const [elRef, setElRef] = useState<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!elRef) return;
    const observer = new ResizeObserver(() => {
      invoiceboxMinapp.onHeightChange(elRef.offsetHeight);
    });
    observer.observe(elRef);
    return () => observer.disconnect();
  }, [elRef, child]);

  return <div ref={elRef}>{children}</div>;
};
```

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

### CURL-запрос для проверки токена (GET /v3/security/api/auth/auth)

Source: https://docs.invoicebox.ru/docs/api/auth

Аналог HTTP-запроса в виде CURL-команды. Использует {baseUrl} как базовый URL. Возвращает 200 OK и userId при корректном токене.

```bash
curl -L -X GET '{baseUrl}/v3/security/api/auth/auth' \
  -H 'Accept: application/json' \
  -H 'User-Agent: MyApp 1.0' \
  -H 'Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e'

```

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

### create_order function schema

Source: https://docs.invoicebox.ru/mcp/functions

Example of a function definition for creating an order, featuring a two-step confirmation process and specific parameter constraints.

```json
{
  "name": "create_order",
  "description": "Выставляет счёт покупателю и возвращает ссылку на оплату. Покупателем может быть организация, ИП или физлицо. Подтверждение в два шага: первый вызов возвращает сводку и confirmation_token, второй исполняет.",
  "parameters": {
    "type": "object",
    "additionalProperties": false,
    "required": ["description", "customer", "basket_items", "amount", "vat_amount", "currency_id", "expiration_date"],
    "properties": {
      "description": { "type": "string" },
      "amount": { "type": "string", "description": "сумма в копейках строкой: 12200 = 122,00 ₽" },
      "vat_amount": { "type": "string" },
      "currency_id": { "type": "string", "enum": ["RUB", "USD", "EUR", "GBP", "CNY"] },
      "customer": {
        "type": "object",
        "properties": {
          "type": { "type": "string", "enum": ["legal", "private"] },
          "name": { "type": "string" },
          "vat_number": { "type": "string" }
        }
      },
      "confirmation_token": { "type": "string" }
    }
  }
}
```

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

### GET /v3/marketplace/api/shop — список точек продаж (curl)

Source: https://docs.invoicebox.ru/docs/marketplace/create

Получает список точек продаж через GET-запрос к API. Требуется авторизационный токен и заголовок Content-Type. Ответ содержит массив объектов ShopResponse.

```bash
curl -X GET 'https://api.invoicebox.ru/v3/marketplace/api/shop' \
  -H 'Authorization: Bearer <ВАШ_ТОКЕН>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp 1.0'
```

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

### Get initial order data

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Retrieves customer and order information. The returned promise resolves to an object containing user details and the mini-app type.

```typescript
getInitialData(): Promise<{
    shopId?: number;
    userEmail: string;
    userName: string;
    userPhone: string;
    fullHeight: boolean;
    locale: string;
} & (
    | {
          orderContainerId?: never;
          minappType: 'order';
      }
    | {
          orderContainerId: string;
          minappType: 'suborder';
      }
)>
```

```javascript
invoiceboxMinapp.getInitialData().then(console.log);

/*
{
    minappType: 'suborder',
    orderContainerId: '3c15a3d1-3da8-4ba8-87e5-2dba828299fa',
    shopId: 123,
    userEmail: 'email@example.com',
    userName: 'Иван Иванов',
    userPhone: '+71231234567',
    fullHeight: false,
    locale: 'ru';
}
*/
```

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

### GET /v3/marketplace/api/shop

Source: https://docs.invoicebox.ru/docs/marketplace/create

Возвращает список точек продаж в маркетплейсе. Требуется авторизация.

```APIDOC
## GET /v3/marketplace/api/shop

### Description
Возвращает список точек продаж в маркетплейсе. Требуется авторизация.

### Method
GET

### Endpoint
https://api.invoicebox.ru/v3/marketplace/api/shop

### Parameters
Нет параметров.

### Request Example
```
curl -X GET 'https://api.invoicebox.ru/v3/marketplace/api/shop' \
  -H 'Authorization: Bearer <ВАШ_ТОКЕН>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp 1.0'
```

### Response
#### Success Response (200)
Список объектов ShopResponse (см. POST /v3/marketplace/api/shop).

#### Response Example
```json
[
  {
    "id": 12,
    "token": "95e5396611d261986cec0915a9f85799",
    "type": "shop",
    "alias": "1694158899",
    "shopUrl": "https://1694158899.expressclient.ru",
    "accountProgramIds": ["01771534-1a57-f184-dee3-ebeb91dded71", "01771534-1a57-f184-dee3-ebeb91dded72"]
  }
]
```
```

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

### HTTP-запрос для проверки токена (GET /v3/security/api/auth/auth)

Source: https://docs.invoicebox.ru/docs/api/auth

Проверяет валидность токена. Требует заголовки Accept, User-Agent и Authorization с Bearer-токеном. При корректном токене возвращает 200 OK и userId.

```http
GET /v3/security/api/auth/auth
Accept: application/json
User-Agent: MyApp 1.0
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e

```

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

### GET /v3/billing/api/order/order

Source: https://docs.invoicebox.ru/schemas/openapi/invoicebox.yaml

Получение списка заказов магазина.

```APIDOC
## GET /v3/billing/api/order/order

### Description
Получение списка заказов магазина.

### Method
GET

### Endpoint
/v3/billing/api/order/order

### Response
#### Success Response (200)
- **BillingProviderDomainOrderEntityOrderApiReadMetadataResponse** (object) - Успешный ответ
- **X-Request-Id** (string) - Идентификатор запроса: приложите его к обращению в поддержку

#### Response Example
{
  "metadata": {}
}

#### Error Responses
- **400** (ErrorResponse) - Ошибка
- **401** (ErrorResponse) - Ошибка
- **403** (ErrorResponse) - Ошибка
- **404** (ErrorResponse) - Ошибка
- **405** (ErrorResponse) - Ошибка
- **422** (ErrorResponse) - Ошибка
- **429** - Превышен лимит: 100 запросов за 30 секунд на учётную запись, 500 на IP. Заголовка Retry-After в ответе нет: повторяйте с растущей задержкой и случайным разбросом
- **500** (ErrorResponse) - Ошибка
```

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

### Create Order via API

Source: https://docs.invoicebox.ru/

Example of a POST request to create an order in the Invoicebox billing system using cURL.

```curl
curl -X POST 'https://api.invoicebox.ru/v3/billing/api/order/order' \
  -H 'Authorization: Bearer <ВАШ_ТОКЕН>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp 1.0' \
  -d '{
  "merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "merchantOrderId": "demo-order-1788874032204",
  "amount": 12000,
  "vatAmount": 0,
  "currencyId": "RUB",
  "languageId": "ru",
  "description": "Оплата бронирования № 4412",
  "expirationDate": "2026-09-09T13:27:12+00:00",
  "successUrl": "https://shop.example.com/order/4412?result=success",
  "failUrl": "https://shop.example.com/order/4412?result=fail",
  "returnUrl": "https://shop.example.com/order/4412?result=return",
  "basketItems": [
    {
      "sku": "room-deluxe",
      "name": "Проживание в номере «Делюкс», 2 ночи",
      "measure": "шт",
      "measureCode": "796",
      "quantity": 1,
      "amount": 12000,
      "amountWoVat": 12000,
      "totalAmount": 12000,
      "totalVatAmount": 0,
      "vatCode": "RUS_VAT0",
      "type": "service",
      "paymentType": "full_prepayment"
    }
  ],
  "customer": {
    "type": "legal",
    "name": "ООО «Ромашка»",
    "vatNumber": "7701234560",
    "taxRegistrationReasonCode": "770101001",
    "phone": "79001112233",
    "email": "buh@example.invbox.ru"
  }
}'
```

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

### GET /v3/filter/api/counterparty-detail

Source: https://docs.invoicebox.ru/docs/dictionary/counterparty-detail

Поиск и получение данных об организации по ИНН. Метод возвращает реквизиты организации (наименование, КПП, адреса) для подстановки в заказ.

```APIDOC
## GET /v3/filter/api/counterparty-detail

### Description
Поиск и получение данных об организации по ИНН. Метод возвращает реквизиты организации (наименование, КПП, адреса) для подстановки в заказ.

### Method
GET

### Endpoint
/v3/filter/api/counterparty-detail

### Parameters
#### Query Parameters
- **vatNumber** (string) - Required - ИНН организации.

### Request Example
```
GET /v3/filter/api/counterparty-detail?vatNumber=2323232323
Accept: application/json
User-Agent: MyApp 1.0
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
```

### Response
#### Success Response (200)
- **data** (array) - Коллекция объектов Counterparty.
- **metaData** (object) - Метаданные ответа.

#### Response Example
```
{
  "data": [
    {
      "id": "01771534-196a-1105-839a-82422289d6d9",
      "vatNumber": "7736207543",
      "taxRegistrationReasonCode": "773601001",
      "name": "ООО «Ромашка»",
      "nameFull": "Общество с ограниченной ответственностью «Ромашка»",
      "registrationNumber": "1027700123456",
      "registrationDate": "2026-09-07T00:00:00+03:00",
      "registrationAddress": "119021, г. Москва, ул. Тимура Фрунзе, д. 11",
      "postAddress": "119021, г. Москва, ул. Тимура Фрунзе, д. 11",
      "postAddressZip": "119021"
    }
  ],
  "metaData": {
    "totalCount": 1,
    "pageSize": 20,
    "page": 1
  }
}
```

### Error Handling
Если организация не найдена или справочный сервис недоступен, метод отвечает `200` с пустым `data`. Обрабатывайте такой ответ как «данных нет»: пустой `data` не означает, что запрос не удался.
```

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

### Update Order Response Example

Source: https://docs.invoicebox.ru/docs/merchant/order/update

The JSON response body returned after a successful order update, containing the full order details.

```json
{
  "id": "019fc671-6d37-77e0-6080-fec092bf521f",
  "description": "Оплата бронирования № 4412",
  "currencyId": "RUB",
  "amount": 12000,
  "vatAmount": 0,
  "basketItems": [
    {
      "sku": "room-deluxe",
      "name": "Проживание в номере «Делюкс», 2 ночи",
      "measure": "шт",
      "measureCode": "796",
      "quantity": 1,
      "amount": 12000,
      "amountWoVat": 12000,
      "totalAmount": 12000,
      "totalVatAmount": 0,
      "vatCode": "RUS_VAT0",
      "type": "service",
      "paymentType": "full_prepayment"
    }
  ],
  "merchantId": "ffffffff-ffff-ffff-ffff-ffffffffffff",
  "status": "created",
  "shipmentStatus": "unshipped",
  "subtype": "order",
  "createdAt": "2026-08-03T07:05:50+00:00",
  "merchantOrderId": "portal-6c2fcf273e55-docs-example-1785740749696",
  "merchantOrderIdVisible": "portal-6c2fcf273e55-docs-example-1785740749696",
  "expirationDate": "2026-08-04T07:05:49+00:00",
  "internalProperty": {},
  "tags": [
    "agent"
  ],
  "sourceId": "v3",
  "returnUrl": "https://shop.example.com/order/4412?result=return",
  "successUrl": "https://shop.example.com/order/4412?result=success",
  "failUrl": "https://shop.example.com/order/4412?result=fail",
  "paymentUrl": "https://pay.invoicebox.ru/order/019fc671-6c80-eed3-ce48-9bb53f679353",
  "paymentPageUrl": "https://pay.invoicebox.ru/order/019fc671-6c80-eed3-ce48-9bb53f679353",
  "customer": {
    "type": "legal",
    "name": "ООО «Ромашка»",
    "phone": "79001112233",
    "email": "buh@example.invbox.ru",
    "countryId": "RUS"
  },
  "languageId": "ru",
  "processable": true,
  "orderContainerId": "019fc671-6c80-eed3-ce48-9bb53f679353"
}
```

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

### GET /v3/security/api/auth/auth

Source: https://docs.invoicebox.ru/llms-api.txt

Метод проверки авторизационного токена. Позволяет убедиться, что токен корректен и авторизация работает. Возвращает идентификатор пользователя при успехе, ошибку при неверном токене, или данные анонимного пользователя при отсутствии токена.

```APIDOC
## GET /v3/security/api/auth/auth

### Description
Проверка авторизационного токена и работоспособности авторизации. Возвращает идентификатор пользователя при корректном токене, ошибку при некорректном токене, или данные анонимного пользователя при отсутствии токена.

### Method
GET

### Endpoint
/v3/security/api/auth/auth

### Parameters
#### Headers
- **Accept** (string) - Required - Должен быть `application/json`.
- **User-Agent** (string) - Required - Идентификатор приложения, например `MyApp 1.0`.
- **Authorization** (string) - Required - Bearer-токен, например `Bearer b37c4c689295904ed21eee5d9a48d42e`.

### Request Example
```http
GET /v3/security/api/auth/auth
Accept: application/json
User-Agent: MyApp 1.0
Authorization: Bearer b37c4c689295904ed21eee5d9a48d42e
```

### Response
#### Success Response (200)
- **data.userId** (string) - Идентификатор пользователя (непустой при корректном токене).
- **data.profile** (null) - Профиль пользователя (всегда null в примере).
- **data.accessToken** (null) - Токен доступа (всегда null в примере).
- **extendedData** (array) - Дополнительные данные (пустой массив).

#### Response Example
```json
{
  "data": {
    "userId": "01771533-8e75-3234-8e3d-9213ae2d7c52",
    "profile": null,
    "accessToken": null
  },
  "extendedData": []
}
```

#### Error Response (401)
- **error.message** (string) - Сообщение об ошибке, например `Unauthorized`.
- **error.code** (string) - Код ошибки, например `unauthorized`.

#### Error Response Example
```json
{
  "error": {
    "message": "Unauthorized",
    "code": "unauthorized"
  }
}
```

#### Anonymous Response (200)
- **data.userId** (null) - null при отсутствии токена.
- **data.profile** (null) - null.
- **data.accessToken** (null) - null.
- **extendedData** (array) - Пустой массив.

#### Anonymous Response Example
```json
{
  "data": {
    "userId": null,
    "profile": null,
    "accessToken": null
  },
  "extendedData": []
}
```
```

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

### GET /v3/billing/api/order/order

Source: https://docs.invoicebox.ru/schemas/invoicebox.postman_collection.json

Получение списка заказов магазина. Поддерживает query-параметр _extend[] со значением merchant. Документация: https://docs.invoicebox.ru/docs/merchant/order/create/

```APIDOC
## GET /v3/billing/api/order/order

### Description
Получение списка заказов магазина.

### Method
GET

### Endpoint
/v3/billing/api/order/order

### Parameters
#### Query Parameters
- **_extend[]** (string) - Optional - Допустимое значение: `merchant`

### Response
#### Success Response (200)
- **orders** (array) - Список заказов

#### Response Example
{
  "orders": []
}
```

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

### Update mini-app height

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Notifies the parent window of the required height for the mini-app. This example uses a ResizeObserver to track element size changes.

```typescript
onHeightChange(height: number): void;
```

```typescript
const Conatiner = ({ children }: { children: ReactNode }) => {
  const [elRef, setElRef] = useState<HTMLDivElement | null>(null);

  useEffect(() => {
    if (!elRef) return;
    const observer = new ResizeObserver(() => {
      invoiceboxMinapp.onHeightChange(elRef.offsetHeight);
    });
    observer.observe(elRef);
    return () => observer.disconnect();
  }, [elRef, child]);

  return <div ref={elRef}>{children}</div>;
};
```

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

### Установка и инициализация MiniApp SDK через npm/yarn

Source: https://docs.invoicebox.ru/llms-marketplace.txt

Установка и инициализация MiniApp SDK через пакетный менеджер. Сначала перейдите в каталог проекта, затем установите библиотеку с помощью npm или yarn, и наконец импортируйте и вызовите connect() в index.js.

```bash
cd <ПУТЬ_К_МИНИ_ПРИЛОЖЕНИЮ>
```

```bash
npm install @invoicebox/minapp-sdk || yarn add @invoicebox/minapp-sdk
```

```javascript
import { invoiceboxMinapp } from '@invoicebox/minapp-sdk';

invoiceboxMinapp.connect();
```

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

### Require Composer autoload

Source: https://docs.invoicebox.ru/docs/merchant/sdk/php

Enable autoloading for the SDK. This line is required in your project code after installing the SDK via Composer or manually.

```php
require __DIR__ . '/vendor/autoload.php';

```

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

### CURL-запрос GET для проверки токена (демо)

Source: https://docs.invoicebox.ru/docs/api/auth

Демонстрационный GET-запрос к API. Использует реальный URL api.invoicebox.ru и плейсхолдер <ВАШ_ТОКЕН>.

```bash
curl -X GET 'https://api.invoicebox.ru/v3/security/api/auth/auth' \
  -H 'Authorization: Bearer <ВАШ_ТОКЕН>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp 1.0'

```

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

### Get list of merchant shipments

Source: https://docs.invoicebox.ru/docs/merchant/order/shipment_create

Retrieves the list of shipments for the merchant using a GET request.

```curl
curl -X GET 'https://api.invoicebox.ru/v3/billing/api/order/shipment' \
  -H 'Authorization: Bearer <ВАШ_ТОКЕН>' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: MyApp 1.0'
```

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

### connect()

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Establishes a connection with the parent window. This method is called by the mini-app to initialize communication.

```APIDOC
## connect()

### Description
Establishes a connection with the parent window. This method is called by the mini-app to initialize communication.

### Method
connect

### Signature
connect(): void;

### Parameters
None

### Return Value
void

```

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

### Инициализация MiniApp SDK в HTML

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Вызов метода connect для инициализации SDK внутри тега script.

```html
<script>
  invoiceboxMinapp.connect();
</script>
```

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

### GET /v3/marketplace/api/shop

Source: https://docs.invoicebox.ru/schemas/coverage-manifest.json

Retrieves a list of marketplace shops. This endpoint is part of the marketplace API and is documented in the OpenAPI schema.

```APIDOC
## GET /v3/marketplace/api/shop

### Description
Retrieves a list of marketplace shops.

### Method
GET

### Endpoint
/v3/marketplace/api/shop

### Parameters
No parameters are documented in the source.

### Response
No response schema is documented in the source.
```

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

### Инициализация MiniApp SDK в index.js

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Импорт и подключение SDK в основном файле приложения.

```javascript
import { invoiceboxMinapp } from '@invoicebox/minapp-sdk';

invoiceboxMinapp.connect();
```

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

### Create Special Offer POST Request

Source: https://docs.invoicebox.ru/schemas/invoicebox.postman_collection.json

Creates a special offer for a merchant. The offer is active between startAt and finishAt, where the end date must be after the start date.

```json
{
  "merchantId": "{{merchantId}}",
  "active": true,
  "startAt": "{{expirationDate}}",
  "finishAt": "{{expirationDate}}",
  "name": "string"
}
```

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

### Пример ответа профиля пользователя

Source: https://docs.invoicebox.ru/llms-id.txt

Пример JSON-ответа при успешном запросе профиля пользователя через GET /v3/security/api/auth/auth.

```json
{
  "data": {
    "userId": "01771533-8e75-3234-8e3d-9213ae2d7c52",
    "profile": {
      "firstName": "Пётр",
      "lastName": "Смирнов",
      "email": "buh@example.invbox.ru"
    }
  }
}
```

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

### Пример запроса с постраничным выводом: GET /v3/filter/api/order/order?_pageSize=5&_page=2

Source: https://docs.invoicebox.ru/docs/api/filters

HTTP-запрос для получения второй страницы выборки с размером страницы 5. Параметры _pageSize и _page обязательны с подчёркиванием, иначе API молча игнорирует их и возвращает первую страницу с 30 элементами.

```http
GET /v3/filter/api/order/order?_pageSize=5&_page=2

```

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

### Установка MiniApp SDK через NPM или Yarn

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Команда для добавления библиотеки @invoicebox/minapp-sdk в проект.

```bash
npm install @invoicebox/minapp-sdk || yarn add @invoicebox/minapp-sdk
```

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

### Connect to parent window

Source: https://docs.invoicebox.ru/docs/marketplace/mini-apps/miniapp-sdk

Establishes a connection with the parent window.

```typescript
connect(): void;
```