Reports
=======

Use this endpoint to manipulate and obtain details on Salesbox's Reports.

Base Endpoint
------------

.. code-block:: text

    https://segmentai.salesbox.com.br/api/reports

Get Report
---------

.. code-block:: text

    GET /api/reports/{id}

Get an individual Report by ID.

**HTTP Request**

``GET /api/reports/ID``

**Response**

``Expected Response Code: 200``

.. code-block:: json

    {
        "report": {
            "id": 1,
            "name": "Monthly Sales Overview",
            "description": "Overview of sales performance by month",
            "type": "sales",
            "isPublished": true,
            "schedule": "monthly",
            "lastRun": "2024-01-15T10:00:00+00:00",
            "nextRun": "2024-02-15T10:00:00+00:00",
            "createdAt": "2024-01-15T10:00:00+00:00",
            "modifiedAt": "2024-01-15T10:00:00+00:00",
            "createdBy": 1,
            "createdByUser": "John Smith",
            "modifiedBy": 1,
            "modifiedByUser": "John Smith",
            "filters": {
                "dateRange": "last_month",
                "salesTeam": "all",
                "products": ["all"]
            },
            "columns": [
                "date",
                "product",
                "revenue",
                "quantity",
                "salesperson"
            ]
        }
    }

**Report Properties**

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - ``id``
     - int
     - ID of the Report
   * - ``name``
     - string
     - Name of the Report
   * - ``description``
     - string/null
     - Description of the Report
   * - ``type``
     - string
     - Type of report (sales, marketing, etc)
   * - ``isPublished``
     - boolean
     - Whether the report is active
   * - ``schedule``
     - string
     - Report schedule (daily, weekly, monthly)
   * - ``lastRun``
     - datetime/null
     - Last time the report was run
   * - ``nextRun``
     - datetime/null
     - Next scheduled run time
   * - ``createdAt``
     - datetime
     - Report creation date/time
   * - ``modifiedAt``
     - datetime/null
     - Report last modified date/time
   * - ``createdBy``
     - int
     - ID of the User that created the Report
   * - ``createdByUser``
     - string
     - Name of the User that created the Report
   * - ``modifiedBy``
     - int
     - ID of the User that last modified the Report
   * - ``modifiedByUser``
     - string
     - Name of the User that last modified the Report
   * - ``filters``
     - object
     - Report filter settings
   * - ``columns``
     - array
     - List of columns to include

List Reports
-----------

.. code-block:: text

    GET /api/reports

Get a list of reports.

**Query Parameters**

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - ``search``
     - string
     - Text to search reports by
   * - ``page``
     - int
     - Which page to display
   * - ``limit``
     - int
     - How many records to return
   * - ``orderBy``
     - string
     - Column to sort by
   * - ``orderByDir``
     - string
     - Sort direction: asc or desc
   * - ``type``
     - string
     - Filter by report type
   * - ``isPublished``
     - boolean
     - Filter by published status

Create Report
------------

.. code-block:: text

    POST /api/reports/new

Create a new report.

**Request Body**

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Description
   * - ``name``
     - string
     - Report name
   * - ``description``
     - string
     - Report description
   * - ``type``
     - string
     - Report type
   * - ``isPublished``
     - boolean
     - Whether the report should be active
   * - ``schedule``
     - string
     - Report schedule
   * - ``filters``
     - object
     - Report filter settings
   * - ``columns``
     - array
     - List of columns to include

Edit Report
----------

.. code-block:: text

    PATCH /api/reports/{id}/edit

Edit an existing report.

**Request Body**

Same fields as Create Report.

Delete Report
------------

.. code-block:: text

    DELETE /api/reports/{id}/delete

Delete an existing report.

Run Report
---------

.. code-block:: text

    POST /api/reports/{id}/run

Run a report immediately.

**Response**

``Expected Response Code: 200``

.. code-block:: json

    {
        "status": "success",
        "message": "Report queued for processing",
        "jobId": "abc123"
    }

Get Report Results
---------------

.. code-block:: text

    GET /api/reports/{id}/results

Get the latest results for a report.

**Response**

``Expected Response Code: 200``

.. code-block:: json

    {
        "results": {
            "generatedAt": "2024-01-15T10:00:00+00:00",
            "data": [
                {
                    "date": "2024-01-01",
                    "product": "Product A",
                    "revenue": 1000.00,
                    "quantity": 5,
                    "salesperson": "Jane Doe"
                }
            ],
            "summary": {
                "totalRevenue": 1000.00,
                "totalQuantity": 5
            }
        }
    }