Invoice System Backend Application

This Go Invoice System provides a RESTful API to manage invoices and customers efficiently. The API allows you to perform various operations, including creating invoices, managing customers, and generating PDF invoices.

---

Tech Stack

• Go: The primary programming language for the application.
• Chi Router: A lightweight and idiomatic router for building HTTP services in Go.
• Ent: An ORM for Go, providing powerful and easy-to-use database interaction tools.
• PostgreSQL with Neon: A serverless database built for modern applications.
• GoPDF Library: A library for generating PDF documents in Go.

---

How to Get Started

1. Clone the repository:

   git clone https://github.com/Tabintel/invoice-system.git
   cd invoice-system

   Create and .env in the root directory file and enter the values for:

   • DATABASE_URL=""
   • JWT_SECRET=""

2. Install dependencies:

   go mod tidy

3. Run the application:

   go run cmd/api/main.go

Base URL: http://localhost:8080

API Base URL deployed on Render: https://invoice-system-8zbx.onrender.com

---

Health Check

• Method: GET
• URL: http://localhost:8080/health
• Description: Verify that the server is running.
• Response:

  {
    "OK"
  }

---

Here is the list of 11 core endpoints, along with their payloads, responses, and usage.

1. Create Invoice

• Method: POST
• URL: http://localhost:8080/api/invoices
• Payload:

  {
    "customer_id": 1,
    "due_date": "2024-12-27T00:00:00Z",
    "currency": "USD",
    "items": [
      {
        "description": "Consulting Services",
        "quantity": 1,
        "rate": 1000.00
      }
    ]
  }

• Response:

  {
    "data": {
      "id": 1,
      "reference_number": "INV-20241127-7400",
      "total_amount": 1000,
      "status": "draft",
      "issue_date": "2024-11-27T18:08:30.2707774+01:00",
      "due_date": "2024-12-27T00:00:00Z",
      "currency": "USD",
      "created_at": "2024-11-27T18:08:30.2707774+01:00",
      "edges": {}
    },
    "status": "success"
  }

• Description: Create a new invoice.

2. List Invoices

• Method: GET
• URL: http://localhost:8080/api/invoices?status=draft
• Response:

  {
    "data": {
      "invoices": [
        {
          "id": 1,
          "reference_number": "INV-20241127-7400",
          "total_amount": 1000,
          "status": "draft",
          "issue_date": "2024-11-27T17:08:30.270777Z",
          "due_date": "2024-12-27T00:00:00Z",
          "currency": "USD",
          "created_at": "2024-11-27T17:08:30.270777Z",
          "edges": {}
        }
      ],
      "stats": {
        "total_paid": 0,
        "total_overdue": 0,
        "total_draft": 1,
        "total_unpaid": 0
      }
    },
    "status": "success"
  }

• Description: List all invoices with a specified status.

3. Update Invoice Status

• Method: PUT
• URL: http://localhost:8080/api/invoices/1/status
• Payload:

  {
    "status": "paid"
  }

• Response:

  {
    "data": {
      "id": 1,
      "reference_number": "INV-20241127-7400",
      "total_amount": 1000,
      "status": "paid",
      "issue_date": "2024-11-27T17:08:30.270777Z",
      "due_date": "2024-12-27T00:00:00Z",
      "currency": "USD",
      "created_at": "2024-11-27T17:08:30.270777Z",
      "edges": {}
    },
    "status": "success"
  }

• Description: Update the status of an invoice.

4. Create Customer

• Method: POST
• URL: http://localhost:8080/api/customers
• Payload:

  {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "address": "123 Business Street, City"
  }

• Response:

  {
    "data": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "address": "123 Business Street, City",
      "created_at": "2024-11-28T10:33:27.7360212+01:00"
    },
    "status": "success"
  }

• Description: Create a new customer.

5. List Customers

• Method: GET
• URL: http://localhost:8080/api/customers
• Response:

  {
    "data": [
      {
        "id": 2,
        "name": "Mary Doe",
        "email": "mary@example.com",
        "phone": "+12345678200",
        "address": "100 Bank Street, City",
        "created_at": "2024-11-28T10:04:20.716112Z"
      },
      {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "phone": "+1234567890",
        "address": "123 Business Street, City",
        "created_at": "2024-11-28T09:33:27.736021Z"
      }
    ],
    "status": "success"
  }

• Description: List all customers.

6. Get Single Customer

• Method: GET
• URL: http://localhost:8080/api/customers/1
• Response:

  {
    "data": {
      "id": 1,
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "address": "123 Business Street, City",
      "created_at": "2024-11-28T09:33:27.736021Z"
    },
    "status": "success"
  }

• Description: Get details of a single customer.

7. Update Customer

• Method: PUT
• URL: http://localhost:8080/api/customers/1
• Payload:

  {
    "name": "John Doe Updated",
    "email": "john.updated@example.com",
    "phone": "+1234567890",
    "address": "456 New Street, City"
  }

• Response:

  {
    "data": {
      "id": 1,
      "name": "John Doe Updated",
      "email": "john.updated@example.com",
      "phone": "+1234567890",
      "address": "456 New Street, City",
      "created_at": "2024-11-28T09:33:27.736021Z"
    },
    "status": "success"
  }

• Description: Update a customer's details.

8. Delete Customer

• Method: DELETE
• URL: http://localhost:8080/api/customers/2
• Response:

  {
    "message": "Customer deleted successfully",
    "status": "success"
  }

• Description: Delete a customer.

9. Generate Invoice PDF

• Method: GET
• URL: http://localhost:8080/api/invoices/1/pdf
• Description: Generate a PDF for an invoice. The browser will automatically download or display the PDF.

10. Generate Shareable Invoice Link

• Method: POST
• URL: http://localhost:8080/api/invoices/1/share
• Response:

  {
    "data": {
      "url": "http://localhost:8080/public/invoices/BFlyy-nWqNyK_t4uUqlVjzFNztojHff4mpSYQd8QEWU=",
      "expires_at": "2024-12-05T14:06:00.8490868+01:00"
    },
    "status": "success"
  }

• Description: Generate a shareable link for an invoice that can be shared with customers.

11. Invoice Statistics

• Method: GET
• URL: http://localhost:8080/api/invoices/stats
• Response:

  {
    "data": {
      "total_paid": 1,
      "total_overdue": 0,
      "total_draft": 2,
      "total_unpaid": 0
    },
    "status": "success"
  }

• Description: Get an overview of the invoice system's current state, including counts of paid, overdue, draft, and unpaid invoices.

---

Notes - Database ORM Updates

When adding new features or endpoints that interact with the database, run:

go generate ./ent

This command will update the database schema and generate the necessary database queries for interacting with the database.

---