InfraNotes - API Endpoint Documentation

Authentication Endpoints

User Registration

• Endpoint: POST /api/auth/register
• Payload:

  {
    "full_name": "John Doe",
    "email": "user@example.com",
    "password": "Password123",
    "username": "johndoe",
    "role": "user"
  }
  

• Response:

  {
    "id": 1,
    "full_name": "John Doe",
    "email": "user@example.com",
    "username": "johndoe",
    "role": "user",
    "is_email_verified": false,
    "message": "Please check your email to verify your account"
  }
  

User Login

• Endpoint: POST /api/auth/login
• Payload:

  {
    "email": "user@example.com",
    "password": "Password123"
  }
  

• Response:

  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "name": "John Doe",
      "email": "user@example.com",
      "username": "johndoe",
      "role": "user",
      "mfa_enabled": false
    }
  }
  

Email Verification

• Endpoint: GET /api/auth/verify-email?token=<verification_token>
• Response:

  {
    "message": "Email verified successfully. You can now log in."
  }
  

Resend Verification Email

• Endpoint: POST /api/auth/resend-verification
• Payload:

  {
    "email": "user@example.com"
  }
  

• Response:

  {
    "message": "Verification email sent. Please check your inbox."
  }
  

Get User Profile

• Endpoint: GET /api/auth/profile
• Headers: Authorization: Bearer <token>
• Response:

  {
    "id": 1,
    "name": "John Doe",
    "email": "user@example.com",
    "username": "johndoe",
    "role": "user",
    "mfa_enabled": false,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T00:00:00Z"
  }
  

Expense Management Endpoints

Create Expense

• Endpoint: POST /api/expenses
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "amount": 250.75,
    "type": "expense",
    "category": "Software",
    "category_id": 3,
    "description": "Software license purchase",
    "notes": "Annual subscription",
    "project_id": 2,
    "currency": "USD"
  }
  

• Response:

  {
    "id": 1,
    "amount": 250.75,
    "type": "expense",
    "category": "Software",
    "category_id": 3,
    "description": "Software license purchase",
    "notes": "Annual subscription",
    "project_id": 2,
    "project_name": "Website Redesign",
    "user_id": 1,
    "shared": false,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T00:00:00Z"
  }
  

Get Expense by ID

• Endpoint: GET /api/expenses/{id}
• Headers: Authorization: Bearer <token>
• Response:

  {
    "id": 1,
    "amount": 250.75,
    "type": "expense",
    "category": "Software",
    "category_id": 3,
    "description": "Software license purchase",
    "notes": "Annual subscription",
    "project_id": 2,
    "project_name": "Website Redesign",
    "user_id": 1,
    "shared": false,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T00:00:00Z"
  }
  

Update Expense

• Endpoint: PUT /api/expenses/{id}
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "amount": 300.00,
    "description": "Updated license purchase",
    "notes": "Annual enterprise subscription"
  }
  

• Response:

  {
    "id": 1,
    "amount": 300.00,
    "type": "expense",
    "category": "Software",
    "category_id": 3,
    "description": "Updated license purchase",
    "notes": "Annual enterprise subscription",
    "project_id": 2,
    "project_name": "Website Redesign",
    "user_id": 1,
    "shared": false,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T01:00:00Z"
  }
  

Delete Expense

• Endpoint: DELETE /api/expenses/{id}
• Headers: Authorization: Bearer <token>
• Response: HTTP 204 No Content

List Expenses

• Endpoint: GET /api/expenses
• Headers: Authorization: Bearer <token>
• Query Parameters:
  • type: Filter by expense type (expense, income)
  • category_id: Filter by category ID
  • project_id: Filter by project ID
  • start_date: Filter by start date (ISO format)
  • end_date: Filter by end date (ISO format)
  • min_amount: Filter by minimum amount
  • max_amount: Filter by maximum amount
  • limit: Number of records to return (default: 50)
  • offset: Offset for pagination (default: 0)
