README

General Ledger

General Ledger refers to the system for accumulating POSLog for sales, VAT, payment, and rounding accounts, exporting accumulated receipts as immutable files.

To enable a general-ledger for a tenant/business unit, accounting rules needs to be configured.

How to configure rules?

Configured rules define how transactions are categorized into specific account numbers. Each transaction type is assigned to its corresponding group, with all groups governed by specific default rules.

The types within each rule are prioritized in the order listed below. Each transaction will be assigned to a single type within its group based on these rules.

• Kinds and Types:

  • sales-and-returns (gle.sales-and-returns-rules.v1)

    • ITEM_ID
      • Rules apply to a specific item id.
    • CATEGORY_ID
      • Rules apply to a specific item category.
    • TAX_GROUP_ID
      • Rules apply to a specific tax group.
    • DEFAULT
      • Serves as a fallback if no other configured rules apply.

  • tax (gle.tax-rules.v1)

    • TAX_GROUP_ID
      • Rules apply to a specific tax group.
    • DEFAULT
      • Serves as a fallback if no other configured rules apply.

  • tender (gle.tender-rules.v1)

    • PROVIDER_ID
      • Rules apply to a specific type of tender provider, e.g., AMEX.
    • INTERNAL_TENDER_ID
      • Rules apply to an internally configured tender ID.
    • ROUNDING
      • Rules apply to rounding in transactions.
    • DEFAULT
      • Serves as a fallback if no other configured rules apply.

  • expense (gle.expense-rules.v1)

    • REASON_CODE_ID
      • Rules apply to a specific reason code.
    • DEFAULT
      • Serves as a fallback if no other configured rules apply.

  • income (gle.income-rules.v1)

    • REASON_CODE_ID
      • Rules apply to a specific reason code.
    • DEFAULT
      • Serves as a fallback if no other configured rules apply.

  • gift-card (gle.gift-card-rules.v1)

    • PROVIDER_ID
      • Rules apply to a specific type of gift card.
    • DEFAULT
      • If the configured rules does not apply, this rule will be picked.

One can configure a rule using Customer Controlled Configuration. Example to configure a rule for a business unit:

curl --request PUT 'https://ccc-api.retailsvc.com/api/v1/config/${kind}/values/business-units/${business-unit-id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
    "value": [
        {
            "id": "rule001",
            "config": {
                "accountId": "SR_Standard",
                "type": "TAX_GROUP_ID",
                "value": "Standard"
            }
        },
        {
            "id": "rule002",
            "config": {
                "accountId": "SR190",
                "type": "DEFAULT",
                "value": null
            }
        }
    ]
}'

Note:

• replace business-unit-id, kind & type as per your rule.
• replace API_TOKEN with a active JWT token.

Minimum rules required to be configured

A rounding rule & all the default rule in a each kinds will be required for the service to work.

How & When will I get the data?

General ledger publishes events/data to PubSub. Other Hii Retail services, or external system using External Events, can subscribe to these messages.

First report is generated everyday at 2:00 AM (UTC). If there are any new transactions after 2:00 AM, reports will be generated in 30-minute intervals during the hours from 2:00 AM to 5:59 AM (UTC). All additional new report will have a delta value.

An example of a message published:

{
    "businessUnitId": "PT001",
    "journalId": 33,
    "businessDate": "2024-12-19",
    "accounts": [
        {
            "accountId": "DEF-01",
            "creditAmount": 7.3,
            "debitAmount": 6.2
        },
        {
            "accountId": "DEF-02",
            "creditAmount": 29.2,
            "debitAmount": 24.8
        },
        {
            "accountId": "DEF-03",
            "creditAmount": 51,
            "debitAmount": 56.5
        }
    ]
}

Subscriptions

Tech	Subscription
Pub/Sub	gle.public.event.general-ledger.v1
External Events	gle.public.event.general-ledger.v1

Format

The JSON format.

What happens to delayed transactions?

If the transaction was completed yesterday, but received today, this will be added as a delta to the report generated for yesterday.

What is re-export?

To retrieve already exported data from previous days, a re-export will republish all reports for the specified date range. This can be done for up to three months from the start date, and the report will be received instantly.

curl --location 'https://general-ledger-api.retailsvc.com/api/v1/tenants/${tenant-id}/general-ledger-replay' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
    "businessUnitId": "EU002",
    "businessDate": {
        "from": "2024-10-16",
        "to": "2024-10-16"
    }
}'

What is replay?

If rules are updated and need to be applied to previously exported business dates, a replay can be initiated. The specified dates will be recalculated, and any detected deltas will be published. This can be performed for up to three months from the start date, with the updated report being received instantly.