docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/functionality/callback/README.md
новий файл +62
−0
1
+
# Відповідь на webhook
2
+
3
+
Для довгих операцій клієнту не обов'язково чекати результату. Спеціальний параметр `$rpc.callback` каже серверу: прийми запит, одразу підтверди, а результат надішли на вказаний URL, коли метод виконається.
4
+
5
+
## Запит
6
+
7
+
```json
8
+
{
9
+
"jsonrpc": "2.0",
10
+
"id": "order-42",
11
+
"method": "Orders.export",
12
+
"params": {
13
+
"id": 42,
14
+
"$rpc": {"callback": "https://client.example/rpc-callback"}
15
+
}
16
+
}
17
+
```
18
+
19
+
`callback` має бути повною адресою з протоколом `http` або `https`. Адреса перевіряється одразу: якщо вона невалідна або не відповідає, запит повертає помилку валідації.
20
+
21
+
## Миттєва відповідь
22
+
23
+
```json
24
+
{
25
+
"jsonrpc": "2.0",
26
+
"id": "order-42",
27
+
"result": {"async": true, "callback": "https://client.example/rpc-callback"}
28
+
}
29
+
```
30
+
31
+
## Доставка результату
32
+
33
+
Метод виконується **після** відправлення миттєвої відповіді (подія `rpc.post_response`). Повна JSON-RPC відповідь — з `result` або `error` — надсилається POST-запитом на callback URL:
34
+
35
+
```json
36
+
{
37
+
"jsonrpc": "2.0",
38
+
"id": "order-42",
39
+
"result": {"orderId": 42, "status": "exported"}
40
+
}
41
+
```
42
+
43
+
Запит на callback має `Content-Type` і `Accept` `application/json`, таймаут 10 с (не більше 15 с загалом). З вхідного HTTP-запиту пересилаються лише заголовки трасування: `X-Request-Id`, `X-Correlation-Id`, `traceparent`, `tracestate`, `baggage`. Токен та інші облікові дані клієнта **не** пересилаються, тож автентифікацію callback-endpoint налаштовуйте окремо (наприклад, секретом у самому URL).
44
+
45
+
Відповідь callback-endpoint зі статусом поза 2xx вважається помилкою доставки й пишеться в лог.
46
+
47
+
:::info subtitle="Версії 9.2.0–10.0.5"
48
+
У цих версіях на callback пересилалися **всі** заголовки клієнта, включно з RPC-токеном. Див. [Виправлені помилки](/docs/api/json-rpc-bundle/developers/known_issues/fixed).
49
+
:::
50
+
51
+
:::warning
52
+
Під PHP-FPM метод виконується після `fastcgi_finish_request()`, і клієнт не чекає. В інших SAPI метод теж виконається, але HTTP-воркер зайнятий до його завершення. Для довгих методів можна ввімкнути від'єднане виконання — `notification.process` у [налаштуваннях](/docs/api/json-rpc-bundle/config).
53
+
:::
54
+
55
+
## Алгоритм
56
+
57
+
1. Отримати запит з `$rpc.callback` і провалідувати URL.
58
+
2. Одразу повернути клієнту `{"async": true, "callback": "<url>"}`.
59
+
3. Після відправлення відповіді виконати метод.
60
+
4. Надіслати JSON-RPC відповідь POST-запитом на callback URL.
61
+
62
+
Помилки доставки на callback у миттєвій відповіді не повідомляються.