انتقل إلى المحتوى الرئيسي

Finance API Documentation Index

Overview​

This section contains comprehensive API documentation for all Finance Module endpoints across multiple sub-modules. The APIs are designed following RESTful principles with full support for multi-dimensional accounting, cross-module integration, and event-driven architecture.

API Organization by Sub-Module​

General Ledger APIs​

Core accounting and journal management endpoints.

Journal Management APIs​

  • General Journals API

    • Base URL: /general-journals
    • Features: Complete journal lifecycle, dimensional transactions, posting/reversal
    • Endpoints: 17 endpoints covering journal and transaction operations

  • Customer Payment Journals API (Planned)

    • Base URL: /general-journals/customer-payments
    • Features: Specialized customer payment processing

  • Vendor Payment Journals API (Planned)

    • Base URL: /general-journals/vendor-payments
    • Features: Specialized vendor payment processing

Dimension & Structure APIs​

  • Dimension Combinations API

    • Base URL: /general-ledger/dimension-combinations
    • Features: Interactive dimension resolution, intelligent suggestions
    • Key Endpoint: POST /resolve-and-suggest-segments

  • Account Structures API (Planned)

    • Base URL: /general-ledger/account-structures
    • Features: Dimension hierarchy management, constraint configuration

Reporting & Analytics APIs​

  • Financial Reports API (Planned)

    • Base URL: /general-ledger/reports
    • Features: Trial balance, income statement, balance sheet

  • Ledger Setup API (Planned)

    • Base URL: /general-ledger/setup
    • Features: Ledger configuration, fiscal calendar, chart of accounts

Financial Dimensions APIs​

Shared dimensional infrastructure used across all finance modules.

Core Dimension Management​

  • Dimension Attributes API (Planned)

    • Base URL: /financial-dimensions/dimension-attributes
    • Features: Dimension definition, custom vs entity-backed types

  • Dimension Values API (Planned)

    • Base URL: /financial-dimensions/dimension-attributes/{id}/values
    • Features: Value management, validation, lookup services

Default Dimension Sets​

Lookup & Validation Services​

  • Dimension Lookup API (Planned)
    • Base URL: /financial-dimensions/lookups
    • Features: Fast lookup services, type-ahead support, validation

Accounts Receivable APIs Planned​

Customer management and receivables processing endpoints.

Customer Management​

  • Customer Master API (Planned)

    • Base URL: /accounts-receivable/customers
    • Features: Customer CRUD, default dimensions, credit management

  • Customer Pricing API (Planned)

    • Base URL: /accounts-receivable/customers/{id}/pricing
    • Features: Customer-specific pricing, discounts, terms

Invoicing & Collections​

  • Customer Invoices API (Planned)

    • Base URL: /accounts-receivable/invoices
    • Features: Invoice generation, posting, status management

  • Customer Payments API (Planned)

    • Base URL: /accounts-receivable/payments
    • Features: Payment processing, application, cash discounts

  • Collections API (Planned)

    • Base URL: /accounts-receivable/collections
    • Features: Aging analysis, collection activities, dunning letters

Accounts Payable APIs Planned​

Vendor management and payables processing endpoints.

Vendor Management​

  • Vendor Master API (Planned)

    • Base URL: /accounts-payable/vendors
    • Features: Vendor CRUD, default dimensions, payment terms

  • Vendor Categories API (Planned)

    • Base URL: /accounts-payable/vendor-categories
    • Features: Vendor classification, default settings

Invoice Processing​

  • Vendor Invoices API (Planned)

    • Base URL: /accounts-payable/invoices
    • Features: Invoice entry, three-way matching, approval workflow

  • Invoice Matching API (Planned)

    • Base URL: /accounts-payable/invoices/{id}/matching
    • Features: PO-Receipt-Invoice matching, tolerance validation

Payment Processing​

  • Vendor Payments API (Planned)
    • Base URL: /accounts-payable/payments
    • Features: Payment proposals, processing, check printing

Cross-Module Integration Patterns​

Shared API Conventions​

Authentication & Authorization​

