InfraNotes Invoice System - Complete Frontend Implementation Guide

Table of Contents

1. System Overview
2. Authentication
3. Core Invoice Management
4. Client Management
5. Invoice Templates
6. Payment Processing
7. Advanced Features
8. Bulk Operations
9. Public Invoice Access
10. Approval Workflows
11. Integration Guidelines
12. Error Handling

System Overview

The InfraNotes Invoice System is a comprehensive enterprise-grade invoicing platform with the following key capabilities:

Core Components

• Invoice Management: Full CRUD operations with status tracking
• Client Management: Complete client/vendor database with contact management
• Payment Processing: Multi-gateway payment integration
• Template System: Customizable invoice templates with recurring functionality
• Approval Workflows: Multi-step approval processes
• Bulk Operations: Batch processing for multiple invoices
• Public Access: Secure public invoice links with analytics
• Late Fee Management: Automated late fee calculation and application
• Reminder System: Automated email reminders with customizable templates

Base URLs

The system supports multiple API versions and endpoint patterns:

# Legacy routes (still supported)
http://localhost:8080/api

# V1 routes (recommended)
http://localhost:8080/api/v1

# Specific service routes
http://localhost:8080/api/v1/late-fees
http://localhost:8080/api/v1/public/invoices (no auth)
http://localhost:8080/api/v1/admin/public-invoices (auth required)

Authentication

All endpoints require JWT authentication via Authorization: Bearer <token> header unless otherwise specified (public invoice access endpoints are exempt).

Required Headers

{
  "Authorization": "Bearer <jwt_token>",
  "Content-Type": "application/json"
}

Core Invoice Management

1. Invoice CRUD Operations

Note: The system supports both legacy and v1 endpoints for backward compatibility.

Create Invoice

Endpoints:

• POST /api/invoices (legacy)
• POST /api/v1/invoices (recommended)

Purpose: Create a new invoice with line items and automatic calculations

Request Body:

{
  "client_id": 123,
  "issue_date": "2025-01-15T00:00:00Z",
  "due_date": "2025-02-15T00:00:00Z",
  "currency": "USD",
  "payment_terms_id": 1,
  "notes": "Monthly service invoice",
  "terms": "Net 30",
  "items": [
    {
      "description": "Web Development Services",
      "quantity": 40,
      "unit_price": 100.00,
      "tax_rate": 8.5
    }
  ]
}

Response: Created invoice with auto-calculated totals and generated invoice number

Get Invoice

Endpoints:

• GET /api/invoices/{id} (legacy)
• GET /api/v1/invoices/{id} (recommended)

Purpose: Retrieve complete invoice details

Response: Invoice object with items, payments, and client information

Update Invoice

Endpoints:

• PUT /api/invoices/{id} (legacy)
• PUT /api/v1/invoices/{id} (recommended)

Purpose: Update existing invoice with validation

Request Body: Same as create invoice structure

Delete Invoice

Endpoints:

• DELETE /api/invoices/{id} (legacy)
• DELETE /api/v1/invoices/{id} (recommended)

Purpose: Delete invoice and all associated data

List Invoices

Endpoints:

• GET /api/invoices (legacy)
• GET /api/v1/invoices (recommended)

Purpose: List invoices with comprehensive filtering

Query Parameters:

• status: Filter by status (draft, sent, paid, overdue, etc.)
• client_id: Filter by client
• start_date, end_date: Date range filter
• min_amount, max_amount: Amount range filter
• is_overdue: Filter overdue invoices
• limit, offset: Pagination

2. Invoice Items Management

Note: Invoice items management is only available on v1 endpoints.

Add Invoice Item

Endpoint: POST /api/v1/invoices/{id}/items
Request Body:

{
  "description": "Additional service",
  "quantity": 5,
  "unit_price": 50.00,
  "tax_rate": 8.5
}

Update Invoice Item

Endpoint: PUT /api/v1/invoices/{id}/items/{item_id}

Delete Invoice Item

Endpoint: DELETE /api/v1/invoices/{id}/items/{item_id}

3. Invoice Status Management

