Export records

Asynchronous export jobs and their status

INFO

Каждый ответ приходит в общем конверте — code, message, messages, status_code, time — а полезная нагрузка лежит в data. Таблицы ниже описывают содержимое data.

POST /export-records/create

Initiate an async export job for the specified page. The export runs in the background via BullMQ; poll get-by-id or get-paging to track progress. Returns the created record with state=pending.

Тело запроса

Поле	Тип	Обязательно	Описание
page_name	string	Да	Bito page identifier to export (e.g. trade, products, purchase, customers). Must match a registered PageNames value.
query_params	object	Да	Page-specific query parameters (filters, date range, etc.). Passed through to the per-page export cursor function after RBAC validation. Include ext_type ('xlsx' or 'csv') to control output format; defaults to xlsx.

{
  "page_name": "string",
  "query_params": {}
}

Ответ

Поле	Тип	Описание
_id	string	Export record ObjectId
account_id	string	Tenant identifier (equals boss ObjectId / dbName)
user_id	string	ObjectId of the user who initiated the export
file_name	string	Generated file name (e.g. trade-1718000000000.xlsx)
file_path	string	S3 / storage path to the exported file (available when state=completed)
page_name	string	Bito page identifier the export was requested for (e.g. trade, products, purchase)
state	string	Current state of the export job. Worker-driven: pending→in_progress→completed|failed. Caller-cancellable: pending|in_progress→canceled.. Допустимые значения: pending, in_progress, completed, failed, canceled
started_at	string (date-time)	Timestamp when the export record was created
completed_at	string (date-time)	Timestamp when the export reached a terminal state (completed, failed, or canceled)
progress	number	Export completion percentage (0–100). Set to 100 on completed.
query_params	object	The validated query parameters used for this export (page-specific shape)
user	object	Denormalized user data (available in get-paging list)
user.full_name	string
user.phone_number	string

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "_id": "string",
    "account_id": "string",
    "user_id": "string",
    "file_name": "string",
    "file_path": "string",
    "page_name": "string",
    "state": "pending",
    "started_at": "2025-05-01T12:00:00Z",
    "completed_at": "2025-05-01T12:00:00Z",
    "progress": 0,
    "query_params": {},
    "user": {
      "full_name": "string",
      "phone_number": "string"
    }
  },
  "time": "2025-05-01T12:00:00Z"
}

GET /export-records/get-by-id/{id}

Fetch a single export record by ObjectId. Use this to poll state/progress after create.

Параметры пути

Параметр	Тип	Обязательно	Описание
id	string	Да	Export record ObjectId

Тело запроса

Тело запроса не требуется.

Ответ

Структура ответа совпадает с POST /export-records/create.

POST /export-records/get-paging

Paginated list of export records for the authenticated tenant. Filterable by user_id, page_name, state, date range, and employee list. Includes $lookup user {full_name, phone_number}.

Тело запроса

Поле	Тип	Обязательно	Описание
page	number	Да	По умолчанию: 1
limit	number	Да	По умолчанию: 20
user_id	string	Нет	Filter by initiating user ObjectId
page_name	string	Нет	Filter by page name (e.g. trade, products)
state	string	Нет	Filter by export state. Допустимые значения: pending, in_progress, completed, failed, canceled
date_from	string (date)	Нет	Filter records created on or after this date (ISO 8601)
date_to	string (date)	Нет	Filter records created on or before this date (ISO 8601)
employees	string[]	Нет	Filter by a list of user ObjectIds (alternative to user_id for multi-user filtering)

{
  "page": 1,
  "limit": 20,
  "user_id": "string",
  "page_name": "string",
  "state": "pending",
  "date_from": "string",
  "date_to": "string",
  "employees": [
    "string"
  ]
}

Ответ

Поле	Тип	Описание
total	number
list	object[]
list[]._id	string	Export record ObjectId
list[].account_id	string	Tenant identifier (equals boss ObjectId / dbName)
list[].user_id	string	ObjectId of the user who initiated the export
list[].file_name	string	Generated file name (e.g. trade-1718000000000.xlsx)
list[].file_path	string	S3 / storage path to the exported file (available when state=completed)
list[].page_name	string	Bito page identifier the export was requested for (e.g. trade, products, purchase)
list[].state	string	Current state of the export job. Worker-driven: pending→in_progress→completed|failed. Caller-cancellable: pending|in_progress→canceled.. Допустимые значения: pending, in_progress, completed, failed, canceled
list[].started_at	string (date-time)	Timestamp when the export record was created
list[].completed_at	string (date-time)	Timestamp when the export reached a terminal state (completed, failed, or canceled)
list[].progress	number	Export completion percentage (0–100). Set to 100 on completed.
list[].query_params	object	The validated query parameters used for this export (page-specific shape)
list[].user	object	Denormalized user data (available in get-paging list)
list[].user.full_name	string
list[].user.phone_number	string

{
  "code": 0,
  "message": "Success",
  "status_code": 200,
  "data": {
    "total": 0,
    "list": [
      {
        "_id": "string",
        "account_id": "string",
        "user_id": "string",
        "file_name": "string",
        "file_path": "string",
        "page_name": "string",
        "state": "pending",
        "started_at": "2025-05-01T12:00:00Z",
        "completed_at": "2025-05-01T12:00:00Z",
        "progress": 0,
        "query_params": {},
        "user": {
          "full_name": null,
          "phone_number": null
        }
      }
    ]
  },
  "time": "2025-05-01T12:00:00Z"
}

PUT /export-records/set-state/{id}

Cancel a pending or in-progress export job. This is the only caller-driven state transition — only state=canceled is accepted. Worker-driven transitions (pending→in_progress→completed/failed) cannot be triggered via this endpoint.

Параметры пути

Параметр	Тип	Обязательно	Описание
id	string	Да	Export record ObjectId

Тело запроса

Поле	Тип	Обязательно	Описание
state	string	Да	Target state. Only 'canceled' is accepted via this endpoint. The record must currently be in 'pending' or 'in_progress' state; otherwise a WrongState error is returned.. Допустимые значения: canceled

{
  "state": "canceled"
}

Ответ

Структура ответа совпадает с POST /export-records/create.

---

Эта страница сгенерирована из спецификации OpenAPI.