{
    "openapi": "3.0.3",
    "info": {
        "title": "Wellemo B2B API",
        "version": "1.1",
        "description": "Интеграция HR/LMS/CRM с бизнес-кабинетом Wellemo: сотрудники, назначения курсов, прогресс и результаты, отчёты, вебхуки.\n\nАутентификация: `Authorization: Bearer <token>`. Токен выпускается администратором компании в кабинете (Интеграции → Токены) и привязан к компании.\n\nScopes: `b2b_read` — чтение; `b2b_provision` — сотрудники; `b2b_assignment` — назначения. Базовый `b2b_api` включён во все токены.\n\nВебхуки (настраиваются в кабинете): `assignment.created`, `assignment.completed`, `assignment.failed`, `assignment.overdue`, `employee.joined`, `employee.removed`. POST JSON на ваш URL, подпись `X-Wellemo-Signature: sha256=HMAC_SHA256(body, secret)`, заголовки `X-Wellemo-Event`, `X-Wellemo-Delivery`. Ретраи: до 6 попыток (1м, 5м, 15м, 1ч, 6ч)."
    },
    "servers": [
        {
            "url": "https://wellemo.com/api/b2b/v1"
        }
    ],
    "components": {
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer"
            }
        },
        "schemas": {
            "Employee": {
                "type": "object",
                "example": {
                    "id": 101,
                    "externalId": "EMP-001",
                    "email": "user@company.ru",
                    "name": "Иван Иванов",
                    "role": "employee",
                    "tags": [
                        "sales"
                    ],
                    "joinedAt": "2026-08-01T10:00:00+00:00"
                }
            },
            "Assignment": {
                "type": "object",
                "example": {
                    "id": 505,
                    "externalId": "ASSIGN-1",
                    "employeeExternalId": "EMP-001",
                    "employeeEmail": "user@company.ru",
                    "courseId": 45,
                    "courseName": "Onboarding",
                    "status": "started",
                    "statusCategory": "in_progress",
                    "isOverdue": false,
                    "completionPercent": 45.5,
                    "score": null,
                    "numberOfAttempts": 1,
                    "isRequired": true,
                    "assignedAt": "2026-08-01T10:00:00+00:00",
                    "deadline": "2026-08-31T23:59:59+00:00",
                    "startedAt": "2026-08-02T09:00:00+00:00",
                    "completedAt": null,
                    "lastActivityAt": "2026-08-02T09:30:00+00:00"
                }
            }
        }
    },
    "security": [
        {
            "bearerAuth": []
        }
    ],
    "paths": {
        "/employees/provision": {
            "post": {
                "summary": "Создать/привязать сотрудника по externalId (идемпотентно)",
                "tags": [
                    "Employees"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "externalId": "EMP-001",
                                "email": "user@company.ru",
                                "name": "Иван Иванов"
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "status: created | linked | found",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "id": 101,
                                        "externalId": "EMP-001",
                                        "email": "user@company.ru",
                                        "status": "created"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/employees": {
            "get": {
                "summary": "Список сотрудников",
                "tags": [
                    "Employees"
                ],
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 500
                        }
                    },
                    {
                        "name": "externalId",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "email",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "tag",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "items + pagination",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "items": [
                                            {
                                                "id": 101,
                                                "externalId": "EMP-001",
                                                "email": "user@company.ru",
                                                "name": "Иван Иванов",
                                                "role": "employee",
                                                "tags": [
                                                    "sales"
                                                ],
                                                "joinedAt": "2026-08-01T10:00:00+00:00"
                                            }
                                        ],
                                        "pagination": {
                                            "page": 1,
                                            "limit": 100,
                                            "total": 1,
                                            "pages": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/employees/{externalId}": {
            "get": {
                "summary": "Сотрудник и его назначения",
                "tags": [
                    "Employees"
                ],
                "parameters": [
                    {
                        "name": "externalId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "employee",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "id": 101,
                                        "externalId": "EMP-001",
                                        "email": "user@company.ru",
                                        "name": "Иван Иванов",
                                        "role": "employee",
                                        "tags": [
                                            "sales"
                                        ],
                                        "joinedAt": "2026-08-01T10:00:00+00:00",
                                        "assignments": [
                                            {
                                                "id": 505,
                                                "externalId": "ASSIGN-1",
                                                "employeeExternalId": "EMP-001",
                                                "employeeEmail": "user@company.ru",
                                                "courseId": 45,
                                                "courseName": "Onboarding",
                                                "status": "started",
                                                "statusCategory": "in_progress",
                                                "isOverdue": false,
                                                "completionPercent": 45.5,
                                                "score": null,
                                                "numberOfAttempts": 1,
                                                "isRequired": true,
                                                "assignedAt": "2026-08-01T10:00:00+00:00",
                                                "deadline": "2026-08-31T23:59:59+00:00",
                                                "startedAt": "2026-08-02T09:00:00+00:00",
                                                "completedAt": null,
                                                "lastActivityAt": "2026-08-02T09:30:00+00:00"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            },
            "patch": {
                "summary": "Изменить имя/теги; active=false — offboarding (отзыв назначений, выход из компании)",
                "tags": [
                    "Employees"
                ],
                "parameters": [
                    {
                        "name": "externalId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "requestBody": {
                    "content": {
                        "application/json": {
                            "example": {
                                "name": "Иван Иванов",
                                "tags": [
                                    "sales",
                                    "moscow"
                                ],
                                "active": true
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "employee | {status: offboarded}",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "id": 101,
                                        "externalId": "EMP-001",
                                        "email": "user@company.ru",
                                        "name": "Иван Иванов",
                                        "role": "employee",
                                        "tags": [
                                            "sales"
                                        ],
                                        "joinedAt": "2026-08-01T10:00:00+00:00"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            },
            "delete": {
                "summary": "Удалить сотрудника из компании с персональными данными (152-ФЗ): назначения удаляются, результаты обезличиваются",
                "tags": [
                    "Employees"
                ],
                "parameters": [
                    {
                        "name": "externalId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "deleted",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "externalId": "EMP-001",
                                        "status": "deleted"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/courses": {
            "get": {
                "summary": "Список курсов компании (включая срезы)",
                "tags": [
                    "Courses"
                ],
                "responses": {
                    "200": {
                        "description": "items",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "items": [
                                            {
                                                "id": 45,
                                                "name": "Onboarding",
                                                "externalId": null,
                                                "isAssessment": false
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/assignments": {
            "post": {
                "summary": "Назначить курс сотруднику (идемпотентно по externalId)",
                "tags": [
                    "Assignments"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "employeeExternalId": "EMP-001",
                                "courseId": 45,
                                "externalId": "ASSIGN-1",
                                "deadline": "2026-12-31T23:59:59Z",
                                "isRequired": true
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "assignment",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "id": 505,
                                        "externalId": "ASSIGN-1",
                                        "status": "assigned",
                                        "statusCategory": "not_started",
                                        "isOverdue": false,
                                        "assignedAt": "2026-08-01T10:00:00+00:00",
                                        "deadline": "2026-12-31T23:59:59+00:00"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            },
            "get": {
                "summary": "Список назначений",
                "tags": [
                    "Assignments"
                ],
                "parameters": [
                    {
                        "name": "employeeExternalId",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "enum": [
                                "assigned",
                                "started",
                                "completed",
                                "failed",
                                "needs_retry"
                            ]
                        }
                    },
                    {
                        "name": "courseId",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "updatedSince",
                        "in": "query",
                        "schema": {
                            "type": "string",
                            "format": "date-time"
                        }
                    },
                    {
                        "name": "page",
                        "in": "query",
                        "schema": {
                            "type": "integer"
                        }
                    },
                    {
                        "name": "limit",
                        "in": "query",
                        "schema": {
                            "type": "integer",
                            "maximum": 500
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "items + pagination",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "items": [
                                            {
                                                "id": 505,
                                                "externalId": "ASSIGN-1",
                                                "employeeExternalId": "EMP-001",
                                                "employeeEmail": "user@company.ru",
                                                "courseId": 45,
                                                "courseName": "Onboarding",
                                                "status": "started",
                                                "statusCategory": "in_progress",
                                                "isOverdue": false,
                                                "completionPercent": 45.5,
                                                "score": null,
                                                "numberOfAttempts": 1,
                                                "isRequired": true,
                                                "assignedAt": "2026-08-01T10:00:00+00:00",
                                                "deadline": "2026-08-31T23:59:59+00:00",
                                                "startedAt": "2026-08-02T09:00:00+00:00",
                                                "completedAt": null,
                                                "lastActivityAt": "2026-08-02T09:30:00+00:00"
                                            }
                                        ],
                                        "pagination": {
                                            "page": 1,
                                            "limit": 100,
                                            "total": 1,
                                            "pages": 1
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/assignments/bulk": {
            "post": {
                "summary": "Массовое назначение (до 500)",
                "tags": [
                    "Assignments"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "example": {
                                "items": [
                                    {
                                        "employeeExternalId": "EMP-001",
                                        "courseId": 45,
                                        "externalId": "ASSIGN-1",
                                        "deadline": "2026-12-31T23:59:59Z",
                                        "isRequired": true
                                    }
                                ]
                            }
                        }
                    }
                },
                "responses": {
                    "200": {
                        "description": "results per item",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "results": [
                                            {
                                                "index": 0,
                                                "ok": true,
                                                "assignmentId": 505,
                                                "status": "assigned"
                                            }
                                        ]
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/assignments/{id}": {
            "get": {
                "summary": "Назначение",
                "tags": [
                    "Assignments"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "assignment",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "id": 505,
                                        "externalId": "ASSIGN-1",
                                        "employeeExternalId": "EMP-001",
                                        "employeeEmail": "user@company.ru",
                                        "courseId": 45,
                                        "courseName": "Onboarding",
                                        "status": "started",
                                        "statusCategory": "in_progress",
                                        "isOverdue": false,
                                        "completionPercent": 45.5,
                                        "score": null,
                                        "numberOfAttempts": 1,
                                        "isRequired": true,
                                        "assignedAt": "2026-08-01T10:00:00+00:00",
                                        "deadline": "2026-08-31T23:59:59+00:00",
                                        "startedAt": "2026-08-02T09:00:00+00:00",
                                        "completedAt": null,
                                        "lastActivityAt": "2026-08-02T09:30:00+00:00"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            },
            "delete": {
                "summary": "Отозвать назначение",
                "tags": [
                    "Assignments"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "revoked",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "id": 505,
                                        "revoked": true
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/assignments/{id}/progress": {
            "get": {
                "summary": "Прогресс",
                "tags": [
                    "Assignments"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "progress",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "id": 505,
                                        "completionPercent": 45.5,
                                        "lastActivityAt": "2026-08-02T11:30:00+00:00",
                                        "status": "started",
                                        "statusCategory": "in_progress",
                                        "isOverdue": false
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/assignments/{id}/results": {
            "get": {
                "summary": "Результаты",
                "tags": [
                    "Assignments"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "integer"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "results",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "id": 505,
                                        "score": 85,
                                        "numberOfAttempts": 2,
                                        "status": "completed",
                                        "statusCategory": "completed",
                                        "completedAt": "2026-08-02T12:00:00+00:00",
                                        "resultSummary": {
                                            "completionState": "success",
                                            "isPassed": true,
                                            "finalScore": 85,
                                            "summary": "Completed with score 85%"
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/assignments/by-external-id/{externalId}": {
            "get": {
                "summary": "Назначение по externalId (также /progress, /results)",
                "tags": [
                    "Assignments"
                ],
                "parameters": [
                    {
                        "name": "externalId",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "assignment",
                        "content": {
                            "application/json": {
                                "example": {
                                    "result": "success",
                                    "data": {
                                        "id": 505,
                                        "externalId": "ASSIGN-1",
                                        "employeeExternalId": "EMP-001",
                                        "employeeEmail": "user@company.ru",
                                        "courseId": 45,
                                        "courseName": "Onboarding",
                                        "status": "started",
                                        "statusCategory": "in_progress",
                                        "isOverdue": false,
                                        "completionPercent": 45.5,
                                        "score": null,
                                        "numberOfAttempts": 1,
                                        "isRequired": true,
                                        "assignedAt": "2026-08-01T10:00:00+00:00",
                                        "deadline": "2026-08-31T23:59:59+00:00",
                                        "startedAt": "2026-08-02T09:00:00+00:00",
                                        "completedAt": null,
                                        "lastActivityAt": "2026-08-02T09:30:00+00:00"
                                    }
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/reports/assignments.csv": {
            "get": {
                "summary": "Отчёт по назначениям (CSV; также .xlsx)",
                "tags": [
                    "Reports"
                ],
                "parameters": [
                    {
                        "name": "status",
                        "in": "query",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "file"
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        },
        "/reports/employees.csv": {
            "get": {
                "summary": "Отчёт по сотрудникам (CSV; также .xlsx)",
                "tags": [
                    "Reports"
                ],
                "responses": {
                    "200": {
                        "description": "file"
                    },
                    "400": {
                        "description": "Validation / business error"
                    },
                    "401": {
                        "description": "Missing or invalid token"
                    },
                    "403": {
                        "description": "Scope or company mismatch"
                    },
                    "404": {
                        "description": "Not found"
                    },
                    "409": {
                        "description": "Idempotency conflict"
                    }
                }
            }
        }
    },
    "tags": [
        {
            "name": "Employees"
        },
        {
            "name": "Courses"
        },
        {
            "name": "Assignments"
        },
        {
            "name": "Reports"
        }
    ]
}