Ingest

POST /developer/v1/ingest/{source_type} принимает пачку записей из внешней системы (HRIS, расчётной системы или собственного справочника) и ставит её в асинхронную обработку. Один запрос несёт записи одного вида: юрлица, подразделения, должности, людей или сотрудников. Используйте его, чтобы наполнить тенант из другой системы и дальше держать его в актуальном состоянии. Повторная отправка записи с тем же external_id обновляет созданный ею объект.

Запрос

Часть	Значение
Метод и путь	`POST https://app.doodocs.kz/api/developer/v1/ingest/{source_type}`
`{source_type}`	`KEDO` — общая JSON-схема, описанная ниже; `1C` — структуры выгрузки 1С
`X-API-Key`	Ключ с областью `ingest:write`. Создаёт супер-администратор в Настройки → Интеграции → «Для разработчиков»
`Idempotency-Key`	Обязателен. Любая строка до 255 символов, уникальная для пачки (удобно: идентификатор запуска плюс порядковый номер)
`Content-Type`	`application/json`

Тело:

Поле	Тип	Описание
`payload_type`	строка, обязательно	Вид записей в пачке: `ORGANIZATIONS`, `DEPARTMENTS`, `JOB_TITLES`, `PERSONS` или `EMPLOYEES`
`create_missing`	boolean	`true` — создавать объекты для неизвестных `external_id`. `false` — только обновлять уже загруженные, остальные пропускать. По умолчанию `false`
`records`	массив объектов, обязательно	Записи в схеме выбранного `payload_type`. Каждая несёт `external_id`

Полный запрос, который загружает одного человека:

curl -X POST "https://app.doodocs.kz/api/developer/v1/ingest/KEDO" \
  -H "X-API-Key: ddp_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rippling-2026-09-18-persons-001" \
  -d '{
    "payload_type": "PERSONS",
    "create_missing": true,
    "records": [
      {
        "external_id": "rip-person-1",
        "first_name": "Куляш",
        "last_name": "Байсеитова",
        "middle_name": "",
        "iin": "950101300111",
        "email": "kulyash@keruen.kz",
        "phone": "+77011234567",
        "birth_date": "1990-05-02"
      }
    ]
  }'

Ответ 200:

{ "ingest_request_id": "01a0b436-d818-7408-963a-2de6d24484da", "status": "ACCEPTED", "record_count": 1 }

ACCEPTED означает, что пачка сохранена и поставлена в очередь. Применилась ли каждая запись, становится известно только после обработки, см. Результат.

Заголовок Idempotency-Key обязателен: без него ответ будет 400 с кодом INTEGRATION.IDEMPOTENCY_REQUIRED. Повторная отправка с тем же ключом не создаёт вторую загрузку — вернётся 409 с тем же кодом. Меняете содержимое пачки — меняйте и ключ.

Важно, кому принадлежит ключ

Пачка применяется от имени владельца ключа. Два следствия:

Ключ должен создать супер-администратор: область ingest:write доступна только ключам пользователей с правом PERMISSIONS:MANAGE.
Чтение результата через GET /employees ограничено профилем прав владельца. Создавайте ключ от администратора, чей профиль охватывает всю компанию, иначе в списке не будет части только что загруженных сотрудников, а владелец вовсе без профиля получит 400 METADATA.FIELD_NOT_VISIBLE.

Порядок загрузки

Ссылки между записями разрешаются по external_id, но не на всякий объект можно сослаться до его появления. Отправляйте пачки в таком порядке:

ORGANIZATIONS

Юрлица. На них ссылается всё остальное.

DEPARTMENTS

Родительское подразделение может быть в той же пачке или в более ранней.

JOB_TITLES

PERSONS

Людей нужно загрузить до сотрудников. Сотрудник, чей external_person_id ещё не загружен, отклоняется.

EMPLOYEES

Связывает человека с юрлицом, подразделением и должностью.

Подразделение, должность или юрлицо, на которое сослались раньше его собственной записи, создаётся пустой заготовкой и заполняется, когда придёт его пачка. У людей заготовки нет: человек — это аккаунт, который находится по ИИН. Пачки обрабатывают несколько воркеров одновременно, поэтому ACCEPTED на предыдущий запрос не означает, что он уже применён. Для ORGANIZATIONS, DEPARTMENTS и JOB_TITLES порядок прощают заготовки, а EMPLOYEES отправляйте только после того, как пачка PERSONS успела примениться (несколько секунд на сотню записей), и повторно отправляйте сотрудников, отклонённых из-за ещё не загруженного человека.

Сопоставление по `external_id`

Каждая запись несёт external_id — идентификатор объекта в вашей системе. Платформа хранит привязку external_id → внутренний id в разрезе source_type:

