Синхронизация с HR-системой

​

Схема связей

• Департамент — подразделение школы; иерархия строится через parentId (parentExtId).
• Трудоустройство — центральная связка: пользователь + департамент + должность, плюс условия занятости (kind, type, rate).
• Руководитель департамента привязывается не к пользователю напрямую, а к его активному трудоустройству.
• Отсутствие (отпуск, больничный, командировка) тоже привязано к трудоустройству.

​

Порядок синхронизации

{ "name": "Отдел продаж", "extId": "ПОДР-001", "parentExtId": "ПОДР-000" }

​

Каким методом заводить сотрудника

• POST /user/create — создаёт нового. Если пользователь с таким логином (email/phone/domain), tgId или extId уже существует — вернётся ошибка (EmailIsBusy, PhoneIsBusy, DomainIsBusy, TgIdIsBusy, ExtIdIsBusy). Пароль (password) применяется.
• PUT /user/upsert — «создать или обновить» за один вызов. Ищет существующего по логину / tgId / extId: найден → обновляет, нет → создаёт. Идемпотентен — повторная выгрузка того же сотрудника не создаёт дубль и не падает.
• PUT /user/ext/{extId}/update (или PUT /user/{userId}/update) — только обновляет существующего. Если пользователя нет — NotFound (создания не будет). Пароль этим методом не задаётся.

• Пароль вы не задаёте (генерируете и рассылаете на нашей стороне или он не нужен) → берите upsert: один вызов, идемпотентно, проще всего для регулярной синхронизации.
• Пароль задаёте вы (например, детерминированный «имя+фамилия+год») → заводите новых через create (там пароль точно применится), а существующих обновляйте через update. Типовой паттерн: update по extId → при NotFound → create (всё адресуется по extId, внутренние ID Exode не нужны). Через upsert так не выйдет: если пользователь уже есть, upsert уйдёт в обновление и заданный вами пароль не применится.

​

Поведение назначений employments

• Повтор той же пары департамент + должность — безопасный no-op. Слать одно и то же назначение при каждом синке можно — дубль не создастся.
• Новая пара — это новое назначение (совместительство), а не перевод. Если сотрудника в 1С перевели и вы пришлёте в employments новую пару, у него станет два активных назначения (старое и новое), а не одно.
• Отсутствие назначения в массиве ≠ увольнение. Не пришли назначение — с ним ничего не произойдёт, оно останется активным. Убрать его можно только явным terminate.

​

Жизненный цикл статуса пользователя

• Увольнение с последнего активного трудоустройства (employment/terminate) автоматически переводит пользователя в Terminated: вход запрещён, все сессии завершаются. Повторный наём (hire) сотрудника со статусом Terminated автоматически возвращает Active. Нельзя уволить с последнего назначения самого себя (StaffCannotTerminateSelf) или владельца школы (StaffCannotTerminateSchoolOwner).
• Блокировка админом — user/update { "status": "Blocked" }: вход закрыт, сессии завершаются, новые зачисления на продукты запрещены; данные сохраняются и видны в отчётах. { "status": "Active" } снимает блокировку. Владельца школы заблокировать нельзя.
• OnLeave управляется модулем отсутствий: при действующем отсутствии (отпуск/больничный) статус автоматически становится OnLeave, по завершении — возвращается в Active. OnLeave информационный — вход остаётся доступен, вручную его ставить не нужно.
• Бан и разбан — user/update { "status": "Banned" } закрывает доступ. При снятии бана (передайте Active) фактический статус пересчитывается автоматически по трудоустройствам и отсутствиям: уволенный вернётся в Terminated, находящийся в отпуске — в OnLeave, остальные — в Active.

​

Маппинг типовых полей

{
  "email": "[email protected]",         // ← email. Поле для входа (логин)
  "phone": "+998901234567",             // ← телефон, межд. формат. Поле для входа (логин)
  "domain": "i.ivanov.01011990",        // ← ваш логин. ВХОД ВЫПОЛНЯЕТСЯ ПО НЕМУ. Латиница/цифры/_/точки-разделители,
                                        //   ≤65, уникален в школе. Нельзя одни цифры или вид id123
  "extId": "i.ivanov.01011990",         // ← GUID/внешний ID из вашей системы. Ключ синхронизации, НЕ логин
  "password": "SecurePass123",          // ← если не передать и есть email/телефон — сгенерируем и отправим сами.
                                        //   Применяется только при СОЗДАНИИ (см. create vs upsert ниже)
  "status": "Active",                   // ← «Работает» → Active. «Уволен» — не здесь, а через employment/terminate
  "profile": {
    "firstName": "Иван",                // ← имя. ≤15 символов, буквы/пробелы/апострофы
    "lastName": "Иванов",               // ← фамилия. ≤15 символов, буквы/пробелы/апострофы
                                        // ← отчество — отдельного поля НЕТ → в кастомное поле
    "bdate": "1990-01-01",              // ← дата рождения. ISO datetime → только дата YYYY-MM-DD
    "sex": "Men",                       // ← пол: «м» → Men, «ж» → Women
    "role": "Student"                   // ← роль: Student / Tutor / Parent
  },
  "extra": {
    "staff": {
      "employments": [                  // ← 1..10 трудоустройств (несколько = совместительство)
        {
          "departmentExtId": "ПОДР-001",                           // ← код подразделения (создайте заранее)
          "positionExtId": "e3b0c442-98fc-4b39-96f7-9c2a4d001a01", // ← GUID должности (создайте заранее). Имя — не ключ
          "kind": "Main",                                          // ← Main; доп. — InternalSecondary/ExternalSecondary
          "startAt": "2020-03-01T00:00:00Z"                        // ← дата приёма/назначения (ISO 8601)
        }
      ]
    }
  }
}

• Отчество, город, теги, произвольный статус из CRM, доп. email → кастомные поля (custom-field/value/set-by-slug после создания/апсерта пользователя).
• Руководители (leader_external_ids) → отдельный вызов staff/department-manager/set (departmentExtId + employmentExtId).
• Роль/теги без аналога — игнорируются.

​

Ограничения, о которых стоит знать заранее

​

Минимальный пример: сотрудник с трудоустройством

curl --location --request PUT 'https://api.exode.biz/saas/v2/user/upsert' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --data-raw '{
    "email": "[email protected]",
    "domain": "i.ivanov.01011990",
    "extId": "i.ivanov.01011990",
    "status": "Active",
    "profile": {
      "firstName": "Иван",
      "lastName": "Иванов",
      "bdate": "1990-01-01",
      "sex": "Men"
    },
    "extra": {
      "staff": {
        "employments": [
          {
            "positionExtId": "manager",
            "departmentExtId": "ПОДР-001",
            "kind": "Main",
            "type": "FullTime",
            "startAt": "2020-03-01T00:00:00Z"
          }
        ]
      }
    }
  }'

curl --location 'https://api.exode.biz/saas/v2/form/custom-field/value/set-by-slug' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --data-raw '{
    "userId": 1683,
    "layoutId": 12,
    "values": [
      { "slug": "middle_name", "value": "Иванович" },
      { "slug": "city", "value": "Ташкент" },
      { "slug": "crm_status", "value": "Работает" }
    ]
  }'