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

General Ledger API Documentation

Overview​

The General Ledger sub-module provides core accounting functionality with full support for multi-dimensional transaction processing. This is the foundation of the finance module, handling journal management, dimensional accounting, and financial reporting.

Available APIs​

Journal Management​

  • General Journals API Complete

    • Base URL: /general-journals
    • Features: Complete journal lifecycle, dimensional transactions, posting/reversal
    • Endpoints: 17 comprehensive endpoints for journal and transaction operations
    • Key Features: Multi-dimensional support, fiscal period validation, reversal capabilities

  • Customer Payment Journals API Planned

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

  • Vendor Payment Journals API Planned

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

Dimension Management​

  • Dimension Combinations API Complete
    • Base URL: /general-ledger/dimension-combinations
    • Features: Interactive dimension resolution, intelligent suggestions
    • Key Endpoint: POST /resolve-and-suggest-segments
    • Integration: Core service for all dimensional transaction entry

Configuration & Setup​

  • Account Structures API Planned

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

  • Ledger Setup API Planned

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

Tax Management​

  • Tax Periods API Complete

    • Base URL: /tax/tax-periods
    • Features: Tax period management, settlement processing
    • Key Features: Period templates, automatic generation, settle and post sales tax

  • Tax Settlements API Complete

    • Base URL: /tax/tax-settlements
    • Features: Tax settlement records query and audit trail
    • Key Features: Corrections workflow, settlement counter tracking

  • Tax Reporting Codes API Complete

    • Base URL: /tax/tax-reporting-codes
    • Features: VAT return field mapping and reporting code management

  • Tax Report Layouts API Complete

    • Base URL: /tax/tax-report-layouts
    • Features: VAT return template management for different jurisdictions

  • Tax Transactions API Complete

    • Base URL: /tax/tax-transactions
    • Features: Detailed tax transaction queries for reporting and reconciliation

  • Tax Deletion API Complete

    • Base URL: /tax (various endpoints)
    • Features: Safe deletion with usage validation for tax entities

Reporting​

  • Financial Reports API Planned
    • Base URL: /general-ledger/reports
    • Features: Trial balance, income statement, balance sheet, dimensional analysis

Quick Start​

Basic Journal Entry Workflow​

// 1. Resolve dimensions for user interface
const resolution = await fetch('/general-ledger/dimension-combinations/resolve-and-suggest-segments', {
  method: 'POST',
  body: JSON.stringify({
    ledger_id: "your-ledger-id",
    segment_inputs: [
      { dimension_attribute_id: "main-account-id", value: "1100" }
    ]
  })
});

// 2. Create journal with dimensional transactions
const journal = await fetch('/general-journals', {
  method: 'POST',
  body: JSON.stringify({
    ledger_journal_name_id: "journal-name-id",
    currency_code: "AED",
    transactions: [{
      description: "Office supplies",
      debit_amount: 1500.00,
      credit_amount: 0.00,
      dimension_segments: [
        { dimension_attribute_id: "main-account-id", value: "1100" },
        { dimension_attribute_id: "department-id", value: "ADMIN" }
      ]
    }]
  })
});

// 3. Post the journal
await fetch(`/general-journals/${journal.id}/post`, { method: 'PUT' });

Integration Patterns​

With Financial Dimensions Module​

// Dimension resolution is the bridge between modules
const dimensionService = {
  async resolveForUI(mainAccount) {
    return await fetch('/general-ledger/dimension-combinations/resolve-and-suggest-segments', {
      method: 'POST',
      body: JSON.stringify({
        ledger_id: currentLedger,
        segment_inputs: [{ dimension_attribute_id: mainAccountDimId, value: mainAccount }]
      })
    });
  },
  
  async validateCombination(segments) {
    return await fetch('/general-ledger/dimension-combinations/resolve-and-suggest-segments', {
      method: 'POST',
      body: JSON.stringify({
        ledger_id: currentLedger,
        segment_inputs: segments
      })
    });
  }
};

With Accounts Receivable Module (Future)​

// AR invoices will integrate with GL posting
const invoice = await fetch('/accounts-receivable/invoices', {
  method: 'POST',
  body: JSON.stringify({
    customer_id: customerId,
    // Inherits customer default dimensions automatically
    lines: [{
      dimension_segments: [...], // Override customer defaults if needed
      amount: 5000.00
    }]
  })
});

// Posting creates GL entries automatically via integration events
await fetch(`/accounts-receivable/invoices/${invoice.id}/post`, { method: 'PUT' });

Error Handling​

Common Error Scenarios​

try {
  const result = await fetch('/general-journals', { method: 'POST', body: journalData });
  if (!result.ok) {
    const error = await result.json();
    
    switch (error.status) {
      case 400:
        if (error.detail.includes('fiscal period')) {
          showError('Cannot post to closed fiscal period');
        } else if (error.detail.includes('dimension')) {
          showDimensionValidationErrors(error.errors);
        }
        break;
      case 422:
        showValidationErrors(error.errors);
        break;
      default:
        showGenericError(error.detail);
    }
  }
} catch (networkError) {
  showNetworkError('Unable to connect to server');
}

Performance Best Practices​

Efficient Dimension Resolution​

// Cache dimension metadata to avoid repeated API calls
const dimensionCache = new Map();

async function getCachedDimensionStructure(mainAccount) {
  if (dimensionCache.has(mainAccount)) {
    return dimensionCache.get(mainAccount);
  }
  
  const structure = await resolveAccountStructure(mainAccount);
  dimensionCache.set(mainAccount, structure);
  return structure;
}

// Debounce dimension validation for real-time UI
const debouncedValidation = debounce(async (segments) => {
  const validation = await validateDimensions(segments);
  updateUIValidation(validation);
}, 300);

Bulk Operations​

// For multiple transactions, create draft then update
const journal = await createJournal({ transactions: [] });

for (const transaction of transactions) {
  await addTransactionToJournal(journal.id, transaction);
}

// Post once all transactions are added
await postJournal(journal.id);

Testing​

API Test Collection​

Use the provided Postman collection for comprehensive testing:

Sample Test Scenarios​

# Successful workflow
POST /general-journals              # Create journal
POST /general-journals/{id}/transactions    # Add transactions  
PUT /general-journals/{id}/transactions/{txnId}  # Update transaction
PUT /general-journals/{id}/post     # Post journal
GET /general-journals/posted        # Verify posted

# Error scenarios
POST /general-journals with future date     # Should fail - fiscal period
POST /general-journals with invalid dimensions  # Should fail - validation
PUT /posted-journal/{id}            # Should fail - cannot modify posted

# Dimension resolution
POST /dimension-combinations/resolve-and-suggest-segments  # Various scenarios

Core Documentation​

Integration Documentation​

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