diff --git a/reference/admin.yaml b/reference/admin.yaml index cf2c26c06..ebb6a3e44 100644 --- a/reference/admin.yaml +++ b/reference/admin.yaml @@ -6360,6 +6360,52 @@ components: type: string nullable: true example: report.created + time_interval_granularity: + type: string + nullable: false + enum: + - day + - month + - quarter + - year + description: | + The time duration by which to group expenses to aggregate sum of amount + example: month + total_amount: + type: number + nullable: false + description: | + Total sum of amount of expenses falling under filtering criteria + example: 990 + time_interval_marker: + type: string + nullable: false + description: > + Representation of a point in time for which the sum of amount of + expenses is calculated. + + Value depends of value of time_interval_granularity as follows : + + - for time_interval_granularity of `day`, value will be in date format + YYYY-MM-DD. Example : 2021-01-01 + + - for time_interval_granularity of `month`, value will be in date format + YYYY-MM. Example : 2021-01 + + - for time_interval_granularity of `quarter`, value will be in date + format YYYY-QQ. Example : 2021-Q1 + + - for time_interval_granularity of `year`, value will be in date format + YYYY. Example : 2021 + example: 2022-02 + spend_overview_summary_data_item: + type: object + nullable: false + properties: + amount: + $ref: '#/components/schemas/amount' + time_interval_marker: + $ref: '#/components/schemas/time_interval_marker' account_out: type: object additionalProperties: false @@ -6820,6 +6866,125 @@ components: example: 20 default: 50 maximum: 200 + time_interval_granularity: + in: query + name: time_interval_granularity + description: | + The time duration by which to group expenses to aggregate sum of amount. + Supported operator is `eq`. + schema: + type: string + default: month + enum: + - day + - month + - quarter + - year + example: eq.month + time_interval_preset: + in: query + name: time_interval_preset + description: > + Preset time durations which can be used to filter expenses by spend + date. + + Default value is used if it is not specified and time_interval_start and + time_interval_end params are also not specified. + + Supported operator is `eq`. + schema: + type: string + default: this_year + enum: + - this_week + - this_month + - this_quarter + - this_year + example: eq.this_year + time_interval_start: + in: query + name: time_interval_start + description: | + Start of time duration for filtering expenses by spend date. + Need not to be specified if time_interval_preset param is passed. + Supported operator is `eq`. + schema: + type: string + format: date-time + description: >- + Date-time in [ISO8601 + format](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14). + example: '2020-06-01T13:14:54.804+00:00' + time_interval_end: + in: query + name: time_interval_end + description: | + End of time duration for filtering expenses by spend date. + Need not to be specified if time_interval_preset param is passed. + Supported operator is `eq`. + schema: + type: string + format: date-time + description: >- + Date-time in [ISO8601 + format](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14). + example: '2021-06-01T13:14:54.804+00:00' + is_reimbursable: + in: query + name: is_reimbursable + description: > + For filtering out only those expenses which are reimbursable to the + employee. + + Supported operators are `eq`.
+ schema: + type: string + example: eq.true + merchants: + in: query + name: merchants + description: | + List of merchants for filtering expenses. + Supported operator is `in`. + schema: + type: string + example: in.(los-pollos-harmanos,saul-goodman) + category_ids: + in: query + name: category_ids + description: | + List of category IDs for filtering expenses. + Supported operator is `in`. + schema: + type: string + example: in.(cat123,cat345) + project_ids: + in: query + name: project_ids + description: | + List of project IDs for filtering expenses. + Supported operator is `in`. + schema: + type: string + example: in.(proj123,proj456) + department_ids: + in: query + name: department_ids + description: | + List of department IDs for filtering expenses. + Supported operator is `in`. + schema: + type: string + example: in.(dept123,dept345) + user_ids: + in: query + name: user_ids + description: | + List of user IDs for filtering expenses. + Supported operator is `in`. + schema: + type: string + example: in.(us123,us456) tags: - name: Accounting Exports description: > @@ -9737,6 +9902,60 @@ paths: application/json: schema: $ref: '#/components/schemas/401' + /admin/spend_overview/summary: + get: + tags: + - Spend Overview + summary: Spend Overview Summary + operationId: spend_overview_summary + description: > + API to return spend overview summary data. Data returned by this API can + be used to plot a time series graph depicting amount of spend over a + period of time.
+ + This API supports very rich filtering on all response fields and + pagination via query parameters. To understand how to use these + parameters, please see the [Guide to Data + APIs](https://docs.fylehq.com/docs/fyle-platform-docs/ZG9jOjI3Mzk2NTM3-guide-to-data-ap-is#filtering) + parameters: + - $ref: '#/components/parameters/time_interval_granularity' + - $ref: '#/components/parameters/time_interval_preset' + - $ref: '#/components/parameters/time_interval_start' + - $ref: '#/components/parameters/time_interval_end' + - $ref: '#/components/parameters/is_reimbursable' + - $ref: '#/components/parameters/merchants' + - $ref: '#/components/parameters/category_ids' + - $ref: '#/components/parameters/project_ids' + - $ref: '#/components/parameters/department_ids' + - $ref: '#/components/parameters/user_ids' + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + time_interval_granularity: + $ref: '#/components/schemas/time_interval_granularity' + total_amount: + $ref: '#/components/schemas/total_amount' + data: + type: array + items: + $ref: '#/components/schemas/spend_overview_summary_data_item' + '400': + description: Bad request + content: + application/json: + schema: + $ref: '#/components/schemas/400' + '401': + description: Unauthorized request + content: + application/json: + schema: + $ref: '#/components/schemas/401' /admin/accounts: get: tags: diff --git a/src/admin/openapi.yaml b/src/admin/openapi.yaml index 5b19cea88..5c5fa4d1e 100644 --- a/src/admin/openapi.yaml +++ b/src/admin/openapi.yaml @@ -224,6 +224,9 @@ paths: $ref: paths/admin@employee_account_summaries.yaml /admin/schedules: $ref: 'paths/admin@schedules.yaml' + /admin/spend_overview/summary: + $ref: 'paths/admin@spend_overview@summary.yaml' + /admin/accounts: $ref: 'paths/admin@accounts.yaml' /admin/tax_groups: diff --git a/src/admin/paths/admin@spend_overview@summary.yaml b/src/admin/paths/admin@spend_overview@summary.yaml new file mode 100644 index 000000000..eaf916ced --- /dev/null +++ b/src/admin/paths/admin@spend_overview@summary.yaml @@ -0,0 +1,49 @@ +get: + tags: + - Spend Overview + summary: Spend Overview Summary + operationId: spend_overview_summary + description: | + API to return spend overview summary data. Data returned by this API can be used to plot a time series graph depicting amount of spend over a period of time.
+ This API supports very rich filtering on all response fields and pagination via query parameters. To understand how to use these parameters, please see the [Guide to Data APIs](https://docs.fylehq.com/docs/fyle-platform-docs/ZG9jOjI3Mzk2NTM3-guide-to-data-ap-is#filtering) + parameters: + - $ref: ../../components/parameters/time_interval_granularity.yaml + - $ref: ../../components/parameters/time_interval_preset.yaml + - $ref: ../../components/parameters/time_interval_start.yaml + - $ref: ../../components/parameters/time_interval_end.yaml + # - $ref: ../../components/parameters/is_card_spend.yaml # will un-comment later when this filter is available + - $ref: ../../components/parameters/is_reimbursable.yaml + - $ref: ../../components/parameters/merchant.yaml + - $ref: ../../components/parameters/category_id.yaml + - $ref: ../../components/parameters/project_id.yaml + - $ref: ../../components/parameters/department_id.yaml + - $ref: ../../components/parameters/user_id.yaml + # - $ref: ../../components/parameters/card_id.yaml # will un-comment later when this filter is available + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + time_interval_granularity: + $ref: ../../components/schemas/fields.yaml#/time_interval_granularity + total_amount: + $ref: ../../components/schemas/fields.yaml#/total_amount + data: + type: array + items: + $ref: ../../components/schemas/fields.yaml#/spend_overview_summary_data_item + '400': + description: Bad request + content: + application/json: + schema: + $ref: ../../components/schemas/400.yaml + '401': + description: Unauthorized request + content: + application/json: + schema: + $ref: ../../components/schemas/401.yaml \ No newline at end of file diff --git a/src/components/parameters/card_id.yaml b/src/components/parameters/card_id.yaml new file mode 100644 index 000000000..210e3cb3a --- /dev/null +++ b/src/components/parameters/card_id.yaml @@ -0,0 +1,8 @@ +in: query +name: card_id +description: | + Corporate card IDs for filtering expenses. + Supported operator is `in`. +schema: + type: string + example: in.(bacc1234,bacc4567) diff --git a/src/components/parameters/category_id.yaml b/src/components/parameters/category_id.yaml new file mode 100644 index 000000000..60f61a127 --- /dev/null +++ b/src/components/parameters/category_id.yaml @@ -0,0 +1,8 @@ +in: query +name: category_id +description: | + Category IDs for filtering expenses. + Supported operator is `in`. +schema: + type: string + example: in.(cat123,cat345) diff --git a/src/components/parameters/department_id.yaml b/src/components/parameters/department_id.yaml new file mode 100644 index 000000000..22ce780fb --- /dev/null +++ b/src/components/parameters/department_id.yaml @@ -0,0 +1,8 @@ +in: query +name: department_id +description: | + Department IDs for filtering expenses. + Supported operator is `in`. +schema: + type: string + example: in.(dept123,dept345) diff --git a/src/components/parameters/is_card_spend.yaml b/src/components/parameters/is_card_spend.yaml new file mode 100644 index 000000000..32c2f9117 --- /dev/null +++ b/src/components/parameters/is_card_spend.yaml @@ -0,0 +1,8 @@ +in: query +name: is_card_spend +description: | + For filtering out only those expenses where source account is corporate card account + Supported operators are `eq`.
+schema: + type: string + example: eq.true diff --git a/src/components/parameters/is_reimbursable.yaml b/src/components/parameters/is_reimbursable.yaml new file mode 100644 index 000000000..c94396d45 --- /dev/null +++ b/src/components/parameters/is_reimbursable.yaml @@ -0,0 +1,8 @@ +in: query +name: is_reimbursable +description: | + For filtering out only those expenses which are reimbursable to the employee. + Supported operators are `eq`.
+schema: + type: string + example: eq.true diff --git a/src/components/parameters/merchant.yaml b/src/components/parameters/merchant.yaml new file mode 100644 index 000000000..dd213691b --- /dev/null +++ b/src/components/parameters/merchant.yaml @@ -0,0 +1,8 @@ +in: query +name: merchant +description: | + List of merchants for filtering expenses. + Supported operator is `in`. +schema: + type: string + example: in.(los-pollos-harmanos,saul-goodman) diff --git a/src/components/parameters/project_id.yaml b/src/components/parameters/project_id.yaml new file mode 100644 index 000000000..31cccb851 --- /dev/null +++ b/src/components/parameters/project_id.yaml @@ -0,0 +1,8 @@ +in: query +name: project_id +description: | + Project IDs for filtering expenses. + Supported operator is `in`. +schema: + type: string + example: in.(proj123,proj456) diff --git a/src/components/parameters/time_interval_end.yaml b/src/components/parameters/time_interval_end.yaml new file mode 100644 index 000000000..5faf6e436 --- /dev/null +++ b/src/components/parameters/time_interval_end.yaml @@ -0,0 +1,13 @@ + +in: query +name: time_interval_end +description: | + End of time duration for filtering expenses by spend date. + Need not to be specified if time_interval_preset param is passed. + Supported operator is `eq`. +schema: + type: string + format: date-time + description: + Date-time in [ISO8601 format](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14). + example: '2021-06-01T13:14:54.804+00:00' diff --git a/src/components/parameters/time_interval_granularity.yaml b/src/components/parameters/time_interval_granularity.yaml new file mode 100644 index 000000000..b2728d989 --- /dev/null +++ b/src/components/parameters/time_interval_granularity.yaml @@ -0,0 +1,16 @@ + +in: query +name: time_interval_granularity +description: | + The time duration by which to group expenses to aggregate sum of amount. + Supported operator is `eq`. +schema: + type: string + default: eq.month + enum: + - eq.day + - eq.month + - eq.quarter + - eq.year + example: eq.month + diff --git a/src/components/parameters/time_interval_preset.yaml b/src/components/parameters/time_interval_preset.yaml new file mode 100644 index 000000000..791e839e6 --- /dev/null +++ b/src/components/parameters/time_interval_preset.yaml @@ -0,0 +1,16 @@ + +in: query +name: time_interval_preset +description: | + Preset time durations which can be used to filter expenses by spend date. + Default value is used if it is not specified and time_interval_start and time_interval_end params are also not specified. + Supported operator is `eq`. +schema: + type: string + default: eq.this_year + enum: + - eq.this_week + - eq.this_month + - eq.this_quarter + - eq.this_year + example: eq.this_year diff --git a/src/components/parameters/time_interval_start.yaml b/src/components/parameters/time_interval_start.yaml new file mode 100644 index 000000000..28c4c5f1d --- /dev/null +++ b/src/components/parameters/time_interval_start.yaml @@ -0,0 +1,13 @@ + +in: query +name: time_interval_start +description: | + Start of time duration for filtering expenses by spend date. + Need not to be specified if time_interval_preset param is passed. + Supported operator is `eq`. +schema: + type: string + format: date-time + description: + Date-time in [ISO8601 format](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14). + example: '2020-06-01T13:14:54.804+00:00' diff --git a/src/components/parameters/user_id.yaml b/src/components/parameters/user_id.yaml new file mode 100644 index 000000000..b9df8f6af --- /dev/null +++ b/src/components/parameters/user_id.yaml @@ -0,0 +1,8 @@ +in: query +name: user_id +description: | + User IDs for filtering expenses. + Supported operator is `in`. +schema: + type: string + example: in.(us123,us456) diff --git a/src/components/schemas/fields.yaml b/src/components/schemas/fields.yaml index fdbbd4198..f4cedf77b 100644 --- a/src/components/schemas/fields.yaml +++ b/src/components/schemas/fields.yaml @@ -625,6 +625,47 @@ reminder_schedule_config: example: 42 description: minute of the hour +time_interval_granularity: + type: string + nullable: False + enum: + - day + - month + - quarter + - year + description: | + The time duration by which to group expenses to aggregate sum of amount + example: month + +total_amount: + type: number + nullable: False + description: | + Total sum of amount of expenses falling under filtering criteria + example: 990 + +time_interval_marker: + type: string + nullable: False + description: | + Representation of a point in time for which the sum of amount of expenses is calculated. + Value depends of value of time_interval_granularity as follows : + - for time_interval_granularity of `day`, value will be in date format YYYY-MM-DD. Example : 2021-01-01 + - for time_interval_granularity of `month`, value will be in date format YYYY-MM. Example : 2021-01 + - for time_interval_granularity of `quarter`, value will be in date format YYYY-QQ. Example : 2021-Q1 + - for time_interval_granularity of `year`, value will be in date format YYYY. Example : 2021 + example: 2022-02 + +spend_overview_summary_data_item: + type: object + nullable: False + properties: + amount: + $ref: './fields.yaml#/amount' + time_interval_marker: + $ref: './fields.yaml#/time_interval_marker' + + department_head_user_ids: type: array nullable: False