Authorization: Bearer {jwt-token}
Content-Type: application/json
X-Tenant-ID: {tenant-id}

Standard Response Format​

{
  "data": { /* response payload */ },
  "meta": {
    "timestamp": "2025-03-15T10:00:00.000Z",
    "request_id": "req-123-456-789",
    "module": "general-ledger",
    "version": "v1"
  }
}

Error Response Format (RFC 7807)​

{
  "type": "https://api.company.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "One or more validation errors occurred",
  "instance": "/general-journals/12345",
  "errors": {
    "dimension_segments[0].value": ["Invalid MainAccount value"]
  },
  "trace_id": "trace-123-456"
}

Integration Workflow Examples​

Customer Invoice to General Ledger​

// 1. Create customer invoice with dimensions
const invoice = await fetch('/accounts-receivable/invoices', {
  method: 'POST',
  body: JSON.stringify({
    customer_id: customerId,
    dimension_segments: inheritedDimensions,
    line_items: [...]
  })
});

// 2. Post to general ledger (automatic via integration event)
// Backend handles: InvoicePostedIntegrationEvent → GeneralLedgerJournalCreation

// 3. Verify GL posting
const glEntries = await fetch(`/general-journals/transactions/by-document/${invoice.document_number}`);

Dimension Resolution Across Modules​

// 1. Get customer default dimensions (AR module)
const customer = await fetch(`/accounts-receivable/customers/${customerId}`);
const defaultDimensions = customer.default_dimension_segments;

// 2. Resolve account structure (GL module)
const resolution = await fetch('/general-ledger/dimension-combinations/resolve-and-suggest-segments', {
  method: 'POST',
  body: JSON.stringify({
    ledger_id: ledgerId,
    segment_inputs: defaultDimensions
  })
});

// 3. Create transaction with resolved dimensions
const transaction = await createTransaction({
  dimension_segments: resolution.validation_results.map(v => ({
    dimension_attribute_id: v.dimension_attribute_id,
    value: v.value
  }))
});

Security & Permissions​

Role-Based Access Control (RBAC)​

Finance Module Permissions​

{
  "roles": {
    "finance_manager": [
      "gl:journals:create",
      "gl:journals:post", 
      "gl:journals:reverse",
      "ar:invoices:create",
      "ap:invoices:approve"
    ],
    "accounting_clerk": [
      "gl:journals:create",
      "ar:invoices:create",
      "ap:invoices:create"
    ],
    "finance_viewer": [
      "gl:journals:read",
      "ar:reports:read",
      "ap:reports:read"
    ]
  }
}

API Security Headers​

# Required for all finance API calls
Authorization: Bearer {jwt-token}
X-Tenant-ID: {tenant-id}
X-User-Role: finance_manager
X-Request-ID: {unique-request-id}

# Optional but recommended
X-Client-Version: 1.2.3
X-Feature-Flags: advanced-dimensions,multi-currency

Data Protection & Audit​

  • PII Encryption: Customer/vendor sensitive data encrypted at rest
  • Audit Trail: All financial transactions logged with user attribution
  • Data Retention: Financial records retained per regulatory requirements
  • Access Logging: All API access logged for compliance monitoring

Performance & Scalability​

API Performance Targets​

Operation TypeTarget Response TimeRate Limit
Dimension Resolution< 100ms200/min
Journal Operations< 500ms100/min
Reporting Queries< 2s50/min
Bulk Operations< 30s10/min
Simple CRUD< 200ms150/min

Caching Strategy​

Client-Side Caching​

// Cache dimension metadata for 1 hour
const dimensionCache = new Map();
const CACHE_DURATION = 60 * 60 * 1000; // 1 hour

async function getCachedDimensionAttribute(id) {
  const cached = dimensionCache.get(id);
  if (cached && Date.now() - cached.timestamp < CACHE_DURATION) {
    return cached.data;
  }
  
  const data = await fetch(`/financial-dimensions/dimension-attributes/${id}`);
  dimensionCache.set(id, { data, timestamp: Date.now() });
  return data;
}

