Invoices Management

The Invoices API allows you to manage invoices, including creation, updates, approvals, and deletion. This section details the various endpoints available for working with invoices.

Endpoints

1. List Invoices

Endpoint: GET /api/invoices

Description: Retrieves a list of invoices for the authenticated company, with optional filtering and pagination.

Request Parameters:

• company_id (optional): The company ID to filter invoices by. Defaults to the authenticated company's ID.

• transaction_id (optional): The transaction ID to filter invoices by.

• status (optional): Filter by invoice status (e.g., pending, paid).

• sort (optional): Sort the results (default is created_at).

• order (optional): The order of the results, either asc or desc (default is desc).

• per_page (optional): The number of results per page (default is 10).

Response:

jsonCopy code{
  "message": "Invoices retrieved successfully.",
  "invoices": [
    {
      "id": 101,
      "description": "Consulting services for Q3",
      "service_date": "2024-10-10",
      "provider_name": "ABC Consulting",
      "total_amount": "5000.00",
      "amount_requested": "4500.00",
      "status": "unpaid",
      "approval_status": "pending",
      "balance": "500.00",
      "category_name": "Consulting",
      "subcategory_name": "Business",
      "payment_method": "self",
      "transaction_id": "H360-XYZ123",
      "user_email": "[email protected]",
      "relationship_manager_email": "[email protected]",
      "finance_approver_email": null,
      "approved_by_manager_email": null,
      "comment": null
    }
  ]
}

---

2. Show Invoice Details

Endpoint: GET /api/invoices/{transaction_id}

Description: Retrieve the details of a specific invoice by its transaction ID.

Response:

jsonCopy code{
  "message": "Invoice retrieved successfully.",
  "invoice": {
    "id": 101,
    "description": "Consulting services for Q3",
    "service_date": "2024-10-10",
    "provider_name": "ABC Consulting",
    "total_amount": "5000.00",
    "amount_requested": "4500.00",
    "status": "unpaid",
    "approval_status": "pending",
    "balance": "500.00",
    "category_name": "Consulting",
    "subcategory_name": "Business",
    "payment_method": "self",
    "transaction_id": "H360-XYZ123",
    "user_email": "[email protected]",
    "relationship_manager_email": "[email protected]",
    "finance_approver_email": null,
    "approved_by_manager_email": null,
    "comment": null
  }
}

---

3. Create an Invoice

Endpoint: POST /api/invoices

Description: Creates a new invoice.

Request Body:

jsonCopy code{
  "company_id": 1,  // Optional
  "description": "Consulting services",
  "service_date": "2024-10-10",
  "total_amount": 5000,
  "amount_requested": 4500,
  "user_email": "[email protected]",
  "payment_method": "self",
  "provider_name": "ABC Consulting",
  "category_name": "Consulting",
  "subcategory_name": "Business"
}

Response:

jsonCopy code{
  "message": "Invoice created successfully",
  "invoice": {
    "id": 101,
    "description": "Consulting services",
    "service_date": "2024-10-10",
    "provider_name": "ABC Consulting",
    "total_amount": "5000.00",
    "amount_requested": "4500.00",
    "status": "unpaid",
    "approval_status": "pending",
    "balance": "500.00",
    "category_name": "Consulting",
    "subcategory_name": "Business",
    "payment_method": "self",
    "transaction_id": "H360-XYZ123",
    "user_email": "[email protected]",
    "relationship_manager_email": "[email protected]"
  }
}

---

4. Update an Invoice

Endpoint: PUT /api/invoices/{transaction_id}

Description: Updates an existing invoice by its transaction ID.

Request Body:

jsonCopy code{
  "total_amount": 6000,
  "amount_requested": 5500,
  "payment_method": "self",
  "provider_name": "XYZ Consulting",
  "category_name": "Consulting",
  "subcategory_name": "Strategy"
}

Response:

jsonCopy code{
  "message": "Invoice updated successfully",
  "invoice": {
    "id": 101,
    "description": "Consulting services",
    "service_date": "2024-10-10",
    "provider_name": "XYZ Consulting",
    "total_amount": "6000.00",
    "amount_requested": "5500.00",
    "status": "unpaid",
    "approval_status": "pending",
    "balance": "500.00",
    "category_name": "Consulting",
    "subcategory_name": "Strategy",
    "payment_method": "self",
    "transaction_id": "H360-XYZ123",
    "user_email": "[email protected]",
    "relationship_manager_email": "[email protected]"
  }
}

---

5. Approve an Invoice

Endpoint: PUT /api/invoices/{transaction_id}/approve

Description: Approves an invoice and optionally notifies the finance approver.

Request Body:

jsonCopy code{
  "manager_email": "[email protected]",
  "approvalAction": "approve",  // or "deny"
  "finance_approver_email": "[email protected]",
  "comment": "Approval comment",  // Optional
  "notify": true  // Optional flag to send notification
}

Response:

jsonCopy code{
  "message": "Invoice successfully updated.",
  "invoice": {
    "id": 101,
    "description": "Consulting services",
    "service_date": "2024-10-10",
    "provider_name": "ABC Consulting",
    "total_amount": "5000.00",
    "amount_requested": "4500.00",
    "status": "unpaid",
    "approval_status": "in progress",
    "balance": "500.00",
    "category_name": "Consulting",
    "subcategory_name": "Business",
    "payment_method": "self",
    "transaction_id": "H360-XYZ123",
    "user_email": "[email protected]",
    "relationship_manager_email": "[email protected]",
    "finance_approver_email": "[email protected]"
  }
}

---

6. Approve or Deny Finance Approval

Endpoint: PUT /api/invoices/{transaction_id}/finance-approve

Description: Approves or denies finance approval for an invoice.

Request Body:

{
  "finance_approved": true,  // or false
  "comment": "Finance approval comment",  // Required if finance_approved is false
  "notify": true  // Optional flag to send notification
}

Response:

{
  "message": "Finance approval completed.",
  "invoice": {
    "id": 101,
    "description": "Consulting services",
    "service_date": "2024-10-10",
    "provider_name": "ABC Consulting",
    "total_amount": "5000.00",
    "amount_requested": "4500.00",
    "status": "unpaid",
    "approval_status": "approved",
    "balance": "500.00",
    "category_name": "Consulting",
    "subcategory_name": "Business",
    "payment_method": "self",
    "transaction_id": "H360-XYZ123",
    "user_email": "[email protected]",
    "relationship_manager_email": "[email protected]",
    "finance_approver_email": "[email protected]"
  }
}

---

7. Delete an Invoice

Endpoint: DELETE /api/invoices/{transaction_id}/destroy

Description: Deletes an invoice if it has not been paid or partially paid.

Request Body:

{
  "user_email": "[email protected]"
}

Response:

{
  "message": "Invoice deleted successfully.",
  "transaction_id": "H360-XYZ123"
}

---

This documentation is structured for GitBook and can