Export records

Asynchronous export jobs and their status

INFO

Every response arrives in the shared envelope — code, message, messages, status_code, time — with the payload in data. The tables below describe what is inside 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.

Request body

Field	Type	Required	Description
page_name	string	Yes	Bito page identifier to export (e.g. trade, products, purchase, customers). Must match a registered PageNames value.
query_params	object	Yes	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": {}
}

Response

Field	Type	Description
_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.. One of: 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.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Export record ObjectId

Request body

No request body.

Response

Same response shape as 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}.

Request body

Field	Type	Required	Description
page	number	Yes	Default: 1
limit	number	Yes	Default: 20
user_id	string	No	Filter by initiating user ObjectId
page_name	string	No	Filter by page name (e.g. trade, products)
state	string	No	Filter by export state. One of: pending, in_progress, completed, failed, canceled
date_from	string (date)	No	Filter records created on or after this date (ISO 8601)
date_to	string (date)	No	Filter records created on or before this date (ISO 8601)
employees	string[]	No	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"
  ]
}

Response

Field	Type	Description
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.. One of: 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.

Path parameters

Parameter	Type	Required	Description
id	string	Yes	Export record ObjectId

Request body

Field	Type	Required	Description
state	string	Yes	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.. One of: canceled

{
  "state": "canceled"
}

Response

Same response shape as POST /export-records/create.

---

This page is generated from the OpenAPI spec.