Server-Side Optimization​

  • Dimension Resolution: Cached for 24 hours
  • Account Structures: Cached until configuration changes
  • Exchange Rates: Cached for 1 hour with refresh triggers
  • User Permissions: Cached for session duration

Pagination & Filtering​

Standard Pagination​

GET /general-journals?page=1&size=50&sort=created_date:desc
{
  "data": [...],
  "pagination": {
    "page": 1,
    "size": 50,
    "total_pages": 10,
    "total_count": 500,
    "has_next": true,
    "has_previous": false
  }
}

Advanced Filtering​

GET /general-journals/account-entries?filters=account_id:eq:1100,posting_date:gte:2025-01-01,amount:gt:1000

Testing & Development​

Environment Configuration​

EnvironmentBase URLPurpose
Developmenthttp://localhost:5134Local development
Testinghttps://api-test.company.comIntegration testing
Staginghttps://api-staging.company.comUAT and performance testing
Productionhttps://api.company.comLive system

API Testing Collections​

Postman Collections​

Sample Test Workflows​

# Complete finance workflow test
# 1. Setup dimensions
POST /financial-dimensions/dimension-attributes
POST /financial-dimensions/dimension-attributes/{id}/values

# 2. Create customer with default dimensions
POST /accounts-receivable/customers
PUT /accounts-receivable/customers/{id}/default-dimensions

# 3. Create and post invoice
POST /accounts-receivable/invoices
PUT /accounts-receivable/invoices/{id}/post

# 4. Verify GL integration
GET /general-journals/transactions/by-document/{invoice-number}

# 5. Process payment
POST /accounts-receivable/payments
PUT /accounts-receivable/payments/{id}/apply

# 6. Generate reports
GET /general-ledger/reports/trial-balance?as-of=2025-03-31

API Versioning & Evolution​

Versioning Strategy​

  • URL Versioning: /v1/general-journals, /v2/general-journals
  • Backward Compatibility: Maintained for one major version
  • Deprecation Policy: 6 months notice for breaking changes
  • Feature Flags: Gradual rollout of new capabilities

API Evolution Timeline​

Breaking Change Examples​

// v1 (Current)
{
  "account_id": "uuid-here",
  "amount": 1500.00
}

// v2 (Planned - dimension support)
{
  "dimension_combination_id": "uuid-here",
  "dimension_segments": [...],
  "amounts": {
    "base_currency": 1500.00,
    "transaction_currency": 1500.00,
    "reporting_currency": 1425.00
  }
}

API Documentation Standards​

OpenAPI Specification​

All APIs documented using OpenAPI 3.0 with:

  • Complete request/response schemas
  • Example payloads for all endpoints
  • Error response documentation
  • Authentication and authorization details

Code Generation​

  • Client SDKs: Auto-generated for TypeScript, C#, Python
  • Server Stubs: Used for contract-first development
  • Mock Servers: Generated for frontend development

API Documentation Tools​

  • Swagger UI: Interactive API exploration
  • Redoc: Beautiful API documentation
  • Postman: Complete request collections
  • Insomnia: Alternative API client support

Cross-Module API Dependencies​

Module Interaction Matrix​

Integration Event APIs​

// Published by General Ledger
{
  "event_type": "journal_posted",
  "module": "general-ledger",
  "data": {
    "journal_id": "uuid",
    "document_number": "GJ-2025-001",
    "posted_date": "2025-03-15T15:30:00Z",
    "entries": [...]
  }
}

// Consumed by Accounts Receivable
{
  "event_type": "customer_balance_updated",
  "module": "accounts-receivable", 
  "data": {
    "customer_id": "uuid",
    "new_balance": 15000.00,
    "transaction_reference": "GJ-2025-001"
  }
}

Internal References​

External Standards​

Last Updated: [Current Date] | Version: 1.0 | Status: Active Development

Current Focus: General Ledger and Financial Dimensions APIs Next Phase: Accounts Receivable and Accounts Payable APIs Coming Soon: Advanced reporting and analytics APIs