---
title: Описать протокол с конвертом
description: Вынесите method, correlation id и payload в протокол сервиса.
sources:
  - eazy_sdk.protocols.JsonRpc
  - eazy_sdk.protocols.Envelope
  - eazy_sdk.protocols.rpc_result
draft: false
api_fingerprint: "sha256:6c1e22fdb8e6a3fccf20e40d6a1f94c03b2361ac1353e43c48d1edc53457e228"
---

Конверт не является сетевым транспортом.

Он добавляет к полезной нагрузке method, correlation id и служебные поля. Конверт принадлежит
сервису, поэтому объявляется на роутере и применяется ко всем его RPC-операциям.

```{literalinclude} ../../../../../examples/docs/protocols.py
:language: python
:start-after: "# region docs: protocols"
:end-before: "# endregion docs: protocols"
```

`JsonRpc(path="/rpc")` выбирает общий HTTP-путь. `Rpc.method(...)` задаёт имя внутри тела, а поля
операции становятся `params`. Публичный вызов остаётся обычным типизированным методом.

:::{dropdown} Файл целиком
```{literalinclude} ../../../../../examples/docs/protocols.py
:language: python
```
:::

<!-- example-output: examples.docs.protocols -->
```text
receipt: receipt-42
POST api.mail.example/rpc
```

## Место конверта в запросе

```text
модель → проекция → конверт → кодирование → шифрование байтов → подпись
```

Подпись и шифрование всего payload получают конверт целиком. Значение JSON-RPC `id` по умолчанию
сохраняется при retry, чтобы сервер мог распознать дубликат. Для сервиса, который требует новый
идентификатор, укажите `id_on_retry="regenerate"`.

JSON-RPC обычно сообщает ошибку внутри ответа `200`. `rpc_result(...)`, `rpc_error(...)` и
`rpc_error_default(...)` превращают result и error в обычные response cases, поэтому вызывающий
получает тот же `ApiError`, что и у REST.

Пакетный JSON-RPC вызов не входит в прозрачный runtime. Частичный успех нарушает соответствие
одной операции одному типизированному результату, а повтор всего batch больше нельзя считать
безопасным только по свойствам отдельных элементов.

## Дальше

- {doc}`Объявить WebSocket API </guide/websocket>`
- {doc}`Подписать конверт </guide/signing>`
- {doc}`Справочник моделей и кодеков </reference/api/models-codecs>`