> For the complete documentation index, see [llms.txt](https://docs.maibmerchants.md/checkout/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maibmerchants.md/checkout/ru/getting-started/osnovy-api.md).

# Основы API

В данном разделе описываются основные принципы работы с API Checkout. Эти правила являются общими для всех эндпоинтов и должны соблюдаться для обеспечения стабильной и безопасной интеграции.

### Структура запросов

* Вся коммуникация с API осуществляется по протоколу **HTTPS** для обеспечения безопасности и целостности данных.
* Запросы и ответы передаются в формате **JSON**.
* Каждый запрос должен содержать корректный заголовок **Authorization** (см. раздел *Authentication*).
* Тела запросов должны строго соответствовать структуре параметров, определённой в спецификациях эндпоинтов.
* Ответы всегда имеют единообразный формат с полем верхнего уровня `ok` а при ошибках — массив `errors` с подробными кодами и сообщениями.

> **Совет:** всегда выполняйте проверку как HTTP-кода ответа, так и флага `ok` в JSON, чтобы корректно выявлять сбои.

***

### Доступные окружения

Для интеграции доступны два окружения:

| Окружение          | Base URL                                                               |
| ------------------ | ---------------------------------------------------------------------- |
| **Production**     | [`https://api.maibmerchants.md`](https://api.maibmerchants.md/)        |
| **Sandbox (Test)** | [`https://sandbox.maibmerchants.md`](https://sandbox.maibmerchants.md) |

* Использование окружения **sandbox** предназначено для начальной разработки и функционального тестирования без перевода реальных средств.
* После стабилизации и сертификации интеграции выполняется переход в окружение **production**.
* Эндпоинты и структуры запросов идентичны в обоих окружениях.

***

### Аутентификация

* API использует аутентификацию по схеме *Bearer token*.
* Токен доступа необходимо получить заранее (см. раздел [*Аутентификация*](/checkout/ru/api-reference/endpointy/autentifikaciya.md) для подробностей о порядке получения).
* Токен указывается в HTTP-заголовке каждого запроса:

```http
Authorization: {tokenType} {access_token}
```

* Токены являются специфичными для окружения (sandbox и production используют разные учётные данные).
* При отсутствии, истечении или недействительности токена API возвращает `401 Unauthorized`.
* Токены должны храниться конфиденциально и не размещаться в клиентском коде или публичных репозиториях.

***

### Формат данных

* **Content-Type**: все запросы должны указывать `application/json`.
* **Поля типа datetime**: всегда используется формат ISO 8601 с указанием временной зоны.
  * Пример: `2029-10-22T10:32:28+03:00`
* **Валюта**: API использует `MDL` *(молдавский лей)* в соответствии со стандартом ISO 4217.

***

### Коды ответов HTTP

API возвращает стандартные HTTP-коды для обозначения результата выполнения каждого запроса:

| Код                           | Значение                                 | Примечания                                                                                                                            |
| ----------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **200 OK**                    | Корректный запрос, ответ возвращён       | Флаг `ok`  в теле ответа будет иметь значение `true`.                                                                                 |
| **400 Bad Request**           | Некорректный запрос                      | Ошибка вызвана отсутствующими/некорректными параметрами или неверно сформированным JSON. Подробности можно найти в массиве `errors` . |
| **401 Unauthorized**          | Отсутствующий или недействительный токен | Необходимо, чтобы токен *Bearer* был указан и не имел истёкшего срока действия.                                                       |
| **403 Forbidden**             | Недостаточно прав                        | Токен действителен, но действие не разрешено для данного торговца.                                                                    |
| **500 Internal Server Error** | Неожиданная ошибка на стороне сервера    | Повторите попытку позже или обратитесь в поддержку, если проблема сохраняется.                                                        |

> **Рекомендация:** обработка ошибок должна выполняться как на основе кода HTTP, так и на основе деталей ошибки в теле JSON.