Quetzal Glossary
Naming in financial systems is hard. This glossary defines the terms used in Quetzal precisely, and explicitly calls out where legacy naming in existing systems differs. When in doubt, use the Quetzal term.
Index
Account Snapshot · Billing Policy · Charge Account · Charge Entry · Document · Fiscal Document · Fiscal Document Types · FiscalEmissionRequest · Org Unit · Submission Ledger · Tenant · Tenant Context
Core Terms
Charge Account
A financial account that tracks what a payer owes for a beneficiary in a given period. Contains charge entries, credit entries, and derives a balance.
In Quetzal: ChargeAccount / charge_accounts table.
In invoices-server: Called Invoice. This naming is confusing because "invoice" also refers to a fiscal document. In Quetzal, Invoice is not used for this concept — it survives only as a document_type value on the Document resource.
Key fields: tenant_id, payer_id, beneficiary_id, org_unit_id, account_type, entries, balance, status.
Charge Entry
A single line item within a charge account. Can be a charge (positive, owed by the payer), a credit (negative, reduces what is owed), or an adjustment (corrects a previous entry).
In Quetzal: ChargeEntry / charge_entries table.
In invoices-server: Called InvoiceItem. Has a concept_type (MEMBERSHIP, SCHOLARSHIP, DISCOUNT, SURCHARGE, etc.) that is Mattilda-specific. In Quetzal, the equivalent is entry_type — a string defined per tenant.
Key fields: entry_type, entry_category (CHARGE / CREDIT / ADJUSTMENT), calculation_mode (FIXED / PERCENTAGE), amount, pending_amount.
Document (API resource)
The primary first-class resource of the Quetzal Invoicing API. A Document is the request- and response-shape that carries everything needed to emit (or describe) a fiscal document against a tax authority. Its document_type field selects the kind of fiscal document the resource represents.
In Quetzal API: /v1/documents — see SPEC/openapi.yaml.
Why a single resource: All four tax authorities (DIAN, SAT, SRI, SUNAT) deal with the same conceptual primitives (issuer, receiver, line items, fiscal id). Modeling them as one resource with a document_type discriminator avoids per-country endpoints and keeps the contract minimal.
Fiscal Document
A tax-compliant document issued by a company to a customer and registered with the tax authority. In fiscal/accounting terms: an invoice, credit note, debit note, or payment complement.
In Quetzal: Modeled by the Document API resource. Internally tracked through the Fiscal Compliance bounded context as FiscalChange / FiscalDocument.
In regulatory-invoices: Called InvoiceChange or just the result of the pipeline. The pipeline produces and tracks these documents.
Important: A fiscal document is NOT the same as a charge account. A charge account records what is owed. A fiscal document is the legal instrument that formalizes a transaction with the tax authority. One charge account may result in zero, one, or multiple fiscal documents over its lifetime.
Fiscal Document Types
Values of Document.document_type. Each maps to a real-world fiscal instrument with country-specific semantics.
| Type | Description | Country availability |
|---|---|---|
invoice | Standard fiscal invoice emitted to a customer | CO, MX, EC, PE |
credit_note | Cancels or adjusts a previously emitted invoice | CO, EC, PE |
debit_note | Adds charges to a previously emitted invoice | CO, PE |
payment_complement | Confirms a payment was received against an invoice | MX (CFDI complemento de pago) |
cancellation | Direct cancellation without credit note | CO (per policy), MX |
Submission Ledger
The record of all fiscal documents that have been emitted (or attempted) for a given charge account. Used by Billing Orchestration to determine whether a document still needs to be emitted, and by gap detection to identify missing documents.
In regulatory-invoices: SubmissionLedger — built from regulatory_invoice_change_actions and provider operations tables.
In Quetzal: Billing Orchestration maintains its own submission_ledger_entries projection, fed by fiscal_document.emitted events from Fiscal Compliance.
Account Snapshot
A point-in-time read model of a charge account, containing all entries and the current balance. This is what Billing Orchestration reads to evaluate whether a fiscal document needs to be emitted.
In Quetzal: AccountSnapshot — defined in schemas/accounts/events.proto. Replaces the current pattern of the fiscal compliance pipeline reading directly from invoices and invoice_items tables.
FiscalEmissionRequest
The command that Billing Orchestration sends to Fiscal Compliance, containing everything the pipeline needs to emit a fiscal document. Self-contained — the pipeline does not read any external data after receiving this command.
In Quetzal: Defined in schemas/billing/fiscal_emission_request.proto.
Replaces: The current ChangeRequest + SqlContextDataGateway reads of invoices, invoice_items, campus_settings, user_tax_data.
Tenant
An educational company using Quetzal as its financial platform. Examples: mattilda, algebraix, lottus-school.
Tenants are not countries and not campuses. A single tenant can operate in multiple countries and have multiple org units.
Org Unit
An organizational subdivision within a tenant. Mattilda calls these "campuses". Another company might call them "schools", "branches", or "locations". Quetzal uses the generic term org_unit_id — each tenant defines what it means.
In Mattilda: campus_id → maps to org_unit_id in Quetzal.
Billing Policy
The configuration that controls when and how Billing Orchestration decides to emit fiscal documents for a given tenant and org unit. Includes when to bill (by date or by payment), what document types are allowed, how charges are grouped, and how cancellations are handled.
In regulatory-invoices: BillingPolicyView — read from campus_settings table, Mattilda-specific field names (emmit_trigger, emmit_method, emmit_nc, etc.).
In Quetzal: TenantBillingPolicy — stored in tenant_billing_policies table, tenant-agnostic field names, configurable via API.
Tenant Context
The runtime context that identifies which tenant, country, and org unit a request belongs to. Injected at the API boundary and carried through all service calls.
TenantContext(
tenant_id="mattilda",
country=Country.CO,
org_unit_id="1e43cc9e-0f3e-4e3c-881a-864d5bc4250d"
)
Legacy Terms (avoid in new code)
These terms exist in current systems but should not be used in Quetzal code or documentation. Use the Quetzal term instead.
| Legacy term | System | Quetzal equivalent | Why deprecated |
|---|---|---|---|
Invoice (charge) | invoices-server | ChargeAccount | Ambiguous — also means fiscal document |
InvoiceItem | invoices-server | ChargeEntry | Too specific to invoices-server's model |
ConceptType (MEMBERSHIP, INSCRIPTION...) | regulatory-invoices | entry_type (tenant-defined string) | Mattilda-specific, hardcoded enum |
FiscalGroup (INVOICE_MAIN, SURCHARGES...) | regulatory-invoices | grouping_strategy in TenantBillingPolicy | Mattilda-specific, hardcoded grouping |
EntityCandidate (CAMPUS, MATTILDA) | regulatory-invoices | issuer field in FiscalEmissionRequest | Mattilda-specific issuer model |
BillingPolicyView | regulatory-invoices | TenantBillingPolicy | Mattilda-specific field names from campus_settings |
CAMPUS_BILLING_DATE_REACHED | regulatory-invoices | Billing cycle trigger event | Mattilda-specific trigger naming |
campus_id | regulatory-invoices / invoices-server | org_unit_id | Mattilda-specific organizational unit name |
MATTILDA_CAMPUS_IDS | regulatory-invoices | Tenant configuration | Hardcoded constants have no place in the platform |