{
  "name": "Nika AI Lead Payload Schema",
  "version": "2026-07-29",
  "language": "ru",
  "endpoint": "https://agentnika.ru/api/leads",
  "method": "POST",
  "content_type": "application/json",
  "schema_url": "https://agentnika.ru/lead-schema.json",
  "integrations_page": "https://agentnika.ru/integrations",
  "receiver_contract_url": "https://agentnika.ru/webhook-receiver.json",
  "webhook_auth": {
    "type": "optional_bearer_token",
    "header": "Authorization: Bearer <NIKA_LEAD_WEBHOOK_TOKEN>"
  },
  "webhook_idempotency": {
    "header": "Idempotency-Key: <leadId>",
    "description": "Webhook delivery sends leadId as Idempotency-Key so receiving systems can deduplicate retries or repeated submissions."
  },
  "telegram_delivery": {
    "type": "optional_direct_bot_message",
    "required_environment": ["NIKA_LEAD_TELEGRAM_BOT_TOKEN", "NIKA_LEAD_TELEGRAM_CHAT_ID"],
    "optional_environment": ["NIKA_LEAD_TELEGRAM_THREAD_ID"],
    "message": "summaryText is sent to the configured Telegram chat when no webhook endpoint is configured."
  },
  "request_schema": {
    "type": "object",
    "required": ["name", "contact", "business", "task", "consent"],
    "properties": {
      "source": {
        "type": "string",
        "default": "nika-ai-site",
        "description": "Public source identifier for the site."
      },
      "leadId": {
        "type": "string",
        "description": "Stable lead identifier for webhook idempotency, CRM records, tables, and owner follow-up."
      },
      "sourcePath": {
        "type": "string",
        "example": "/products/product-card-generator",
        "description": "Route where the visitor prepared the lead."
      },
      "sourceUrl": {
        "type": "string",
        "example": "/products/product-card-generator?utm_source=telegram&utm_medium=social&utm_campaign=first-pilot",
        "description": "Full site path, query, and hash where the visitor prepared the lead."
      },
      "referrer": {
        "type": "string",
        "description": "Browser referrer when available."
      },
      "utmSource": {
        "type": "string",
        "description": "utm_source campaign label from the landing URL."
      },
      "utmMedium": {
        "type": "string",
        "description": "utm_medium campaign label from the landing URL."
      },
      "utmCampaign": {
        "type": "string",
        "description": "utm_campaign campaign label from the landing URL."
      },
      "utmContent": {
        "type": "string",
        "description": "utm_content campaign label from the landing URL."
      },
      "utmTerm": {
        "type": "string",
        "description": "utm_term campaign label from the landing URL."
      },
      "createdAt": {
        "type": "string",
        "format": "date-time",
        "description": "Browser-side ISO timestamp when the lead was prepared."
      },
      "name": {
        "type": "string",
        "minLength": 2,
        "description": "Visitor name."
      },
      "contact": {
        "type": "string",
        "minLength": 2,
        "description": "Phone, Telegram, MAX, email, or another return contact."
      },
      "business": {
        "type": "string",
        "minLength": 2,
        "description": "Business type or company context."
      },
      "interest": {
        "type": "string",
        "description": "Selected product, ready agent, or custom development direction."
      },
      "task": {
        "type": "string",
        "minLength": 2,
        "description": "Visitor's task or request summary."
      },
      "preferredChannel": {
        "type": "string",
        "description": "Preferred reply channel selected in the form."
      },
      "consent": {
        "type": "boolean",
        "const": true,
        "description": "Explicit consent to process personal data for replying to the request."
      },
      "consentText": {
        "type": "string",
        "description": "Human-readable consent text shown near the checkbox."
      },
      "summaryText": {
        "type": "string",
        "description": "Human-readable lead summary prepared for the owner, messenger, CRM, table, or automation."
      },
      "status": {
        "type": "string",
        "enum": ["prepared_not_sent"],
        "description": "Client-side status before Worker acceptance."
      }
    }
  },
  "accepted_payload_additions": {
    "receivedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Worker-side ISO timestamp when the lead was accepted."
    },
    "leadId": {
      "type": "string",
      "description": "Worker-side stable lead identifier, generated when a direct API request does not provide one."
    },
    "status": {
      "type": "string",
      "enum": ["accepted"],
      "description": "Worker-side status after validation."
    },
    "summaryText": {
      "type": "string",
      "description": "Worker-side readable summary generated or refreshed before webhook delivery."
    }
  },
  "response_schema": {
    "type": "object",
    "required": ["ok", "delivery", "lead"],
    "properties": {
      "ok": {
        "type": "boolean",
        "const": true
      },
      "delivery": {
        "type": "string",
        "enum": ["delivered", "stored_without_webhook", "webhook_failed", "telegram_failed"]
      },
      "webhookStatus": {
        "type": "number",
        "description": "HTTP status from the configured webhook, or 0 when the request cannot be completed."
      },
      "webhookError": {
        "type": "string",
        "enum": ["timeout", "request_failed"],
        "description": "Network delivery error detail when available."
      },
      "telegramStatus": {
        "type": "number",
        "description": "HTTP status from the Telegram Bot API, or 0 when the request cannot be completed."
      },
      "telegramError": {
        "type": "string",
        "enum": ["timeout", "request_failed"],
        "description": "Telegram delivery error detail when available."
      },
      "lead": {
        "type": "object",
        "description": "Accepted lead payload including receivedAt and status: accepted."
      }
    }
  },
  "validation_errors": [
    "missing_name",
    "missing_contact",
    "missing_business",
    "missing_task",
    "missing_consent",
    "invalid_json",
    "method_not_allowed"
  ],
  "delivery_outcomes": [
    "delivered",
    "stored_without_webhook",
    "webhook_failed",
    "telegram_failed"
  ],
  "sample_request": {
    "source": "nika-ai-site",
    "leadId": "lead_demo_product_card_generator_001",
    "sourcePath": "/products/product-card-generator",
    "sourceUrl": "/products/product-card-generator?utm_source=telegram&utm_medium=social&utm_campaign=first-pilot",
    "referrer": "https://example.com/",
    "utmSource": "telegram",
    "utmMedium": "social",
    "utmCampaign": "first-pilot",
    "utmContent": "post-1",
    "utmTerm": "marketplace-card",
    "createdAt": "2026-07-29T09:00:00.000Z",
    "name": "Visitor Name",
    "contact": "telegram: @visitor",
    "business": "Marketplace seller",
    "interest": "Product Card Generator",
    "task": "Prepare marketplace product cards for a first pilot batch.",
    "preferredChannel": "Telegram",
    "consent": true,
    "consentText": "Consent to process personal data for replying to the request",
    "summaryText": "Заявка Nika AI\nID заявки: lead_demo_product_card_generator_001\nИмя: Visitor Name\nКонтакт: telegram: @visitor\nБизнес: Marketplace seller\nИнтерес: Product Card Generator\nКанал ответа: Telegram\nСтраница: /products/product-card-generator\nИсточник: /products/product-card-generator?utm_source=telegram&utm_medium=social&utm_campaign=first-pilot\nКампания: source=telegram; medium=social; campaign=first-pilot; content=post-1; term=marketplace-card\nРеферер: https://example.com/\nЗадача: Prepare marketplace product cards for a first pilot batch.\nСогласие на обработку персональных данных: получено",
    "status": "prepared_not_sent"
  },
  "sample_accepted_payload": {
    "source": "nika-ai-site",
    "leadId": "lead_demo_product_card_generator_001",
    "sourcePath": "/products/product-card-generator",
    "sourceUrl": "/products/product-card-generator?utm_source=telegram&utm_medium=social&utm_campaign=first-pilot",
    "referrer": "https://example.com/",
    "utmSource": "telegram",
    "utmMedium": "social",
    "utmCampaign": "first-pilot",
    "utmContent": "post-1",
    "utmTerm": "marketplace-card",
    "createdAt": "2026-07-29T09:00:00.000Z",
    "receivedAt": "2026-07-29T09:00:02.000Z",
    "name": "Visitor Name",
    "contact": "telegram: @visitor",
    "business": "Marketplace seller",
    "interest": "Product Card Generator",
    "task": "Prepare marketplace product cards for a first pilot batch.",
    "preferredChannel": "Telegram",
    "consent": true,
    "consentText": "Consent to process personal data for replying to the request",
    "summaryText": "Заявка Nika AI\nID заявки: lead_demo_product_card_generator_001\nИмя: Visitor Name\nКонтакт: telegram: @visitor\nБизнес: Marketplace seller\nИнтерес: Product Card Generator\nКанал ответа: Telegram\nСтраница: /products/product-card-generator\nИсточник: /products/product-card-generator?utm_source=telegram&utm_medium=social&utm_campaign=first-pilot\nКампания: source=telegram; medium=social; campaign=first-pilot; content=post-1; term=marketplace-card\nРеферер: https://example.com/\nЗадача: Prepare marketplace product cards for a first pilot batch.\nСогласие на обработку персональных данных: получено",
    "status": "accepted"
  }
}