Промпт: документация к API по коду

Документация к API управления заявками (Leads)

Обзор

API позволяет внешним партнерам интегрироваться с нашей системой для работы с заявками (лидами). Основные возможности:

• Создание новых заявок (POST)
• Получение подробной информации о конкретной заявке (GET)
• Изменение статуса заявки (PATCH).

Аутентификация

Все запросы требуют наличия HTTP-заголовка X-Api-Key. Если ключ отсутствует или неверен — возвращается ошибка 401:

{"error":"unauthorized"}

Формат общих ошибок

При ошибках запросов система возвращает JSON вида:

{
    "error": "<тип ошибки>",
    "message": "<описание ошибки>"
}

Кроме того, некоторые типы ошибок содержат дополнительные поля:

• 422 Validation: поле "fields" содержит список полей с ошибкой и её описанием:

{
    "error": "validation",
    "fields": {
        "field_name": "description"
    }
}

---

Эндпоинт: создание новой заявки

Метод и путь

Метод: POST
Путь: /api/v1/leads

Описание

Создает новую заявку от партнера.

Параметры запроса

(все передаются в теле запроса):

Пример запроса (curl)

curl --location 'https://example.com/api/v1/leads' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <ваш_api_key>' \
--data '{
    "name": "Иван Иванов",
    "phone": "+79876543210",
    "source": "site",
    "comment": "Оставил заявку через сайт"
}'

Ответ сервера

Успешное создание:
Статус-код: 201 Created
Тело ответа:

{
    "id": 123,
    "status": "new"
}

Возможные ошибки:

• 422 Unprocessable Entity — проблема с форматом входных данных:

{
    "error": "validation",
    "fields": {
        "phone": "E.164 format required"
    }
}

• 409 Conflict — такая же заявка была создана ранее данным партнером менее чем сутки назад.

---

Спецификация OpenAPI 3 для эндпоинта создания заявки (YAML фрагмент)

openapi: 3.0.0
info:
  title: Leads Management API
  version: v1
paths:
  /api/v1/leads:
    post:
      summary: Создать новую заявку
      description: Регистрирует новую заявку от партнера
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 100
                  example: Иван Иванов
                phone:
                  type: string
                  pattern: ^\+?[1-9]\d{1,14}$
                  example: +79876543210
                source:
                  type: string
                  enum: ["site", "call", "partner"]
                  example: site
                comment:
                  type: string
                  maxLength: 1000
                  nullable: true
                  example: Оставил заявку через сайт
              required:
                - name
                - phone
                - source
      responses:
        '201':
          description: Заявка успешно создана
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 123
                  status:
                    type: string
                    example: new
        '422':
          description: Некорректные данные
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: validation
                  fields:
                    type: object
                    additionalProperties:
                      type: string
                    example:
                      phone: E.164 format required
        '409':
          description: Повторная заявка за последние 24 часа

---

ВОПРОСЫ К РАЗРАБОТЧИКУ

Ниже приведены замечания и вопросы по текущей реализации, которые потребуют уточнения или доработки:

1. Не указано максимальное количество попыток отправки одного и того же запроса. Возможно, стоит добавить лимитирование количества повторных отправок одной и той же заявки?

1. Как обрабатываются ситуации, когда один партнёр случайно создаёт две разные заявки с одним номером телефона? Сейчас это ограничивает возможность повторного обращения одного клиента.

1. Есть ли ограничения на частоту обращений (rate limiting)? Это могло бы защитить систему от злоупотреблений и перегрузок.

1. По статусу "lost" ожидается обязательное указание причины изменения статуса. Стоит уточнить детали формата этого поля (например, максимальная длина).

1. Что происходит, если другой партнер запрашивает доступ к чужим заявкам (например, используя чужой ID)? Техническая реализация этого механизма безопасности требует подтверждения.

1. Какие требования предъявляются к значению ключа X-Api-Key, его структуре и длине? Например, есть ли ограничение по сложности пароля?