• Response:

  {
    "data": [
      {
        "id": 1,
        "amount": 300.00,
        "type": "expense",
        "category": "Software",
        "category_id": 3,
        "description": "Updated license purchase",
        "notes": "Annual enterprise subscription",
        "project_id": 2,
        "project_name": "Website Redesign",
        "user_id": 1,
        "shared": false,
        "created_at": "2025-05-17T00:00:00Z",
        "updated_at": "2025-05-17T01:00:00Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
  

Project Management Endpoints

Create Project

• Endpoint: POST /api/projects
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "name": "Website Redesign",
    "description": "Company website redesign project",
    "start_date": "2025-06-01T00:00:00Z",
    "end_date": "2025-07-31T23:59:59Z",
    "status": "active",
    "budget": 15000,
    "location": "Remote"
  }
  

• Response:

  {
    "id": 1,
    "name": "Website Redesign",
    "description": "Company website redesign project",
    "location": "Remote",
    "start_date": "2025-06-01T00:00:00Z",
    "end_date": "2025-07-31T23:59:59Z",
    "budget": 15000,
    "status": "active",
    "user_id": 1,
    "shared": false,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T00:00:00Z"
  }
  

Get Project by ID

• Endpoint: GET /api/projects/{id}
• Headers: Authorization: Bearer <token>
• Response:

  {
    "id": 1,
    "name": "Website Redesign",
    "description": "Company website redesign project",
    "location": "Remote",
    "start_date": "2025-06-01T00:00:00Z",
    "end_date": "2025-07-31T23:59:59Z",
    "budget": 15000,
    "status": "active",
    "user_id": 1,
    "shared": false,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T00:00:00Z"
  }
  

Update Project

• Endpoint: PUT /api/projects/{id}
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "name": "Website Redesign and Migration",
    "status": "in-progress",
    "budget": 18000
  }
  

• Response:

  {
    "id": 1,
    "name": "Website Redesign and Migration",
    "description": "Company website redesign project",
    "location": "Remote",
    "start_date": "2025-06-01T00:00:00Z",
    "end_date": "2025-07-31T23:59:59Z",
    "budget": 18000,
    "status": "in-progress",
    "user_id": 1,
    "shared": false,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T01:30:00Z"
  }
  

Delete Project

• Endpoint: DELETE /api/projects/{id}
• Headers: Authorization: Bearer <token>
• Response: HTTP 204 No Content

List Projects

• Endpoint: GET /api/projects
• Headers: Authorization: Bearer <token>
• Query Parameters:
  • status: Filter by project status
  • start_date: Filter by start date (ISO format)
  • end_date: Filter by end date (ISO format)
  • min_budget: Filter by minimum budget
  • max_budget: Filter by maximum budget
  • limit: Number of records to return (default: 50)
  • offset: Offset for pagination (default: 0)
• Response:

  {
    "data": [
      {
        "id": 1,
        "name": "Website Redesign",
        "description": "Company website redesign project",
        "location": "Remote",
        "start_date": "2025-06-01T00:00:00Z",
        "end_date": "2025-07-31T23:59:59Z",
        "budget": 15000,
        "status": "active",
        "user_id": 1,
        "shared": false,
        "created_at": "2025-05-17T00:00:00Z",
        "updated_at": "2025-05-17T00:00:00Z"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
  

Get Project Expenses

• Endpoint: GET /api/projects/{id}/expenses
• Headers: Authorization: Bearer <token>
• Response:

  {
    "data": [
      {
        "id": 1,
        "amount": 250.75,
        "type": "expense",
        "category": "Software",
        "description": "Software license purchase",
        "notes": "Annual subscription",
        "project_id": 1,
        "user_id": 1,
        "created_at": "2025-05-17T00:00:00Z"
      }
    ],
    "total": 1,
    "project_total": 250.75
  }
  

Invoice Management Endpoints

Create Invoice

• Endpoint: POST /api/invoices
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "client_id": 1,
    "status": "draft",
    "issue_date": "2025-05-17T00:00:00Z",
    "due_date": "2025-06-17T00:00:00Z",
    "tax_rate": 10,
    "discount_amount": 0,
    "notes": "Payment due within 30 days",
    "terms": "Standard terms apply",
    "currency": "USD",
    "items": [
      {
        "description": "Consulting Services",
        "quantity": 10,
        "unit_price": 200,
        "tax_rate": 10
      }
    ]
  }
  

• Response:

  {
    "id": 1,
    "invoice_number": "INV-2025-001",
    "client_id": 1,
    "user_id": 1,
    "status": "draft",
    "issue_date": "2025-05-17T00:00:00Z",
    "due_date": "2025-06-17T00:00:00Z",
    "subtotal": 2000,
    "tax_amount": 200,
    "tax_rate": 10,
    "discount_amount": 0,
    "discount_type": "fixed",
    "total_amount": 2200,
    "amount_paid": 0,
    "balance_due": 2200,
    "notes": "Payment due within 30 days",
    "terms": "Standard terms apply",
    "currency": "USD",
    "items": [
      {
        "id": 1,
        "invoice_id": 1,
        "description": "Consulting Services",
        "quantity": 10,
        "unit_price": 200,
        "amount": 2000,
        "tax_rate": 10,
        "tax_amount": 200,
        "created_at": "2025-05-17T00:00:00Z",
        "updated_at": "2025-05-17T00:00:00Z"
      }
    ],
    "approval_status": "pending",
    "requires_approval": false,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T00:00:00Z"
  }
  

Get Invoice by ID

• Endpoint: GET /api/invoices/{id}
• Headers: Authorization: Bearer <token>
• Response:

  {
    "id": 1,
    "invoice_number": "INV-2025-001",
    "client_id": 1,
    "user_id": 1,
    "status": "draft",
    "issue_date": "2025-05-17T00:00:00Z",
    "due_date": "2025-06-17T00:00:00Z",
    "subtotal": 2000,
    "tax_amount": 200,
    "tax_rate": 10,
    "discount_amount": 0,
    "discount_type": "fixed",
    "total_amount": 2200,
    "amount_paid": 0,
    "balance_due": 2200,
    "notes": "Payment due within 30 days",
    "terms": "Standard terms apply",
    "currency": "USD",
    "items": [
      {
        "id": 1,
        "invoice_id": 1,
        "description": "Consulting Services",
        "quantity": 10,
        "unit_price": 200,
        "amount": 2000,
        "tax_rate": 10,
        "tax_amount": 200,
        "created_at": "2025-05-17T00:00:00Z",
        "updated_at": "2025-05-17T00:00:00Z"
      }
    ],
    "payments": [],
    "approval_status": "pending",
    "requires_approval": false,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T00:00:00Z"
  }
  

Update Invoice Status

• Endpoint: POST /api/invoices/{id}/status
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "status": "sent"
  }
  

• Response:

  {
    "id": 1,
    "status": "sent",
    "updated_at": "2025-05-17T02:00:00Z"
  }
  

Generate PDF for Invoice

• Endpoint: GET /api/invoices/{id}/pdf
• Headers: Authorization: Bearer <token>
• Response: PDF file

Payment System Endpoints

Add Payment to Invoice

• Endpoint: POST /api/invoices/{id}/payments
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "amount": 1000.00,
    "payment_method": "bank_transfer",
    "payment_date": "2025-05-20T00:00:00Z",
    "transaction_id": "TRX123456",
    "notes": "Partial payment"
  }
  

• Response:

  {
    "id": 1,
    "invoice_id": 1,
    "amount": 1000.00,
    "payment_method": "bank_transfer",
    "payment_date": "2025-05-20T00:00:00Z",
    "transaction_id": "TRX123456",
    "notes": "Partial payment",
    "reconciliation_status": "pending",
    "created_at": "2025-05-20T12:00:00Z",
    "updated_at": "2025-05-20T12:00:00Z"
  }
  

Get Invoice Payments

• Endpoint: GET /api/invoices/{id}/payments
• Headers: Authorization: Bearer <token>
• Response:

  {
    "data": [
      {
        "id": 1,
        "invoice_id": 1,
        "amount": 1000.00,
        "payment_method": "bank_transfer",
        "payment_date": "2025-05-20T00:00:00Z",
        "transaction_id": "TRX123456",
        "notes": "Partial payment",
        "reconciliation_status": "pending",
        "created_at": "2025-05-20T12:00:00Z",
        "updated_at": "2025-05-20T12:00:00Z"
      }
    ],
    "total_paid": 1000.00,
    "balance_due": 1200.00
  }
  

Delete Payment

• Endpoint: DELETE /api/invoices/{invoiceId}/payments/{paymentId}
• Headers: Authorization: Bearer <token>
• Response: HTTP 204 No Content

Create Payment Gateway Configuration

• Endpoint: POST /api/payment-gateways
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "name": "Stripe",
    "provider": "stripe",
    "is_active": true,
    "is_default": true,
    "config": {
      "api_key": "sk_test_123456789",
      "webhook_secret": "whsec_123456789",
      "public_key": "pk_test_123456789"
    }
  }
  

