Ingest

POST /developer/v1/ingest/{source_type} принимает пачку записей из внешней системы и ставит её в асинхронную обработку. Область — ingest:write; она доступна только ключам супер-администраторов.

curl -X POST -H "X-API-Key: ddp_ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sync-2026-02-10-001" \
  https://app.doodocs.kz/api/developer/v1/ingest/KEDO \
  -d '{
    "payload_type": "EMPLOYEES",
    "create_missing": true,
    "records": [ { "external_id": "emp-1001", "…": "…" } ]
  }'

Заголовок Idempotency-Key обязателен. Повторная отправка с тем же ключом не создаёт вторую загрузку — вернётся ошибка «ingest request already exists». Меняете содержимое пачки — меняйте и ключ.

Источники и типы пейлоадов

`source_type`	`payload_type`	Что загружает
`KEDO`	`PERSONS`	Люди (идентификационные данные)
`KEDO`	`ORGANIZATIONS`	Юридические лица
`KEDO`	`DEPARTMENTS`	Подразделения
`KEDO`	`EMPLOYEES`	Сотрудники
`KEDO`	`JOB_TITLES`	Должности
`1C`	`EMPLOYEES_FULL`	Сотрудники вместе с физлицами (структуры 1С)
`1C`	`DEPARTMENTS`	Подразделения (структуры 1С)

Неизвестная пара источник/пейлоад не является ошибкой: запрос будет принят, а записи молча пропущены и учтены как «пропущенные» в журнале обработки. Проверяйте написание значений — опечатка не вернёт 400.

Сопоставление по `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, ИИН).

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

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

KEDO · PERSONS

Поле	Описание
`external_id`	Идентификатор человека в источнике (обязателен)
`first_name`, `last_name`, `middle_name`	ФИО
`gender`	Пол
`birth_date`, `birth_place`	Дата и место рождения
`iin`	ИИН
`number`, `serial_number`	Номер и серия документа, удостоверяющего личность
`issued_date`, `issuing_authority`, `issuing_authority_code`	Выдача документа
`registration_address`	Адрес регистрации
`citizenship`	Гражданство
`phone`, `email`	Контакты

KEDO · ORGANIZATIONS

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

KEDO · DEPARTMENTS

Поле	Описание
`external_id`	Идентификатор подразделения
`title`	Название
`external_organization_id`	Ссылка на юрлицо (его `external_id`)
`external_parent_id`	Родительское подразделение (опционально)

KEDO · EMPLOYEES

Поле	Описание
`external_id`	Идентификатор сотрудника
`number`	Табельный номер
`admission_date`	Дата приёма
`left_date`	Дата увольнения (опционально)
`available_vacation_day_count`	Остаток дней отпуска (опционально)
`external_person_id`	Ссылка на человека (`PERSONS.external_id`)
`external_organization_id`	Ссылка на юрлицо
`external_department_id`	Ссылка на подразделение
`external_job_title_id`	Ссылка на должность

KEDO · JOB_TITLES

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

1C · EMPLOYEES_FULL

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

Ответ и отслеживание обработки

{ "ingest_request_id": "8f4e…", "status": "ACCEPTED", "record_count": 120 }

Обработка асинхронная. Эндпоинта статуса по ingest_request_id сейчас нет — это ограничение preview. Практический способ убедиться в результате:

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

Обзор

Endpoints

Источники и типы пейлоадов

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

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

KEDO · PERSONS

KEDO · ORGANIZATIONS

KEDO · DEPARTMENTS

KEDO · EMPLOYEES

KEDO · JOB_TITLES

1C · EMPLOYEES_FULL

Ответ и отслеживание обработки

Дальше

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

Лимиты

​Источники и типы пейлоадов

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

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

​KEDO · PERSONS

​KEDO · ORGANIZATIONS

​KEDO · DEPARTMENTS

​KEDO · EMPLOYEES

​KEDO · JOB_TITLES

​1C · EMPLOYEES_FULL

​Ответ и отслеживание обработки

​Дальше

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

Лимиты

Источники и типы пейлоадов

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

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

KEDO · PERSONS

KEDO · ORGANIZATIONS

KEDO · DEPARTMENTS

KEDO · EMPLOYEES

KEDO · JOB_TITLES

1C · EMPLOYEES_FULL

Ответ и отслеживание обработки

Дальше