1. Как реализуется обработка ситуаций при наличии конфликта между несколькими источниками одной заявки (если одновременно поступают несколько разных источников)?

1. Поведение системы при передаче некорректного значения параметра source: будет возвращена общая ошибка валидатора или конкретный код ошибки?

---

Документ описывает функциональность API на основе предоставленного кода и комментариев. Однако указанные вопросы помогут устранить возможные пробелы в понимании текущего поведения API и позволят улучшить документ.

API для работы с лидами

Документация предназначена для внешних партнёров-интеграторов, подключающих свою CRM.

API позволяет:

• создавать лиды;
• получать информацию о созданных лидах;
• обновлять статус лида.

Базовый URL в коде не указан: [уточнить].

---

1. Обзор

Аутентификация

Все запросы к API требуют передачи API-ключа в HTTP-заголовке:

X-Api-Key: <api-key>

Если заголовок отсутствует или ключ невалиден, API возвращает:

401 Unauthorized

{
  "error": "unauthorized"
}

Формат и способ получения API-ключа: [уточнить].

---

Формат данных

API принимает и возвращает данные в формате JSON.

Для запросов с телом необходимо передавать заголовок:

Content-Type: application/json

---

Общий формат ошибок

Из кода явно видны следующие форматы ошибок.

Ошибка авторизации

{
  "error": "unauthorized"
}

Ошибка валидации

{
  "error": "validation",
  "fields": {
    "phone": "e164"
  }
}

Где:

Формат ошибок для 404 и 409 в коде не указан: [уточнить].

---

2. Эндпоинты

---

Создание лида

POST /api/v1/leads

Создаёт нового лида от имени партнёра, определённого по API-ключу.

Если лид с таким телефоном уже был создан этим же партнёром за последние 24 часа, API возвращает ошибку 409 Conflict.

---

Параметры тела запроса

> Примечание: поле source имеет ограничение oneof=site call partner, но в коде не указано required. Поведение при отсутствии поля — [уточнить].

---

Пример запроса

curl -X POST 'https://api.example.com/api/v1/leads' \
  -H 'X-Api-Key: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Иван Петров",
    "phone": "+79991234567",
    "source": "partner",
    "comment": "Интересуется продуктом"
  }'

> Базовый домен https://api.example.com приведён как пример: [уточнить].

---

Пример успешного ответа

201 Created

{
  "id": 123,
  "status": "new"
}

---

Коды ошибок

---

Получение лида

GET /api/v1/leads/{id}

Возвращает информацию о лиде по его идентификатору.

Если лид не найден или принадлежит другому партнёру, API возвращает 404 Not Found.

---

Параметры пути

---

Пример запроса

curl -X GET 'https://api.example.com/api/v1/leads/123' \
  -H 'X-Api-Key: <api-key>'

---

Пример успешного ответа

200 OK

{
  "id": 123,
  "name": "Иван Петров",
  "phone": "+79991234567",
  "status": "new",
  "created_at": "2026-10-06T12:34:56Z"
}

---

Поля ответа

---

Коды ошибок

---

Обновление статуса лида

PATCH /api/v1/leads/{id}/status

Обновляет статус лида.

Допустимые целевые статусы:

• in_work;
• won;
• lost.

Для статуса lost поле reason обязательно.

Если лид уже находится в финальном статусе won или lost, изменить его статус нельзя. В этом случае API возвращает 409 Conflict.

---

Параметры пути

---

Параметры тела запроса

Ограничения на длину поля reason не указаны: [уточнить].

---

Пример запроса: перевод в работу

curl -X PATCH 'https://api.example.com/api/v1/leads/123/status' \
  -H 'X-Api-Key: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "in_work"
  }'

---

Пример запроса: закрытие как проигранного

curl -X PATCH 'https://api.example.com/api/v1/leads/123/status' \
  -H 'X-Api-Key: <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "lost",
    "reason": "Клиент отказался"
  }'