• Response:

  {
    "id": 1,
    "name": "Stripe",
    "provider": "stripe",
    "is_active": true,
    "is_default": true,
    "user_id": 1,
    "created_at": "2025-05-20T12:00:00Z",
    "updated_at": "2025-05-20T12:00:00Z"
  }
  

Create Payment Intent

• Endpoint: POST /api/payment-intents
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "invoice_id": 1,
    "amount": 2200.00,
    "currency": "USD",
    "payment_method": "credit_card",
    "description": "Payment for Invoice #INV-2025-001"
  }
  

• Response:

  {
    "id": "pi_123456789",
    "client_secret": "pi_123456789_secret_123456789",
    "amount": 2200.00,
    "currency": "USD",
    "status": "requires_payment_method",
    "created_at": "2025-05-20T12:00:00Z"
  }
  

Budget Management Endpoints

Create Budget

• Endpoint: POST /api/budgets
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "name": "Q3 Marketing Budget",
    "description": "Budget for Q3 marketing activities",
    "type": "department",
    "status": "active",
    "period": "quarterly", 
    "start_date": "2025-07-01T00:00:00Z",
    "end_date": "2025-09-30T23:59:59Z",
    "total_amount": 75000,
    "currency": "USD",
    "alert_threshold": 80
  }
  

