Journal Entry

​

API operations

​

Data model

​

Attributes

​

Relationships

​

System-computed

• journal_entry_id is generated by PostgreSQL via gen_random_uuid() at INSERT; the TypeScript default randomUUID() is a client-side fallback that is overridden by the DB default.
• created_at is set by MikroORM onCreate lifecycle hook (new Date()); not client-settable.
• updated_at is set by MikroORM onCreate + onUpdate lifecycle hooks (new Date()); updated automatically on every flush. DB column is NOT NULL (TIMESTAMPTZ NOT NULL DEFAULT now()) — cannot be null in production.
• deleted_at follows the platform-wide soft-delete contract: null means active; a non-null timestamp means soft-deleted. All repository queries must predicate deleted_at IS NULL. The posting_idempotency_key partial unique index also gates on deleted_at IS NULL.
• posting_idempotency_key dedup: the partial unique index journal_entries_workspace_posting_idempotency_unique on (workspace_pk, posting_idempotency_key) WHERE deleted_at IS NULL AND posting_idempotency_key IS NOT NULL prevents double-posting by the automated pipelines. This index lives in Migration20260525102000_journal_entry_posting_metadata, not on the entity decorator — schema:fresh may diverge from production on this column.
• status defaults to DRAFT at the DB level (DEFAULT ‘DRAFT’). The VALIDATED and LOCKED transitions are enforced at service level (services/accounting/). Once VALIDATED, entry_number is treated as immutable.
• sourceWorkspaceConnector provenance: when non-null, the entry was written by the MCP sync mapping pipeline (target_model = ‘journal_entry’). A sparse index idx_journal_entries_source_wc exists on source_workspace_connector_pk WHERE non-null — added by Migration20260406100000_expand_mcp_sync_models.
• Composite unique constraint: (workspace_pk, entry_number, fiscal_year) — enforced at DB level to prevent duplicate entry numbers within the same fiscal year for a workspace.
• Partial index on (workspace_pk, entry_date) — idx_journal_entries_workspace_date — optimises date-range queries within a workspace.
• source_entity_type / source_entity_id form a polymorphic soft FK pattern (no DB foreign key). They are set by the posting pipelines to trace origin (e.g. ‘invoice’ + the connector’s external invoice id). No ON DELETE cascade.
• JournalEntryLine children are the load-bearing accounting rows; the JournalEntry header is the grouping container. Accessing lines via Hasura uses the alias ‘lines’ (not ‘journal_entry_lines’) per the composites.yml documentation.
• journal_entry_posting_attempts is a separate append-only ledger table (Migration20260526020000) that records each posting attempt (source_kind × source_id × status). It is not a property of JournalEntry itself but references it by source.

​

Example

{
  "data": {
    "type": "journal_entry",
    "id": "a3f7c21e-84b2-4d19-9f01-2c8e6b5d3a7f",
    "attributes": {
      "journal_entry_id": "a3f7c21e-84b2-4d19-9f01-2c8e6b5d3a7f",
      "entry_number": "VTE-2026-0042",
      "entry_date": "2026-05-15",
      "label": "Facture Acme SAS – vente de licences Q2",
      "status": "VALIDATED",
      "validated_at": "2026-05-16T09:14:22.000Z",
      "fiscal_year": 2026,
      "fiscal_period": 5,
      "source_entity_type": "invoice",
      "source_entity_id": "inv_8f3a12cd",
      "posting_idempotency_key": "invoice:3b6f1a7c-98d2-4e11-a0c3-7f2e8b4d5c1a:v1",
      "posting_metadata": {
        "builder_version": "2.1.0",
        "triggered_by": "invoice_extraction"
      },
      "created_at": "2026-05-15T14:32:11.000Z",
      "updated_at": "2026-05-16T09:14:22.000Z",
      "deleted_at": null
    },
    "relationships": {
      "workspace": {
        "data": { "type": "workspace", "id": "d4e9c2a1-5b7f-4c3e-8d2a-1f6b9e3c7a5d" }
      },
      "journal": {
        "data": { "type": "journal", "id": "c1b8e7f2-3a4d-4f9e-8c1b-5d7a2e9f4b3c" }
      },
      "validated_by": {
        "data": { "type": "people", "id": "e5f2a3b1-7c4d-4e8f-9a2b-3c6d1e5f7a8b" }
      },
      "invoice_transaction": {
        "data": { "type": "invoice_transaction", "id": "b7d3e1f4-2a5c-4b8e-9f3d-1a6c2e7b4d5f" }
      },
      "sourceWorkspaceConnector": {
        "data": null
      },
      "lines": {
        "data": [
          { "type": "journal_entry_line", "id": "f2a1b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c" },
          { "type": "journal_entry_line", "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }
        ]
      }
    }
  }
}