---

Пример успешного ответа

Тело успешного ответа в коде не указано: [уточнить].

200 OK

{}

> Пример тела ответа приведён только как заглушка. Фактический формат — [уточнить].

---

Коды ошибок

> Для PATCH /api/v1/leads/{id}/status в коде явно указан только конфликт 409 при попытке перехода из won или lost. Коды и формат ошибок для невалидного тела, отсутствующего лида и прочих случаев — [уточнить].

---

3. Фрагмент OpenAPI 3 для создания лида

openapi: 3.0.3
info:
  title: Leads API
  version: 1.0.0

paths:
  /api/v1/leads:
    post:
      summary: Создать лида
      description: Создаёт нового лида от имени партнёра, определённого по API-ключу.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - phone
              properties:
                name:
                  type: string
                  maxLength: 100
                  description: Имя лида.
                  example: Иван Петров
                phone:
                  type: string
                  description: Телефон в формате E.164.
                  example: "+79991234567"
                source:
                  type: string
                  enum:
                    - site
                    - call
                    - partner
                  description: Источник лида.
                  example: partner
                comment:
                  type: string
                  maxLength: 1000
                  description: Комментарий.
                  example: Интересуется продуктом
      responses:
        "201":
          description: Лид создан
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                  - status
                properties:
                  id:
                    type: integer
                    example: 123
                  status:
                    type: string
                    example: new
        "401":
          description: Не передан или невалиден API-ключ
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                    example: unauthorized
        "409":
          description: Лид с таким телефоном уже создан этим партнёром за последние 24 часа
        "422":
          description: Ошибка валидации
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                  - fields
                properties:
                  error:
                    type: string
                    example: validation
                  fields:
                    type: object
                    additionalProperties:
                      type: string
                    example:
                      phone: e164

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key

---

4. Вопросы к разработчику

1. Какой базовый URL API?

В коде указаны только пути /api/v1/....

1. Как партнёр получает X-Api-Key?

Не указаны процесс выдачи, ротации и отзыва ключей.

1. Поле source действительно необязательное?

Валидация содержит oneof=site call partner, но нет required. Нужно уточнить поведение при отсутствии source.

1. Какой формат ошибок для 409?

Для конфликтов описан только HTTP-код, тело ответа не указано.

1. Какой формат ошибок для 404?

Для случая «не найден или принадлежит другому партнёру» тело ответа не указано.

1. Какой успешный ответ у PATCH /api/v1/leads/{id}/status?

В коде не указан ни HTTP-код, ни тело ответа.

1. Какие ошибки валидации возвращает PATCH /status?

Не указан код и формат ответа при:

• отсутствующем status;
• недопустимом status;
• отсутствии reason для lost;
• некорректном JSON.

1. Какие допустимые переходы статусов, кроме запрета переходов из won и lost?

Из кода видно только, что из won и lost переходить нельзя. Неясно, можно ли, например:

• new → won;
• new → lost;
• in_work → new.

1. Сохраняется ли reason для статусов, отличных от lost?

В коде указано только, что reason обязателен для lost.

1. Есть ли ограничения на длину reason?

В коде ограничения не указаны.

1. Как определяется дубль лида по телефону?

Указано: «лид с таким телефоном уже создан этим партнёром за последние 24 часа». Нужно уточнить:

• сравнение строго по строке или после нормализации;
• учитываются ли только активные лиды или любые;
• от какого времени отсчитываются 24 часа.

1. Какой тип идентификатора id?

В примерах используется число 123, но точный тип и диапазон не указаны.

1. Какая таймзона используется в created_at?

Указан формат RFC3339, но не указано, всегда ли время возвращается в UTC.

1. Возвращаются ли поля source и comment при получении лида?

В ответе GET /api/v1/leads/{id} они не указаны, хотя передаются при создании.

1. Что возвращается при невалидном или отсутствующем Content-Type?

Поведение не описано.