запись с уже известным external_id обновляет существующий объект;
запись с новым external_id создаёт объект, только если create_missing: true, иначе пропускается;
ссылки между записями (external_department_id, external_person_id и т.д.) тоже указываются внешними идентификаторами — платформа разрешает их сама.

Привязка external_id хранится на стороне платформы и не возвращается в GET /employees: у объекта Employee нет поля external_id, и фильтра по нему нет. Чтобы сверять данные после загрузки, храните соответствие на своей стороне либо используйте естественные ключи (табельный номер employee_number, ИИН).

Привязка — единственный ключ сопоставления. Человек или сотрудник, который уже был в тенанте до интеграции (заведён вручную или другим источником), по ИИН или табельному номеру не находится: запись с новым external_id попытается создать второго человека с тем же ИИН и будет отклонена. Начинайте интеграцию на тенанте, где сотрудники приходят только из этого источника, либо согласуйте перенос существующих записей с поддержкой.

Схемы записей

Поля не из схемы игнорируются. Даты — строки YYYY-MM-DD. Пустая строка считается «не задано».

ORGANIZATIONS

Поле	Обязательно	Описание
`external_id`	да	Идентификатор юрлица в источнике
`title`	да	Наименование
`bin`	да	БИН, 12 цифр
`legal_address`, `actual_address`		Юридический и фактический адреса
`bank_bik`, `bank_account`, `bank_name`		Банковские реквизиты

{
  "payload_type": "ORGANIZATIONS",
  "create_missing": true,
  "records": [
    { "external_id": "rip-org-1", "title": "ТОО «Керуен»", "bin": "123456789012", "legal_address": "Алматы, пр. Абая 1" }
  ]
}

DEPARTMENTS

Поле	Обязательно	Описание
`external_id`	да	Идентификатор подразделения
`title`	да	Название
`external_parent_id`		Родительское подразделение (`DEPARTMENTS.external_id`)
`external_organization_id`		Юрлицо (`ORGANIZATIONS.external_id`). Принимается на будущее; сегодня подразделения общие на тенант

{
  "payload_type": "DEPARTMENTS",
  "create_missing": true,
  "records": [
    { "external_id": "rip-dep-hr", "title": "HR", "external_organization_id": "rip-org-1" },
    { "external_id": "rip-dep-recruiting", "title": "Рекрутинг", "external_organization_id": "rip-org-1", "external_parent_id": "rip-dep-hr" }
  ]
}

JOB_TITLES

Поле	Обязательно	Описание
`external_id`	да	Идентификатор должности
`title`	да	Название

{
  "payload_type": "JOB_TITLES",
  "create_missing": true,
  "records": [ { "external_id": "rip-jt-engineer", "title": "Инженер" } ]
}

PERSONS

Человек — это личность за сотрудником. Загрузка человека создаёт или находит аккаунт платформы по ИИН; email становится логином этого аккаунта, если у него ещё нет логина.

Поле	Обязательно	Описание
`external_id`	да	Идентификатор человека в источнике
`iin`	да	ИИН, 12 цифр. Человек без ИИН отклоняется
`first_name`, `last_name`	да	Имя и фамилия
`middle_name`		Отчество
`email`		Личная почта. Приводится к нижнему регистру; для нового аккаунта становится логином
`phone`		Телефон в международном формате, например `+77011234567`
`birth_date`		Дата рождения

{
  "payload_type": "PERSONS",
  "create_missing": true,
  "records": [
    { "external_id": "rip-person-1", "first_name": "Куляш", "last_name": "Байсеитова", "iin": "950101300111", "email": "kulyash@keruen.kz", "phone": "+77011234567", "birth_date": "1990-05-02" },
    { "external_id": "rip-person-2", "first_name": "Каныш", "last_name": "Сатпаев", "middle_name": "Имантаевич", "iin": "960202400222", "email": "kanysh@keruen.kz" }
  ]
}

Поля документа, удостоверяющего личность (номер, орган выдачи, адрес регистрации, гражданство, пол), через ingest сегодня не загружаются. Если их прислать, они игнорируются; заполняйте их в приложении или дождитесь расширения схемы.

EMPLOYEES

Поле	Обязательно	Описание
`external_id`	да	Идентификатор сотрудника
`external_person_id`	да	Человек (`PERSONS.external_id`), должен быть уже загружен
`external_organization_id`	да	Юрлицо
`external_department_id`		Подразделение
`external_job_title_id`		Должность
`number`		Табельный номер
`admission_date`		Дата приёма. Становится `start_date`
`left_date`		Дата увольнения. Если указана, сотрудник создаётся или обновляется как `TERMINATED` с этой `end_date`