Update Status

Endpoint: PUT /api/v1/invoices/{id}/status
Request Body:

{
  "status": "sent",
  "notes": "Invoice sent to client"
}

Get Status History

Endpoint: GET /api/v1/invoices/{id}/status/history
Response: Complete status change history with timestamps

Get Status Metadata

Endpoint: GET /api/v1/invoice-statuses
Response: Available invoice statuses and their metadata

Process Overdue Invoices

Endpoint: POST /api/v1/invoices/process-overdue
Response: Result of processing overdue invoices

4. Invoice Operations

Generate PDF

Endpoints:

• GET /api/invoices/{id}/pdf (legacy)
• GET /api/v1/invoices/{id}/pdf (recommended)

Response: PDF file or download link

Send Invoice

Endpoints:

• POST /api/invoices/{id}/send (legacy)
• POST /api/v1/invoices/{id}/send (recommended)

Request Body:

{
  "email_text": "Please find attached invoice"
}

Generate from Expenses

Endpoint: POST /api/v1/invoices/generate-from-expenses
Request Body:

{
  "client_id": 123,
  "expense_ids": [1, 2, 3],
  "markup_percentage": 10
}

Get Communications

Endpoint: GET /api/v1/invoices/{id}/communications
Response: Communication history for the invoice

Client Management

1. Client CRUD Operations

Create Client

Endpoint: POST /clients
Request Body:

{
  "type": "client",
  "name": "Acme Corporation",
  "email": "billing@acme.com",
  "phone": "+1234567890",
  "address": "123 Business St",
  "city": "New York",
  "country": "USA",
  "default_currency": "USD",
  "payment_terms_id": 1
}

Get Client

Endpoint: GET /clients/{id}

Update Client

Endpoint: PUT /clients/{id}

Delete Client

Endpoint: DELETE /clients/{id}

List Clients

Endpoint: GET /clients
Query Parameters: type, country, limit, offset

2. Contact Person Management

List Contact Persons

Endpoint: GET /clients/{client_id}/contacts

Create Contact Person

Endpoint: POST /contacts
Request Body:

{
  "client_id": 123,
  "name": "John Doe",
  "position": "Accounting Manager",
  "email": "john@acme.com",
  "phone": "+1234567890",
  "is_primary": true
}

Update Contact Person

Endpoint: PUT /contacts/{id}

Delete Contact Person

Endpoint: DELETE /contacts/{id}

Set Primary Contact

Endpoint: PUT /contacts/{id}/primary

3. Client Communication

Create Communication

Endpoint: POST /clients/communications
Request Body:

{
  "client_id": 123,
  "type": "email",
  "subject": "Invoice Follow-up",
  "content": "Following up on invoice payment",
  "direction": "outbound"
}

Get Communication History

Endpoint: GET /clients/{client_id}/communications

Invoice Templates

1. Template Management

Create Template

Endpoint: POST /invoice-templates
Request Body:

{
  "name": "Monthly Service Template",
  "description": "Standard monthly service invoice",
  "is_recurring": true,
  "frequency": "monthly",
  "auto_send": false,
  "client_id": 123,
  "items": [
    {
      "description": "Monthly Service Fee",
      "quantity": 1,
      "unit_price": 1000.00
    }
  ]
}

Get Template

Endpoint: GET /invoice-templates/{id}

Update Template

Endpoint: PUT /invoice-templates/{id}

Delete Template

Endpoint: DELETE /invoice-templates/{id}

List Templates

Endpoint: GET /invoice-templates

Generate Invoice from Template

Endpoint: POST /invoice-templates/{id}/generate
Request Body:

{
  "issue_date": "2025-01-15T00:00:00Z",
  "due_date": "2025-02-15T00:00:00Z",
  "custom_variables": {
    "project_name": "Website Development"
  }
}

2. Line Item Templates

Create Line Item Template

Endpoint: POST /line-item-templates
Request Body:

{
  "name": "Web Development Hour",
  "description": "Web development services (per hour)",
  "unit_price": 100.00,
  "category": "Development",
  "is_active": true
}

