API для выдачи спонсорских карточек в Telegram-боте

Authorization: Bearer EVIR_API_KEY
Content-Type: application/json

В заголовке замените EVIR_API_KEY значением ключа. В командах Bash ниже $EVIR_API_KEY подставляет его из окружения. Чаты подключаются отдельно через @EvirBot и не используют этот ключ.

{
  "data": {
    "assignments": [{
      "deliveryId": "AbCdEfGhIjKlMnOpQrStUvWxYz012345",
      "title": "Заголовок",
      "description": "Текст карточки",
      "ctaLabel": "Открыть",
      "actionUrl": "https://t.me/EvirBot/delivery?startapp=ia_AbCdEfGhIjKlMnOpQrStUvWxYz012345&mode=compact",
      "allowSkip": false,
      "topicCode": "technology",
      "targetType": "channel",
      "targetUsername": "example_channel",
      "expiresAt": "2026-09-04T12:05:00.000Z",
      "productType": "impression",
      "requiresServedAck": true,
      "requiresQualification": true,
      "billingMode": "qualified_action",
      "outcomeType": "membership"
    }]
  },
  "meta": { "requestId": "http-request-id" }
}

productType: recommendation | impression | transition | op; ctaKind: subscribe | start | open. Эти поля и requiresServedAck / requiresQualification могут отсутствовать у legacy-рекомендаций. assignments: [] — нормальный успешный ответ: продолжите обычный сценарий бота.

curl -sS -X POST https://evir.me/api/v1/integrations/deliveries/check \
  -H "Authorization: Bearer $EVIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipientId":"123456789","deliveryIds":["AbCdEfGhIjKlMnOpQrStUvWxYz012345"]}'

Используйте from.id нажавшего «Проверить»: он должен совпадать с recipientId из next. Проверка не подтверждает отправку автоматически. Показы ждут подтверждённой подписки или /start; переход — авторизованного открытия; ОП — подписки, подходящей заявки или запуска бота.

curl -sS -X POST "https://evir.me/api/v1/integrations/deliveries/$EVIR_DELIVERY_ID/qualify" \
  -H "Authorization: Bearer $EVIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"recipientId":"123456789"}'

Успешный data: { "qualified": true, "settled": true, "alreadySettled": false, "proof": "membership" }. proof: join_request означает подтверждённую заявку. Повтор served, check или qualify не создаёт второго начисления.