• Response:

  {
    "id": 1,
    "name": "Q3 Marketing Budget",
    "description": "Budget for Q3 marketing activities",
    "type": "department",
    "status": "active",
    "period": "quarterly",
    "start_date": "2025-07-01T00:00:00Z",
    "end_date": "2025-09-30T23:59:59Z",
    "total_amount": 75000,
    "currency": "USD",
    "used_amount": 0,
    "remaining_amount": 75000,
    "alert_threshold": 80,
    "user_id": 1,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T00:00:00Z"
  }
  

Get Budget Usage Report

• Endpoint: GET /api/budgets/{id}/usage
• Headers: Authorization: Bearer <token>
• Response:

  {
    "budget_id": 1,
    "budget_name": "Q3 Marketing Budget",
    "total_amount": 75000,
    "used_amount": 12500,
    "remaining_amount": 62500,
    "usage_percentage": 16.67,
    "period": "quarterly",
    "start_date": "2025-07-01T00:00:00Z",
    "end_date": "2025-09-30T23:59:59Z",
    "currency": "USD",
    "expense_breakdown": [
      {
        "category": "Advertising",
        "amount": 7500
      },
      {
        "category": "Events",
        "amount": 5000
      }
    ]
  }
  

Compliance Feature Endpoints

Create Compliance Policy

• Endpoint: POST /api/compliance/policies
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "name": "Expense Approval Policy",
    "description": "All expenses above $1000 require manager approval",
    "type": "expense",
    "is_active": true,
    "rules": [
      {
        "condition": "amount > 1000",
        "action": "require_approval",
        "approver_role": "manager"
      }
    ]
  }
  

• Response:

  {
    "id": 1,
    "name": "Expense Approval Policy",
    "description": "All expenses above $1000 require manager approval",
    "type": "expense",
    "is_active": true,
    "created_at": "2025-05-20T12:00:00Z",
    "updated_at": "2025-05-20T12:00:00Z",
    "rules": [
      {
        "id": 1,
        "policy_id": 1,
        "condition": "amount > 1000",
        "action": "require_approval",
        "approver_role": "manager",
        "created_at": "2025-05-20T12:00:00Z"
      }
    ]
  }
  