Apply Templates to Invoice

Endpoint: POST /api/v1/invoices/{id}/apply-templates
Request Body:

{
  "template_ids": [1, 2, 3],
  "quantities": [10, 5, 1]
}

List Line Item Templates

Endpoint: GET /api/v1/line-item-templates

Create Line Item Template

Endpoint: POST /api/v1/line-item-templates

Get Line Item Template

Endpoint: GET /api/v1/line-item-templates/{id}

Update Line Item Template

Endpoint: PUT /api/v1/line-item-templates/{id}

Delete Line Item Template

Endpoint: DELETE /api/v1/line-item-templates/{id}

Get Popular Templates

Endpoint: GET /api/v1/line-item-templates/popular

Get Default Templates

Endpoint: GET /api/v1/line-item-templates/default

Get Templates by Category

Endpoint: GET /api/v1/line-item-templates/category/{category}

3. Recurring Invoices

Create Recurring Invoice

Endpoint: POST /recurring-invoices
Request Body:

{
  "template_id": 123,
  "client_id": 456,
  "frequency": "monthly",
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-12-31T23:59:59Z",
  "auto_send": true
}

Get Scheduler Status

Endpoint: GET /recurring-invoices/scheduler/status

Run Scheduler Manually

Endpoint: POST /recurring-invoices/scheduler/run

4. Invoice Number Formats

List Invoice Number Formats

Endpoint: GET /api/v1/invoice-number-formats

Create Invoice Number Format

Endpoint: POST /api/v1/invoice-number-formats

Get Invoice Number Format

Endpoint: GET /api/v1/invoice-number-formats/{id}

Update Invoice Number Format

Endpoint: PUT /api/v1/invoice-number-formats/{id}

Delete Invoice Number Format

Endpoint: DELETE /api/v1/invoice-number-formats/{id}

Set Default Format

Endpoint: PUT /api/v1/invoice-number-formats/{id}/default

Generate Preview

Endpoint: GET /api/v1/invoice-number-formats/{id}/preview

5. Invoice Templates (Complete CRUD)

Create Invoice Template

Endpoint: POST /api/v1/invoice-templates

List Invoice Templates

Endpoint: GET /api/v1/invoice-templates

Get Invoice Template

Endpoint: GET /api/v1/invoice-templates/{id}

Update Invoice Template

Endpoint: PUT /api/v1/invoice-templates/{id}

Delete Invoice Template

Endpoint: DELETE /api/v1/invoice-templates/{id}

Generate Invoice from Template

Endpoint: POST /api/v1/invoice-templates/{id}/generate-invoice

Payment Processing

1. Payment Management

Add Payment

Endpoint: POST /api/v1/invoices/{id}/payments
Request Body:

{
  "amount": 1000.00,
  "payment_method": "credit_card",
  "payment_date": "2025-01-15T00:00:00Z",
  "transaction_id": "TXN123456",
  "notes": "Payment via Stripe"
}

Get Payments

Endpoint: GET /api/v1/invoices/{id}/payments

Get Specific Payment

Endpoint: GET /api/v1/invoice-payments/{id}

Update Payment

Endpoint: PUT /api/v1/invoice-payments/{id}

Delete Payment

Endpoint: DELETE /api/v1/invoice-payments/{id}

2. Payment Gateways

Configure Gateway

Endpoint: POST /payment-gateways
Request Body:

{
  "name": "Stripe",
  "type": "stripe",
  "is_active": true,
  "configuration": {
    "publishable_key": "pk_test_...",
    "secret_key": "sk_test_...",
    "webhook_endpoint": "https://api.example.com/webhooks/stripe"
  }
}

Process Payment

Endpoint: POST /payment-gateways/{id}/process

3. Payment Reconciliation

Import Bank Statement

Endpoint: POST /reconciliation/import
Request Body: CSV file with bank transactions

Get Reconciliation Matches

Endpoint: GET /reconciliation/matches

Confirm Match

Endpoint: POST /reconciliation/matches/{id}/confirm

Advanced Features

1. Invoice Reminders

Create Reminder Template