1. Есть ли лимиты запросов и ограничения по частоте?

В коде не указано, но для партнёрской интеграции это важно.

1. Идемпотентно ли создание лида?

Сейчас при дубле за 24 часа указан 409. Нужно уточнить, возвращается ли существующий id или только ошибка.

1. Может ли партнёр получать только свои лиды?

Для GET указано, что чужой лид возвращает 404. Для PATCH аналогичное поведение не описано явно — [уточнить].

Документация API интеграции CRM

1. Обзор

API предназначено для создания и управления лидами (заявками), поступающими от партнёрских систем (CRM), во внешнюю систему обработки лидов.

Базовый URL: [уточнить] (в коде не указан, используется относительный путь /api/v1/...)

Аутентификация

Все запросы должны содержать заголовок:

X-Api-Key: <ваш ключ>

Если заголовок отсутствует или ключ недействителен, сервер возвращает:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{"error": "unauthorized"}

[уточнить] — различаются ли коды/сообщения для случаев «ключ отсутствует» и «ключ невалиден», либо ответ всегда одинаковый.

Формат ошибок

Общий вид ошибки:

{"error": "<код_ошибки>"}

Для ошибок валидации (422) добавляется объект fields с описанием проблемных полей:

{"error": "validation", "fields": {"phone": "e164"}}

[уточнить] — какой формат значений в fields для остальных типов ошибок (required, max, oneof); в коде показан пример только для phone.

---

2. Эндпоинты

2.1. POST /api/v1/leads

Создаёт новый лид.

Заголовки

Тело запроса

Пример запроса

curl -X POST https://example.com/api/v1/leads \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Иван Иванов",
        "phone": "+79991234567",
        "source": "site",
        "comment": "Интересует тариф Pro"
      }'

Успешный ответ

HTTP/1.1 201 Created
Content-Type: application/json

{"id": 123, "status": "new"}

Статус созданного лида всегда new.

Коды ошибок

[уточнить] — какое тело возвращается при 409 (есть ли там id существующего лида).

---

2.2. GET /api/v1/leads/{id}

Возвращает данные лида по идентификатору.

Параметры пути

Заголовки

Пример запроса

curl -X GET https://example.com/api/v1/leads/123 \
  -H "X-Api-Key: YOUR_API_KEY"

Успешный ответ

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 123,
  "name": "Иван Иванов",
  "phone": "+79991234567",
  "status": "new",
  "created_at": "2024-01-15T10:30:00Z"
}

status может принимать значения: new, in_work, won, lost.
created_at — в формате RFC3339.

[уточнить] — в ответе отсутствуют поля source и comment, которые были переданы при создании. Это намеренное поведение или недочёт?

Коды ошибок

Обратите внимание: для «не найден» и «принадлежит другому партнёру» возвращается один и тот же код 404 без уточнения причины — вероятно, в целях безопасности (чтобы не раскрывать факт существования чужих лидов).

---

2.3. PATCH /api/v1/leads/{id}/status

Изменяет статус лида.

Параметры пути

Заголовки

Тело запроса

Пример запроса

curl -X PATCH https://example.com/api/v1/leads/123/status \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "lost", "reason": "Клиент отказался"}'

Успешный ответ

[уточнить] — код и тело успешного ответа не описаны в коде/комментариях (предположительно 200, но формат тела неизвестен).

Коды ошибок

---

3. Фрагмент OpenAPI 3 (YAML) — создание лида

openapi: 3.0.3
info:
  title: Lead Integration API
  version: "1.0.0"