Get Compliance Policies

• Endpoint: GET /api/compliance/policies
• Headers: Authorization: Bearer <token>
• Response:

  {
    "data": [
      {
        "id": 1,
        "name": "Expense Approval Policy",
        "description": "All expenses above $1000 require manager approval",
        "type": "expense",
        "is_active": true,
        "created_at": "2025-05-20T12:00:00Z",
        "updated_at": "2025-05-20T12:00:00Z"
      }
    ],
    "total": 1
  }
  

Get Compliance Policy Details

• Endpoint: GET /api/compliance/policies/{id}
• Headers: Authorization: Bearer <token>
• Response:

  {
    "id": 1,
    "name": "Expense Approval Policy",
    "description": "All expenses above $1000 require manager approval",
    "type": "expense",
    "is_active": true,
    "created_at": "2025-05-20T12:00:00Z",
    "updated_at": "2025-05-20T12:00:00Z",
    "rules": [
      {
        "id": 1,
        "policy_id": 1,
        "condition": "amount > 1000",
        "action": "require_approval",
        "approver_role": "manager",
        "created_at": "2025-05-20T12:00:00Z"
      }
    ]
  }
  

Update Compliance Policy

• Endpoint: PUT /api/compliance/policies/{id}
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "name": "Expense Approval Policy",
    "description": "All expenses above $500 require manager approval",
    "is_active": true,
    "rules": [
      {
        "condition": "amount > 500",
        "action": "require_approval",
        "approver_role": "manager"
      }
    ]
  }
  

• Response:

  {
    "id": 1,
    "name": "Expense Approval Policy",
    "description": "All expenses above $500 require manager approval",
    "type": "expense",
    "is_active": true,
    "updated_at": "2025-05-20T13:00:00Z"
  }
  

Compliance Validation

• Endpoint: POST /api/compliance/validate
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "entity_type": "expense",
    "entity_id": 1,
    "action": "create"
  }
  

• Response:

  {
    "compliant": true,
    "validation_results": [
      {
        "policy_id": 1,
        "policy_name": "Expense Approval Policy",
        "compliant": true,
        "actions_required": [],
        "message": "Expense amount is below threshold"
      }
    ]
  }
  

Client Management Endpoints

Create Client

• Endpoint: POST /api/clients
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "name": "Acme Corp",
    "contact_name": "John Smith",
    "email": "contact@acmecorp.com",
    "phone": "1234567890",
    "address": "123 Business St",
    "city": "Business City",
    "state": "BC",
    "postal_code": "12345",
    "country": "USA",
    "default_currency": "USD",
    "type": "client"
  }
  

• Response:

  {
    "id": 1,
    "type": "client",
    "name": "Acme Corp",
    "contact_name": "John Smith",
    "email": "contact@acmecorp.com",
    "phone": "1234567890",
    "address": "123 Business St",
    "city": "Business City",
    "state": "BC",
    "postal_code": "12345",
    "country": "USA",
    "default_currency": "USD",
    "user_id": 1,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T00:00:00Z"
  }
  

Team Management Endpoints

Create Team

• Endpoint: POST /api/teams
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "name": "Engineering Team",
    "description": "Team for engineering department"
  }
  

• Response:

  {
    "id": 1,
    "name": "Engineering Team",
    "description": "Team for engineering department",
    "owner_id": 1,
    "created_at": "2025-05-17T00:00:00Z",
    "updated_at": "2025-05-17T00:00:00Z"
  }
  

Add Member to Team

• Endpoint: POST /api/teams/{id}/members
• Headers: Authorization: Bearer <token>
• Payload:

  {
    "user_id": 2,
    "role": "member"
  }
  

• Response:

  {
    "team_id": 1,
    "user_id": 2,
    "role": "member",
    "created_at": "2025-05-17T00:00:00Z"
  }