Endpoint: POST /api/v1/invoice-reminders/templates
Request Body:

{
  "name": "Before Due Date",
  "subject": "Invoice Due Soon",
  "body": "Your invoice is due in 3 days",
  "is_default": true
}

List Reminder Templates

Endpoint: GET /api/v1/invoice-reminders/templates

Get Reminder Template

Endpoint: GET /api/v1/invoice-reminders/templates/{id}

Update Reminder Template

Endpoint: PUT /api/v1/invoice-reminders/templates/{id}

Delete Reminder Template

Endpoint: DELETE /api/v1/invoice-reminders/templates/{id}

Schedule Reminders for Invoice

Endpoint: POST /api/v1/invoices/{invoice_id}/reminders/schedule
Request Body:

{
  "template_id": 456,
  "send_date": "2025-01-12T09:00:00Z",
  "reminder_type": "before_due"
}

Get Reminder History

Endpoint: GET /api/v1/invoices/{invoice_id}/reminders

Cancel Reminders

Endpoint: DELETE /api/v1/invoices/{invoice_id}/reminders

Send Manual Reminder

Endpoint: POST /api/v1/invoices/{invoice_id}/reminders/send
Request Body:

{
  "template_id": 456,
  "override_recipient": "client@example.com"
}

Preview Reminder

Endpoint: GET /api/v1/invoices/{invoice_id}/reminders/preview

2. Late Fee Management

Create Late Fee Configuration

Endpoint: POST /api/v1/late-fees/configs
Request Body:

{
  "name": "Standard Late Fee",
  "fee_type": "percentage",
  "fee_amount": 0.0,
  "fee_percentage": 5.0,
  "grace_period_days": 7,
  "is_active": true
}

List Late Fee Configurations

Endpoint: GET /api/v1/late-fees/configs

Get Late Fee Configuration

Endpoint: GET /api/v1/late-fees/configs/{id}

Update Late Fee Configuration

Endpoint: PUT /api/v1/late-fees/configs/{id}

Delete Late Fee Configuration

Endpoint: DELETE /api/v1/late-fees/configs/{id}

Calculate Late Fee

Endpoint: POST /api/v1/late-fees/calculate
Request Body:

{
  "invoice_id": 123,
  "as_of_date": "2025-01-20T00:00:00Z",
  "config_id": 456
}

Bulk Calculate Late Fees

Endpoint: POST /api/v1/late-fees/bulk-calculate

Get Late Fee Charge History

Endpoint: GET /api/v1/late-fees/charges

Apply Late Fee

Endpoint: POST /api/v1/late-fees/charges/{id}/apply

Waive Late Fee

Endpoint: POST /api/v1/late-fees/charges/{id}/waive

Reverse Late Fee

Endpoint: POST /api/v1/late-fees/charges/{id}/reverse

Get Late Fee Statistics

Endpoint: GET /api/v1/late-fees/stats

Process Overdue Invoices

Endpoint: POST /api/v1/late-fees/process-overdue

3. Invoice Archiving

Archive Single Invoice

Endpoint: POST /api/v1/invoices/{id}/archive
Request Body:

{
  "reason": "Manual archiving",
  "notify_client": false
}

Unarchive Invoice

Endpoint: POST /api/v1/invoices/{id}/unarchive

Get Archive History

Endpoint: GET /api/v1/invoices/archived

Get Archive Summary

Endpoint: GET /api/v1/invoices/archive/summary

Get Archive Statistics

Endpoint: GET /api/v1/invoices/archive/stats

4. Invoice Comments

Add Comment

Endpoint: POST /api/v1/invoices/{id}/comments
Request Body:

{
  "content": "Client requested payment extension",
  "is_internal": true
}

Get Comments

Endpoint: GET /api/v1/invoices/{id}/comments

Get Comment Threads

Endpoint: GET /api/v1/invoices/{id}/comments/threads

Get Comment Statistics

Endpoint: GET /api/v1/invoices/{id}/comments/stats

Get Specific Comment

Endpoint: GET /api/v1/comments/{id}

Update Comment

