Отправить результат долгого метода

POST /v1/solution-calls/:callId/result

Принимает от решения исход вызова долгого метода по контракту и сам доставляет его на портал Битрикс24. Адрес этого маршрута, одноразовый токен ответа и срок решение получает заголовками вместе с самим вызовом, поэтому ни ключ платформы, ни отдельная настройка ему не нужны.

Как приходит долгий вызов

Метод контракта с x-vibe-async: true платформа вызывает так же, как обычный: HTTP-запросом на маршрут решения из контракта, по туннелю приложения. Долгий вызов отличают пять заголовков:

Общие заголовки вызова по контракту приходят и здесь: X-Vibe-Request-Id, X-Vibe-Caller-Kind со значением contract, X-Vibe-Caller-Portal-Id, X-Vibe-Portal-User-Id, X-Vibe-Operation-Id, X-Vibe-Contract-Version и Idempotency-Key. Заголовок X-Vibe-Invocation-Context есть только у вызова с переданным контекстом. Заголовков X-Vibe-Caller-Key-Id и X-Vibe-Caller-App-Id у вызова по контракту нет — он идёт не по ключу внешнего API.

Ответить на такой вызов решение может двумя способами:

Ответ 4xx закрывает вызов как неуспешный без результата — присылать его потом бессмысленно. Остальные ответы — 5xx, 3xx, 2xx кроме 200 и 202 — вместе с обрывом соединения и таймаутом платформа считает временным сбоем и повторяет доставку с нарастающей паузой до срока из X-Vibe-Reply-Deadline — с тем же X-Vibe-Call-Id и тем же токеном ответа, так что результат, посчитанный по первой попытке, этот маршрут принимает без оговорок.

Параметры

Аутентификация — заголовок Authorization: Bearer с токеном ответа из X-Vibe-Reply-Token того же вызова. Ключ платформы vibe_… на этом маршруте не принимается, а токен ответа не открывает ни одного другого адреса.

Поля запроса (body)

Тело — JSON с одним из двух исходов. Размер тела — до 512 КиБ, считается по сырым байтам до разбора.

Тело при failed:

{
  "outcome": "failed",
  "error": {
    "code": "INVOICE_LOCKED",
    "message": "Invoice is locked by another user",
    "problem": {
      "type": "https://example.com/problems/invoice-locked",
      "title": "Invoice locked",
      "detail": "Invoice 17 is being edited",
      "instance": "/invoices/17"
    }
  }
}

Примеры

Ось авторизации у маршрута одна — токен ответа из X-Vibe-Reply-Token, поэтому пример один на язык: личный ключ и ключ авторизации приложения получают 401 REPLY_TOKEN_INVALID.

curl — токен ответа

curl -X POST "https://vibecode.bitrix24.tech/v1/solution-calls/call_01M31PGZ80V9GJMWJ5N48AATB2/result" \
  -H "Authorization: Bearer YOUR_REPLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"outcome": "completed", "result": {"invoiceNumber": "A-17"}}'

JavaScript — токен ответа

// Заголовки входящего вызова — из обработчика долгого метода в решении.
const replyUrl = req.headers['x-vibe-reply-url'];
const replyToken = req.headers['x-vibe-reply-token'];

const res = await fetch(replyUrl, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${replyToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ outcome: 'completed', result: { invoiceNumber: 'A-17' } }),
});

const body = await res.json();
if (!body.success) {
  // 4xx закрывает вызов: повторять тот же результат бессмысленно.
  console.error(`результат не принят: ${body.error.code}`);
}

Поля ответа

Пример ответа

{
  "success": true,
  "data": {
    "state": "completed"
  }
}

Пример ответа при ошибке

422 — тело больше 512 КиБ, вызов закрыт как failed:

{
  "success": false,
  "error": {
    "code": "RESULT_INVALID",
    "message": "The result body is over the boundary-contract limit; the call is closed as failed",
    "errorCode": "SOLUTION_RESULT_TOO_LARGE",
    "limitBytes": 524288
  }
}

Поле error.errorCode называет причину — SOLUTION_RESULT_TOO_LARGE или SOLUTION_BAD_RESPONSE, и с тем же кодом исход уходит на портал. Поле error.limitBytes приходит только при превышении размера. У 409 SOLUTION_CALL_CLOSED вместо них поле error.state — состояние вызова.

Ошибки

Полный список общих ошибок API — Ошибки.

Известные особенности

• Любой 4xx закрывает вызов окончательно. 422 — не приглашение исправить тело и повторить: вызов уже переведён в failed, исход с кодом причины ушёл на портал, и тот же токен дальше отвечает 409. Проверяйте result по схеме callbacks.result до отправки — правка кода решения поможет следующему вызову, а не этому.
• Повторять нужно только после 5xx и обрыва соединения. Токен одноразов на принятый исход, а не на попытку: пока платформа не ответила 2xx или 4xx, результат не записан, и повтор с тем же адресом, токеном и телом обязателен — иначе шаг на портале дождётся срока и завершится по таймауту. Незавершённая попытка держит вызов одну-две минуты, и на это время ответ — 409 со state: accepted.
• Токен ответа — секрет одного вызова. Тот, у кого он есть, закроет ваш вызов любым результатом. Не пишите его в журнал, не показывайте в интерфейсе и не передавайте дальше. Платформа в свои журналы не пишет ни токен, ни тело результата.
• После срока или отмены результат порталу не нужен. 409 со state: expired или state: canceled — сигнал прервать долгую работу: продолжать её незачем, а её итог уже некуда принять.
• Ответ 200 означает «исход записан», а не «портал его получил». Доставку на портал платформа ведёт сама, с повторами при недоступности портала. Решению для этого ничего делать не нужно.

Смотрите также

• Внешний API приложения
• Что приходит в приложение
• Витрина приложений
• Ошибки