Перейти к содержимому
AISARAISAR
REST API

Экспорт

Асинхронный экспорт данных компании — контактов (contacts), сообщений (messages) или сегментов (segments) — в формат CSV, XLSX или JSON. Создание ставит фоновую задачу в очередь и сразу возвращает объект экспорта в статусе pending, а готовый файл скачивается отдельным эндпоинтом. Вся группа доступна только на плане Business.

Доступ и права

Вся группа доступна только на плане Business (middleware feature:exports): без фичи любой запрос возвращает 403 { "error": "feature_not_available", "feature": "exports", "required_plan": "business" }. Просмотр (GET /exports, GET /exports/{id}) требует права export.view, создание (POST /exports) — права export.create. Список поддерживает пагинацию (page ≥ 1, perPage 5–100, по умолчанию 20).

Жизненный цикл экспорта

Создание ставит фоновую задачу в очередь и сразу возвращает объект экспорта в статусе pending (жизненный цикл pending → processing → completed/failed); готовность отслеживается через GET /exports/{id}, а файл скачивается по GET /exports/{id}/download — пока status != completed, этот эндпоинт отвечает 404. Ссылка download_url появляется только после перехода в completed и указывает на этот же download-эндпоинт.

Тело создания и фильтры

В теле создания type и format обязательны; необязательный объект filters сужает выборку полями account_type, segment_id, segment_ids[], date_from, date_to, channel_id, direction (inbound/outbound), conversation_id, group_chat_id.

Суточные лимиты

Действуют суточные лимиты на компанию: не более 20 экспортов любого типа в сутки и не более 5 экспортов типа messages; превышение любого из лимитов — 422 с ошибкой в поле type.

Эндпоинты

МетодПуть
GET/v1/exports

Список экспортов

POST/v1/exports

Создание экспорта

GET/v1/exports/{export}

Получение экспорта (статус, размер, кол-во строк)

GET/v1/exports/{export}/download

Скачивание готового файла экспорта

DELETE/v1/exports/{export}

Удаление экспорта

Примеры

Создание экспорта контактов

Запрос

bash
curl -X POST https://api.aisar.app/v1/exports \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "contacts",
    "format": "csv",
    "filters": { "segment_id": 12 }
  }'

Ответ

json
{
  "data": {
    "message": "Export started.",
    "export": {
      "id": 301,
      "uuid": "9f1c2e40-6b3a-4e9e-9d2a-1f7a8c0b5d21",
      "type": "contacts",
      "name": "Contacts export",
      "format": "csv",
      "status": "pending",
      "filters": { "segment_id": 12 },
      "row_count": null,
      "file_size": null,
      "error_message": null,
      "download_url": null,
      "expires_at": "2026-03-22T10:00:00.000000Z",
      "created_at": "2026-03-15T10:00:00.000000Z",
      "updated_at": "2026-03-15T10:00:00.000000Z"
    }
  }
}

Экспорт сообщений с фильтрами

Запрос

bash
curl -X POST https://api.aisar.app/v1/exports \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "messages",
    "format": "xlsx",
    "filters": {
      "channel_id": 7,
      "direction": "inbound",
      "date_from": "2026-03-01",
      "date_to": "2026-03-15"
    }
  }'

Ответ

json
{
  "data": {
    "message": "Export started.",
    "export": {
      "id": 302,
      "uuid": "3b8f1a20-7c4d-4a1e-8f6b-2e9c0d3a5b74",
      "type": "messages",
      "name": "Messages export",
      "format": "xlsx",
      "status": "pending",
      "filters": {
        "channel_id": 7,
        "direction": "inbound",
        "date_from": "2026-03-01",
        "date_to": "2026-03-15"
      },
      "row_count": null,
      "file_size": null,
      "error_message": null,
      "download_url": null,
      "expires_at": "2026-03-22T10:05:00.000000Z",
      "created_at": "2026-03-15T10:05:00.000000Z",
      "updated_at": "2026-03-15T10:05:00.000000Z"
    }
  }
}

Проверка статуса экспорта

Запрос

bash
curl https://api.aisar.app/v1/exports/301 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "data": {
    "export": {
      "id": 301,
      "uuid": "9f1c2e40-6b3a-4e9e-9d2a-1f7a8c0b5d21",
      "type": "contacts",
      "name": "Contacts export",
      "format": "csv",
      "status": "completed",
      "filters": { "segment_id": 12 },
      "row_count": 340,
      "file_size": 48213,
      "error_message": null,
      "download_url": "https://api.aisar.app/v1/exports/301/download",
      "expires_at": "2026-03-22T10:00:00.000000Z",
      "created_at": "2026-03-15T10:00:00.000000Z",
      "updated_at": "2026-03-15T10:02:31.000000Z"
    }
  }
}

Экспорт недоступен на текущем плане (403)

Запрос

bash
curl -X POST https://api.aisar.app/v1/exports \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "type": "contacts", "format": "csv" }'

Ответ

json
{
  "data": {
    "message": "Feature not available on your plan.",
    "error": "feature_not_available",
    "feature": "exports",
    "required_plan": "business"
  }
}