{
  "payload_type": "EMPLOYEES",
  "create_missing": true,
  "records": [
    { "external_id": "rip-emp-1", "number": "R-001", "admission_date": "2025-01-15", "external_person_id": "rip-person-1", "external_organization_id": "rip-org-1", "external_department_id": "rip-dep-hr", "external_job_title_id": "rip-jt-engineer" },
    { "external_id": "rip-emp-2", "number": "R-002", "admission_date": "2025-03-01", "left_date": "2026-03-31", "external_person_id": "rip-person-2", "external_organization_id": "rip-org-1", "external_department_id": "rip-dep-recruiting", "external_job_title_id": "rip-jt-engineer" }
  ]
}

Схема сотрудника сегодня не покрывает вид занятости, руководителя, рабочую почту и локацию — они остаются такими, как заданы в приложении. Восстановление уволенного сотрудника через ingest не поддерживается; делайте это в приложении.

1C · EMPLOYEES_FULL и DEPARTMENTS

При source_type = 1C записи идут в формате выгрузки 1С — сотрудник вместе с физлицом, поля на русском: ТабельныйНомер, ДатаПриема, Организация.Ссылка, Подразделение.Ссылка, Должность.Ссылка и вложенный объект ФизЛицо (Имя, Фамилия, Отчество, ИИН, Телефон, ДатаРождения). 1C · DEPARTMENTS — Ссылка, Наименование, Родитель.Ссылка. Для любой другой системы используйте общую схему KEDO.

Обновления и увольнения

Отправьте запись повторно с тем же external_id и новыми значениями. Всегда отправляйте запись целиком, а не только изменившиеся поля. Чтобы уволить сотрудника, пришлите его запись с left_date: сотрудник станет TERMINATED, а end_date заполнится.

Запись сотрудника без left_date применяется как ACTIVE. Если уволенного сотрудника прислать повторно без left_date (например, при полной пересинхронизации), он будет восстановлен. Держите left_date в каждой пачке, где есть уволенный сотрудник, либо не включайте уволенных в последующие пачки.

Удаление объектов через ingest не поддерживается.

Результат

Обработка асинхронная. По каждой пачке платформа ведёт журнал с четырьмя счётчиками:

Счётчик	Значение
`received`	Записей в пачке
`accepted`	Записей применено (создано или обновлено)
`skipped`	Записей с неизвестным `external_id` при `create_missing: false`
`failed`	Записей отклонено: нет `external_id` или ИИН, ссылка на незагруженного человека, ошибка валидации

Эндпоинта, который возвращает этот журнал или ошибки по записям для ingest_request_id, пока нет. Практический способ убедиться в результате:

Подождите обработку: пачки в сотни записей обрабатываются за секунды.
Перечитайте данные: GET /employees?updated_since=…&expand=person вернёт созданных и обновлённых сотрудников, GET /employees/{id} — одного.
Подпишитесь на вебхук employee.changed — каждая изменённая карточка придёт событием.

Отклонённые записи не останавливают пачку: остальное применяется. Исправьте отклонённые записи и пришлите их новой пачкой с новым Idempotency-Key.

Неизвестный payload_type или source_type не отклоняется: запрос принимается, а все записи считаются отклонёнными. Проверяйте написание значений — опечатка не вернёт 400.

Ошибки

HTTP	Код	Когда
`400`	`INTEGRATION.IDEMPOTENCY_REQUIRED`	Нет заголовка `Idempotency-Key`
`409`	`INTEGRATION.IDEMPOTENCY_REQUIRED`	Пачка с таким ключом уже принята
`401`	`INTEGRATION.API_KEY_INVALID`	Ключ не передан, отозван или истёк
`403`	`DEVELOPER.SCOPE_INSUFFICIENT`	У ключа нет области `ingest:write`
`429`		Превышен лимит запросов, см. Лимиты

Обзор

Endpoints

Запрос

Важно, кому принадлежит ключ

Порядок загрузки

Сопоставление по `external_id`

Схемы записей

ORGANIZATIONS

DEPARTMENTS

JOB_TITLES

PERSONS

EMPLOYEES

1C · EMPLOYEES_FULL и DEPARTMENTS

Обновления и увольнения

Результат

Ошибки

Дальше

Синхронизация сотрудников

Лимиты

​Запрос

​Важно, кому принадлежит ключ

​Порядок загрузки

​Сопоставление по external_id

​Схемы записей

​ORGANIZATIONS

​DEPARTMENTS

​JOB_TITLES

​PERSONS

​EMPLOYEES

​1C · EMPLOYEES_FULL и DEPARTMENTS

​Обновления и увольнения

​Результат

​Ошибки

​Дальше

Синхронизация сотрудников

Лимиты

Запрос

Важно, кому принадлежит ключ

Порядок загрузки

Сопоставление по `external_id`

Схемы записей

ORGANIZATIONS

DEPARTMENTS

JOB_TITLES

PERSONS

EMPLOYEES

1C · EMPLOYEES_FULL и DEPARTMENTS

Обновления и увольнения

Результат

Ошибки

Дальше