> ## Documentation Index
> Fetch the complete documentation index at: https://platform.doodocs.kz/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest

> Массовая загрузка оргструктуры: источники, схемы записей, идемпотентность

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

```bash theme={null}
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", "…": "…" } ]
  }'
```

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

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

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

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

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

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

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

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

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

Поля не из схемы игнорируются. Даты — строки `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` — `Ссылка`,
`Наименование`, `Родитель.Ссылка`.

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

```json theme={null}
{ "ingest_request_id": "8f4e…", "status": "ACCEPTED", "record_count": 120 }
```

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

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

## Дальше

<Columns cols={2}>
  <Card title="Синхронизация сотрудников" icon="rotate" href="/ru/guides/recipes/sync-employees">
    Полная и инкрементальная выгрузка обратно.
  </Card>

  <Card title="Лимиты" icon="gauge" href="/ru/api-reference/limits">
    Частота запросов и размеры.
  </Card>
</Columns>