feat: Add API spec for `POST corporate_card_transactions/expenses/sta…

…ts` API (#583)

reference/spender.yaml

@@ -4878,6 +4878,75 @@ components:
         - last_user_matched_at
         - is_exported
         - metadata
+    corporate_card_transactions_expenses_stats_in:
+      type: object
+      properties:
+        query_params:
+          type: string
+          description: |
+            Query param string for filtering corporate card transactions.
+          nullable: false
+          example: created_at=gt.2024-01-01
+    corporate_card_transactions_expenses_stats_out:
+      type: array
+      description: |
+        Array containing stats objects grouped by corporate card numbers and expense state. Returns an empty array if no 
+        transactions are found matching the criteria.
+      items:
+        type: object
+        required:
+          - card_number
+          - bank_name
+          - state
+          - count
+          - total_amount
+        properties:
+          card_number:
+            type: string
+            nullable: false
+            description: |
+              Masked card number (showing first 6 and last 4 digits).
+            example: 411111******1111
+          bank_name:
+            type: string
+            nullable: false
+            description: |
+              Name of the bank that issued the card.
+            example: VISA_BANK
+          state:
+            type: string
+            nullable: false
+            description: |
+              State of the corporate card transactions.
+            example: COMPLETE
+          count:
+            type: integer
+            nullable: false
+            description: |
+              Number of transactions for this card number.
+            example: 7
+          total_amount:
+            type: number
+            nullable: false
+            description: |
+              Sum of transaction amounts for this card number.
+            example: 500.86
+      example:
+        - state: COMPLETE
+          bank_name: VISA_BANK
+          card_number: 411111******1111
+          count: 7
+          total_amount: 500.86
+        - state: COMPLETE
+          bank_name: MASTERCARD_BANK
+          card_number: 422222******2222
+          count: 3
+          total_amount: 3209.98
+        - state: DRAFT
+          bank_name: VISA_BANK
+          card_number: 444444******4444
+          count: 3
+          total_amount: 336.81
     corporate_card_transaction_id_in:
       type: object
       properties:
@@ -11028,6 +11097,61 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/401'
+  /spender/corporate_card_transactions/expenses/stats:
+    post:
+      tags:
+        - Corporate Card Transactions
+      summary: Get corporate card transactions expenses stats
+      description: |
+        Get stats of corporate card transaction expenses grouped by card number and expense state.
+      operationId: corporate_card_transactions_expenses_stats
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+                - data
+              properties:
+                data:
+                  $ref: '#/components/schemas/corporate_card_transactions_expenses_stats_in'
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                properties:
+                  data:
+                    $ref: '#/components/schemas/corporate_card_transactions_expenses_stats_out'
+        '400':
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/400'
+        '401':
+          description: Unauthorized request
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/401'
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/403'
+        '404':
+          description: Not Found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/404'
   /spender/corporate_card_transactions/mark_personal:
     post:
       tags:

src/components/schemas/corporate_card_transaction.yaml

@@ -2457,3 +2457,74 @@ corporate_card_transaction_reassign_in:
   required:
     - id
     - user_id
+
+corporate_card_transactions_expenses_stats_in:
+  type: object
+  properties:
+    query_params:
+      type: string
+      description: | 
+        Query param string for filtering corporate card transactions.
+      nullable: false
+      example: created_at=gt.2024-01-01
+
+corporate_card_transactions_expenses_stats_out:
+  type: array
+  description: |
+    Array containing stats objects grouped by corporate card numbers and expense state. Returns an empty array if no 
+    transactions are found matching the criteria.
+  items:
+    type: object
+    required:
+      - card_number
+      - bank_name
+      - state
+      - count
+      - total_amount
+    properties:
+      card_number:
+        type: string
+        nullable: false
+        description: |
+          Masked card number (showing first 6 and last 4 digits).
+        example: "411111******1111"
+      bank_name:
+        type: string
+        nullable: false
+        description: |
+          Name of the bank that issued the card.
+        example: "VISA_BANK"
+      state:
+        type: string
+        nullable: false
+        description: |
+          State of the corporate card transactions.
+        example: "COMPLETE"
+      count:
+        type: integer
+        nullable: false
+        description: |
+          Number of transactions for this card number.
+        example: 7
+      total_amount:
+        type: number
+        nullable: false
+        description: |
+          Sum of transaction amounts for this card number.
+        example: 500.86
+  example:
+    - state: "COMPLETE"
+      bank_name: "VISA_BANK"
+      card_number: "411111******1111"
+      count: 7
+      total_amount: 500.86
+    - state: "COMPLETE"
+      bank_name: "MASTERCARD_BANK"
+      card_number: "422222******2222"
+      count: 3
+      total_amount: 3209.98
+    - state: "DRAFT"
+      bank_name: "VISA_BANK"
+      card_number: "444444******4444"
+      count: 3
+      total_amount: 336.81

src/spender/openapi.yaml

@@ -178,7 +178,8 @@ paths:
     $ref: paths/spender@corporate_cards.yaml
   /spender/corporate_card_transactions:
     $ref: paths/spender@corporate_card_transactions.yaml
-
+  /spender/corporate_card_transactions/expenses/stats:
+    $ref: paths/spender@corporate_card_transactions@[email protected]
   /spender/corporate_card_transactions/mark_personal:
     $ref: paths/spender@corporate_card_transactions@mark_personal.yaml
 #  /spender/corporate_card_transactions/mark_personal/bulk:

src/spender/paths/spender@corporate_card_transactions@expenses@stats.yaml

@@ -0,0 +1,54 @@
+post:
+  tags:
+    - Corporate Card Transactions
+  summary: Get corporate card transactions expenses stats
+  description: |
+    Get stats of corporate card transaction expenses grouped by card number and expense state.
+  operationId: corporate_card_transactions_expenses_stats
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          additionalProperties: False
+          required:
+            - data
+          properties:
+            data:
+              $ref: '../../components/schemas/corporate_card_transaction.yaml#/corporate_card_transactions_expenses_stats_in'
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            type: object
+            additionalProperties: False
+            properties:
+              data:
+                $ref: '../../components/schemas/corporate_card_transaction.yaml#/corporate_card_transactions_expenses_stats_out'
+    '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
+    '403':
+      description: Forbidden
+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas/403.yaml
+    '404':
+      description: Not Found
+      content:
+        application/json:
+          schema:
+            $ref: '../../components/schemas/404.yaml'