🧾 Invoice Generator API

📚 API Documentation

Documentation

RESTful API for automatic invoice generation with sequential numbering and customizable templates. Built with .NET 10 and designed to be simple, flexible, and easy to implement.

---

🌟 Features

• ✨ Customizable templates with flexible format patterns
• 🔢 Automatic sequential numbering with leading zeros
• 💾 JSON storage with no database dependencies
• 🏗️ Clean layered architecture that's maintainable
• 📝 Structured logging with Serilog
• 🔄 Reset system to restart number sequences
• 🚀 Interactive documentation with Scalar
• 🆓 100% Open Source and free to use

---

🚀 Quick Start

Prerequisites

• .NET 10 SDK

Installation

1. Clone the repository

   git clone https://github.com/JSAcodev/InvoiceGenerator-API.git
   cd invoice-generator-api

2. Run the application

   cd InvoiceGenerator
   dotnet run

3. Access the API

   https://localhost:PORT
   http://localhost:PORT
   

4. Interactive documentation

   https://localhost:PORT/scalar/v1
   

---

📸 Screenshots

API Documentation (Scalar)

Interactive API documentation with all available endpoints

Creating a Template

Example of creating a custom invoice template

Generated Invoice

Example response when generating a new invoice

---

📚 Basic Usage

Create a Template

POST /invoice/newtemplate
Content-Type: application/json

{
  "name": "Invoice USA",
  "pattern": "USA-{year}{month}-{number:5}",
  "description": "Template for US market"
}

Generate an Invoice

POST /invoice/nextinvoice
Content-Type: application/json

{
  "id": "11571eff-5e2c-4a62-ba9a-098384d408d6"
}

Result:

USA-202512-00001
USA-202512-00002
USA-202512-00003
...

---

🎨 Available Patterns

Create your own invoice formats using these tokens:

Token	Description	Example
{year} or {yyyy}	Year (4 digits)	2025
{month} or {mm}	Month (2 digits)	12
{day} or {dd}	Day (2 digits)	25
{number:x}	Sequential number with x digits	{number:5} → 00001

Pattern Examples

"USA-{year}{month}-{number:3}"     →  USA-202512-001
"INV-{dd}-{number:15}"             →  INV-25-000000000000001
"FAC-{yyyy}-{mm}-{dd}-{number:4}"  →  FAC-2025-12-25-0001
"INVC-{yyyy}-USA-{number:6}"       →  INVC-2025-USA-000001

---

📡 API Endpoints

Method	Endpoint	Description
POST	/invoice/newtemplate	Create a new template
GET	/invoice/templates	Get all templates
GET	/invoice/template	Get a template by ID
POST	/invoice/nextinvoice	Generate next invoice
GET	/invoice/invoices	Get all invoices
GET	/invoice/invoice/{name}	Get last invoice by name
POST	/invoice/resettemplate	Reset template counter

---

🏗️ Architecture

The project follows a clean layered architecture:

┌─────────────────────┐
│   InvoiceGenerator  │  ← API Layer (Controllers, Middleware)
└─────────────────────┘
          ↓
┌─────────────────────┐
│      Business       │  ← Business Logic
└─────────────────────┘
          ↓
┌─────────────────────┐
│       Domain        │  ← Entities
└─────────────────────┘
          ↓
┌─────────────────────┐
│        Data         │  ← Repositories (JSON)
└─────────────────────┘

---

🛠️ Technologies

• .NET 10 - Main framework
• ASP.NET Core - REST API
• Mapster - Object mapping
• Serilog - Structured logging
• Scalar - Interactive documentation

---

📂 Project Structure

InvoiceGenerator/
├── Business/          # Business logic, DTOs, Services
├── Data/              # Repositories, Interfaces
├── Domain/            # Domain entities
└── InvoiceGenerator/  # API, Controllers, Middleware
    └── Storage/       # JSON files

---

💡 Use Cases

• 📊 Small businesses that need to generate simple invoices
• 👨‍💼 Freelancers for billing management
• 🏪 POS systems requiring automatic numbering
• 📦 E-commerce to generate unique order numbers
• 🧪 Educational projects to learn layered architecture

---

🌐 Resources

• 📖 API Documentation
• 🐛 Report an Issue

---

⭐ Support

If you find this project useful, consider giving it a star ⭐ on GitHub. Help other developers discover it!