paths:
  /api/v1/leads:
    post:
      summary: Создать лид
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LeadIn'
            example:
              name: "Иван Иванов"
              phone: "+79991234567"
              source: "site"
              comment: "Интересует тариф Pro"
      responses:
        '201':
          description: Лид успешно создан
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    example: 123
                  status:
                    type: string
                    enum: [new]
                    example: new
        '401':
          description: Отсутствует или неверный API-ключ
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: unauthorized
        '409':
          description: Лид с таким телефоном уже создан этим партнёром за последние 24 часа
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Ошибка валидации полей
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              example:
                error: validation
                fields:
                  phone: e164

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key

  schemas:
    LeadIn:
      type: object
      required:
        - name
        - phone
        - source
      properties:
        name:
          type: string
          maxLength: 100
          example: "Иван Иванов"
        phone:
          type: string
          description: Телефон в формате E.164
          example: "+79991234567"
        source:
          type: string
          enum: [site, call, partner]
          example: site
        comment:
          type: string
          maxLength: 1000
          nullable: true

    ErrorResponse:
      type: object
      properties:
        error:
          type: string

    ValidationErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: validation
        fields:
          type: object
          additionalProperties:
            type: string

---

4. Вопросы к разработчику

1. Тело успешного ответа PATCH /status — в коде не указано, что возвращается при успешной смене статуса (код, поля).
2. Тела ответов 409 и 404 — не описан формат (только код). Нужно ли туда что-то, кроме {"error": "..."}, например id конфликтующего лида?
3. Формат fields в 422 — показан пример только для phone ("e164"). Какие значения будут для required, max, oneof? Нужна таблица соответствия тегов валидации и кодов ошибок.
4. Пропавшие поля в GET-ответе — source и comment передаются при создании, но отсутствуют в примере ответа GET /leads/{id}. Это осознанное решение или недоработка?
5. Переходы статусов — явно запрещён переход из won/lost. А разрешён ли прямой переход new → won или new → lost, минуя in_work? Это не ограничено в коде, но не ясно, так ли задумано.
6. Невалидный status в PATCH — что будет, если передано значение вне in_work|won|lost (например, опечатка)? Это 422 или другой код?
7. reason при статусах, отличных от lost — если передать reason, но статус не lost, игнорируется ли поле или вызовет ошибку?
8. Поведение при обновлении текущего статуса на тот же самый (например, in_work → in_work) — разрешено или это тоже 409?
9. Различие кодов при отсутствующем и неверном ключе — всегда ли 401 unauthorized, или есть иные состояния (например, заблокированный партнёр)?
10. Rate limiting / пагинация — не описаны в коде, но важно уточнить для партнёров (лимиты запросов, есть ли список лидов).

API Интеграции CRM Партнёров

Данная документация предназначена для внешних партнёров-интеграторов, подключающих свои CRM-системы к нашей платформе. API позволяет создавать новые лиды, получать информацию о существующих и обновлять их статусы.

1. Обзор

Что делает API?

API предоставляет набор методов для управления лидами:

• Создание лидов: Позволяет партнёрам передавать информацию о потенциальных клиентах в нашу систему.
• Получение информации о лидах: Предоставляет детализированную информацию о конкретном лиде.
• Обновление статуса лидов: Даёт возможность партнёрам изменять текущий статус лида в соответствии с жизненным циклом продаж.

Аутентификация

Все запросы к API требуют наличия заголовка X-Api-Key. Этот заголовок должен содержать уникальный ключ, выданный вашему партнёру.

Пример заголовка:

X-Api-Key: your_api_key_here

В случае отсутствия или неверного ключа API, будет возвращена ошибка 401 Unauthorized.

Общий формат ошибок

В случае возникновения ошибок, API возвращает JSON-объект с описанием проблемы.

Ошибка аутентификации:

{
  "error": "unauthorized"
}

Ошибка валидации:

{
  "error": "validation",
  "fields": {
    "phone": "e164"
  }
}

Поле fields содержит объект, где ключи — это имена полей, вызвавших ошибку, а значения — коды ошибок валидации.

2. Эндпоинты

2.1. Создание нового лида

Метод: POST
Путь: /api/v1/leads

Описание:
Создаёт новый лид в системе. Каждый лид привязывается к партнёру, который его создал.

Параметры запроса (тело JSON):

| Имя | Тип | Обязательный | Описание