Импорт и экспорт

Все методы · Ключи и права · Ошибки

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

Для методов с ключом действуют общие проверки: 401 — ключ не принят, 403 — не хватает scope или прав владельца, 429 — превышен лимит. Неверные параметры могут дать 400, недоступный адресный ресурс — 404. Особенности команды указаны рядом с методом. Точную причину смотрите в error.code и details: как обработать ошибку и безопасно повторить запрос.

Создать настройку импорта

POST /api/v1/import-definitions

Действие ключа: imports:write. Оно не заменяет права владельца на объекты и поля.

Дополнительно import.manage. targetKind: object/user/group/organization. format: CSV/JSON; mode: CREATE_ONLY/UPDATE_ONLY/UPSERT. mapping: source,target, необязательные transform/precedence. resolver.externalIdField задаёт колонку внешнего идентификатора; без неё строки не пройдут импорт. externalId связывает строки с ранее импортированными записями одного источника.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/import-definitions HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "code": "sample-import",
  "name": "Учебная загрузка",
  "targetKind": "object",
  "targetTypeId": "TYPE_ID",
  "format": "CSV",
  "mode": "UPSERT",
  "sourceCode": "sample-source",
  "resolver": {
    "externalIdField": "externalId"
  },
  "mapping": [
    {
      "source": "subject",
      "target": "FIELD_CODE"
    }
  ]
}

Ответ и ошибки

Успех: 201. Определение импорта.

{
  "data": {
    "id": "DEFINITION_ID",
    "format": "CSV",
    "mode": "UPSERT"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Проверить или запустить импорт

POST /api/v1/imports/run

Действие ключа: imports:write. Оно не заменяет права владельца на объекты и поля.

Дополнительно import.execute. content — строка CSV либо JSON-массива; dryRun=true сначала. Каждая строка сохраняется независимо; частичные ошибки не откатывают остальные.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/imports/run HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "definitionId": "DEFINITION_ID",
  "content": "externalId,subject\nexternal-1,Пример",
  "dryRun": true
}

Ответ и ошибки

Успех: 201. Запуск с результатами строк.

{
  "data": {
    "id": "RUN_ID",
    "dryRun": true,
    "succeeded": 1,
    "failed": 0,
    "skipped": 0
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Прочитать результат импорта

GET /api/v1/import-runs/{runId}

Действие ключа: imports:read. Оно не заменяет права владельца на объекты и поля.

Дополнительно import.manage. Проверяйте failed/skipped и ошибки строк, а не только HTTP 200/201.

Параметры пути: runId. Тело: не требуется.

Пример запроса

GET /api/v1/import-runs/RUN_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Запуск с результатами строк.

{
  "data": {
    "id": "RUN_ID",
    "succeeded": 1,
    "failed": 0,
    "skipped": 0
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Выгрузить CSV или JSON

POST /api/v1/exports

Действие ключа: exports:read. Оно не заменяет права владельца на объекты и поля.

Дополнительно export.execute. format JSON/CSV; limit 1–10 000, default 1000; query необязателен. Ответ ограничен 16 MiB. HTTP-ответ не сообщает truncated: не считать его полной резервной копией.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/exports HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "typeDefinitionId": "TYPE_ID",
  "format": "JSON",
  "limit": 1000
}

Ответ и ошибки

Успех: 200. Файл JSON/CSV.

[]

JSON-тело свыше 10 MiB отклоняется с 413.

Выполнить пакет изменений

POST /api/v1/bulk

Действие ключа: objects:write. Оно не заменяет права владельца на объекты и поля.

operation: update/archive/transition; items 1–1000. Для transition: objectId,transitionId,expectedRevision,expectedStateId,values; archive: objectId,expectedRevision. Права проверяются для каждой записи; возможен частичный успех.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

POST /api/v1/bulk HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "operation": "update",
  "items": [
    {
      "objectId": "OBJECT_ID",
      "expectedRevision": 1,
      "changes": {
        "FIELD_CODE": "Значение"
      }
    }
  ]
}

Ответ и ошибки

Успех: 200. Массив результатов по элементам.

{
  "data": [
    {
      "objectId": "OBJECT_ID",
      "status": "SUCCEEDED",
      "revision": 2
    }
  ],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Связанные статьи

• Обзор API
• Права доступа
• Интеграции