Endpoint: PUT /api/v1/comments/{id}

Delete Comment

Endpoint: DELETE /api/v1/comments/{id}

5. Invoice Cancellation

Cancel Invoice

Endpoint: POST /api/v1/invoices/{invoiceId}/cancel
Request Body:

{
  "reason": "Client requested cancellation",
  "refund_amount": 500.00,
  "notify_client": true
}

Get Invoice Cancellation

Endpoint: GET /api/v1/invoices/{invoiceId}/cancellation

List All Cancellations

Endpoint: GET /api/v1/cancellations

Get Specific Cancellation

Endpoint: GET /api/v1/cancellations/{cancellationId}

Reverse Cancellation

Endpoint: POST /api/v1/cancellations/{cancellationId}/reverse

Process Refund

Endpoint: POST /api/v1/cancellations/{cancellationId}/refund

6. Invoice Timeline

Get Timeline

Endpoint: GET /api/v1/invoices/{invoice_id}/timeline
Query Parameters: event_types, start_date, end_date

Response: Chronological list of all invoice events

Get Timeline Statistics

Endpoint: GET /api/v1/invoices/{invoice_id}/timeline/stats

Create Timeline Event

Endpoint: POST /api/v1/invoices/{invoice_id}/timeline/events

Get Recent Activity

Endpoint: GET /api/v1/invoices/{invoice_id}/timeline/recent

Get User Activity

Endpoint: GET /api/v1/invoices/{invoice_id}/timeline/users/{user_id}

Bulk Operations

1. Create Bulk Operation

Bulk Status Update

Endpoint: POST /api/v1/bulk-operations
Request Body:

{
  "type": "status_update",
  "invoice_ids": [1, 2, 3, 4, 5],
  "parameters": {
    "status": "sent",
    "notes": "Bulk status update"
  }
}

Bulk Send

Endpoint: POST /api/v1/bulk-operations
Request Body:

{
  "type": "send",
  "invoice_ids": [1, 2, 3],
  "parameters": {
    "template_id": 123,
    "custom_subject": "Your Monthly Invoice"
  }
}

Bulk Export

Endpoint: POST /api/v1/bulk-operations
Request Body:

{
  "type": "export",
  "invoice_ids": [1, 2, 3],
  "parameters": {
    "format": "xlsx",
    "include_items": true,
    "include_payments": true
  }
}

List Bulk Operations

Endpoint: GET /api/v1/bulk-operations

2. Monitor Bulk Operations

Get Operation Status

Endpoint: GET /api/v1/bulk-operations/{id}

Get Operation Results

Endpoint: GET /api/v1/bulk-operations/{id}/results

Get Operation Summary

Endpoint: GET /api/v1/bulk-operations/{id}/summary

Cancel Operation

Endpoint: POST /api/v1/bulk-operations/{id}/cancel

Retry Failed Items

Endpoint: POST /api/v1/bulk-operations/{id}/retry

Public Invoice Access

1. Public Link Management

Create Public Link

Endpoint: POST /admin/public-invoices/{invoiceId}/links
Request Body:

{
  "expires_at": "2025-02-15T23:59:59Z",
  "max_views": 10,
  "allow_download": true,
  "allow_print": true,
  "access_policy": {
    "block_bots": true,
    "allowed_countries": ["US", "CA"]
  }
}

Get Public Invoice (No Auth Required)

Endpoint: GET /public/invoices/{token}

Get Access Statistics

Endpoint: GET /public/invoices/{token}/statistics

Revoke Public Link

Endpoint: DELETE /admin/public-invoices/links/{token}

2. Client Portal

Get Client Portal Data

Endpoint: GET /client-portal/invoices
Headers: X-Client-Token: <client_token>

Update Client Information

Endpoint: PUT /client-portal/profile

Approval Workflows

1. Workflow Management

Create Workflow

Endpoint: POST /approval/workflows
Request Body:

{
  "name": "Invoice Approval",
  "entity_type": "invoice",
  "min_amount_threshold": 1000.00,
  "steps": [
    {
      "step_order": 1,
      "approver_type": "user",
      "approver_id": 123,
      "is_required": true
    }
  ]
}

