# Общая информация

### Терминология

- **Узел** - конечный URL, к которому отправляются запросы. Например - `https://service.leadhit.ru/api/v1/orders/`.
- **Методы** - методы, которые принимают узлы, являются обычными питоновскими функциями.

### API

API располагается по адресу [https://service.leadhit.ru/api/v1/](https://service.leadhit.ru/api/v1/)

- Основной протокол - JSON-RPC 2.0
- Content-type - application/json

### Карта методов
У каждого узла API есть специальная страница - карта методов.
На этой странице можно увидеть все существующие методы данного узла, а также дополнительную информацию о них.

Ее можно найти, если выполнить GET-запрос (или зайти через браузер), добавив к интересующему вас URL узла в конце `/map`.

Пример карты методов:

`https://service.leadhit.ru/api/v1/orders/map`

### Авторизация
Чтобы пользоваться API, сначала необходимо получить API key. Обратитесь к своему менеджеру за ним.

После того, как вы получили ключ, вам необходимо передать его в заголовке POST-запроса к API. Он должен иметь название API-KEY (или api-key).

В случае, если API не получило авторизационный ключ в заголовке, вы получите ответ 403.

### Базовый запрос
Общение с API происходит по протоколу JSON-RPC 2.0, через POST-запросы.<br>
Content-type должен быть `application/json`.<br>
Не забывайте об авторизации (заголовок API-KEY).

Помимо этого, каждый запрос к API должен содержать в себе три обязательных параметра - метод, версия JSON-RPC, id запроса. JSON-RPC всегда равен 2.0, а id может быть любым, такой же id вернется в ответе на запрос:
```json
"method": "example_method"
"jsonrpc": "2.0"
"id": 0
```
Помимо обязательных параметров, методы принимают аргументы, котороые передаются через "params".<br>
Могут быть либо списком, либо словарем.

В качестве примера - метод **set_order_status**.
```json
Запрос:

{
  "method": "set_order_status",
  "params": {
    "order_id": "f168148717",
    "status": "paid"
  }, 
  "jsonrpc": "2.0"
  "id": 0
}
```
Ответ:
```json
{
  "jsonrpc": "2.0",
  "result": {
    "status": "ok",
    "message": "Order status changed"
  },
  "id": 0
}
```
### Ошибки
В случае, если вы не авторизованы, сервер вернет статус 403.<br>
Если вы ошиблись в параметре, или произошла какая-то другая ошибка, сервер вернет статус 200, а в теле ответа будет содержаться ключ **error**, в котором описана причина ошибки.
```json
{
  "jsonrpc": "2.0",
  "id": 0,
  "error": {
    "message": "Server error",
    "code": -32000,
    "data": {
      "message": "Possible statuses: paid, submitted",
      "args": [
        "Possible statuses: paid, submitted"
      ],
      "type": "ValidationError"
    }
  }
}
```