Get Workflow

Endpoint: GET /approval/workflows/{id}

2. Approval Processes

Request Approval

Endpoint: POST /approval/request
Request Body:

{
  "entity_type": "invoice",
  "entity_id": 123,
  "workflow_id": 456,
  "notes": "Please approve this invoice"
}

Approve Request

Endpoint: POST /approval/instances/{id}/approve
Request Body:

{
  "notes": "Approved - within budget"
}

Reject Request

Endpoint: POST /approval/instances/{id}/reject
Request Body:

{
  "notes": "Rejected - missing documentation"
}

Get Pending Approvals

Endpoint: GET /approval/pending

Integration Guidelines

1. Error Handling

All endpoints return standardized error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "field": "client_id",
      "reason": "Client ID is required"
    }
  }
}

Common Error Codes:

• VALIDATION_ERROR: Request validation failed
• NOT_FOUND: Resource not found
• UNAUTHORIZED: Authentication required
• FORBIDDEN: Insufficient permissions
• CONFLICT: Resource conflict (duplicate, etc.)
• RATE_LIMITED: Too many requests

2. Pagination

List endpoints support pagination:

{
  "data": [...],
  "meta": {
    "limit": 25,
    "offset": 0,
    "total": 150,
    "has_more": true
  }
}

3. Field Validation

Required Fields:

• Invoice: client_id, issue_date, due_date
• Client: name, email, type
• Payment: amount, payment_method, payment_date

Field Formats:

• Dates: ISO 8601 format (2025-01-15T00:00:00Z)
• Currency: 3-letter ISO code (USD, EUR)
• Amounts: Decimal with 2 decimal places

4. Real-time Updates

For real-time invoice updates, use WebSocket connection:

const socket = new WebSocket('ws://localhost:8080/ws');
socket.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === 'invoice_updated') {
    // Handle invoice update
  }
};

5. Performance Considerations

• Use pagination for large datasets
• Implement caching for frequently accessed data
• Use bulk operations for multiple invoice updates
• Optimize database queries with appropriate filters

6. Security Best Practices

• Always validate user permissions before operations
• Use HTTPS in production
• Implement proper CORS policies
• Sanitize all user inputs
• Log all financial operations for audit trails

NextJS 15+ Specific Implementation

1. Server Actions

// app/actions/invoice-actions.ts
'use server'

import { revalidatePath } from 'next/cache'

export async function createInvoice(formData: FormData) {
  const response = await fetch('/api/v1/invoices', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(invoiceData),
  })
  
  if (response.ok) {
    revalidatePath('/invoices')
    return { success: true }
  }
  
  return { error: 'Failed to create invoice' }
}

2. React Server Components

// app/invoices/page.tsx
import { getInvoices } from '@/lib/api'

export default async function InvoicesPage() {
  const invoices = await getInvoices()
  
  return (
    <div>
      {invoices.map(invoice => (
        <InvoiceCard key={invoice.id} invoice={invoice} />
      ))}
    </div>
  )
}

3. Streaming

// app/invoices/loading.tsx
export default function Loading() {
  return <InvoiceListSkeleton />
}

// app/invoices/page.tsx
import { Suspense } from 'react'

export default function InvoicesPage() {
  return (
    <Suspense fallback={<InvoiceListSkeleton />}>
      <InvoiceList />
    </Suspense>
  )
}

4. API Routes

// app/api/invoices/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function GET(request: NextRequest) {
  const { searchParams } = new URL(request.url)
  const status = searchParams.get('status')
  
  // Fetch invoices with status filter
  const invoices = await getInvoices({ status })
  
  return NextResponse.json(invoices)
}

export async function POST(request: NextRequest) {
  const invoiceData = await request.json()
  
  // Create invoice
  const invoice = await createInvoice(invoiceData)
  
  return NextResponse.json(invoice, { status: 201 })
}

This comprehensive guide covers the entire invoice system API with all endpoints, request/response formats, and NextJS 15+ specific implementation patterns. Use this as your reference for building the frontend integration.