Documents

Accounting documents represent financial transactions from your ERP system — invoices, payments, credit memos, journal entries, and more. They are the foundation for reconciliation between your accounting system and bank transactions in Atlar.

This guide covers the conceptual model, field semantics, and integration patterns for the Documents API (/v2beta/documents).

---

Conceptual Model

SOURCE vs INSTRUCTION

Every document is automatically classified as either SOURCE or INSTRUCTION based on its general ledger entries:

You do not set classification yourself. The system computes it from the GL accounts used in glEntries. If you change GL entries via a PATCH, classification is recomputed.

Document Lifecycle

A typical document moves through these stages:

1. Created — synced from your ERP into Atlar.
2. Partially applied — one or more counter-documents are linked (e.g., a partial payment applied to an invoice). The remainingAmount reflects what is still outstanding.
3. Fully applied — remainingAmount reaches zero.
4. Matched — the document is matched to a bank transaction during reconciliation (reconciliationStatus: MATCHED).
5. Reconciled — the reconciliation match is approved (reconciliationStatus: RECONCILED).

How Documents Relate to Each Other

Documents are linked through appliedDocuments. For example, when a payment is made against an invoice:

• The payment document lists the invoice in its appliedDocuments (with the applied amount).
• The invoice document's remainingAmount should be updated to reflect the partial or full payment.

These relationships are bidirectional in meaning but managed by the caller — Atlar does not automatically update remainingAmount when you create or modify appliedDocuments. See What you manage vs what the system computes.

---

Document Types

The type field identifies the kind of accounting transaction:

Remember: classification is determined by GL accounts, not by type. A JOURNAL_ENTRY that touches a bank GL account becomes an INSTRUCTION.

---

Key Fields Explained

amount and remainingAmount

Both fields use the MultiCurrencyAmount structure with two sub-amounts:

• instructedAmount — the amount in the document's original currency.
• baseAmount — the amount in the GL entity's base (functional) currency.

amount is the total face value of the document and does not change after creation (unless explicitly patched).

remainingAmount tracks the outstanding portion:

• For SOURCE documents (e.g., invoices): represents the unpaid balance. Required at creation.
• For INSTRUCTION documents (e.g., payments): represents the unapplied portion — how much of the payment hasn't been matched to a source document yet. Optional.

Example: You create an invoice for $1,000 with remainingAmount also set to $1,000. A $400 payment is applied against it. You would then PATCH the invoice to update remainingAmount to $600.

glEntries

Every document must have at least one general ledger entry. Each entry specifies:

• glAccountId — the GL account affected.
• amount — the entry amount (with instructedAmount and baseAmount).
• type — DEBIT or CREDIT.
• vendorId — the entry's identifier in your ERP.

GL entries serve two purposes: they record the accounting impact and they determine the document's classification. If any entry references a GL account of type BANK, the document is classified as INSTRUCTION.

Simple invoice example (two entries):

1. Debit Accounts Receivable (non-bank) — $1,000
2. Credit Revenue (non-bank) — $1,000

Result: classification = SOURCE (no bank account involved).

Payment example (two entries):

1. Debit Accounts Payable (non-bank) — $500
2. Credit Bank Account (bank) — $500

Result: classification = INSTRUCTION (bank account involved).

reference, references, and description

These three fields serve distinct purposes:

Use reference for the primary identifier your team would use to look up the document. Use references for supplementary data that helps with matching or audit trails.

date

The meaning of date depends on the document type:

This is not the creation timestamp (that's created), nor when the document was created in your ERP (that's vendorCreated).

counterparty

Identifies the external party involved in the transaction:

• name — the counterparty's legal name.
• type — VENDOR, CUSTOMER, or EMPLOYEE.
• erpId — the counterparty's identifier in your ERP system.

Required for INVOICE, CREDIT_MEMO, and PURCHASE_ORDER documents. Optional for other types.

currencyExchange

Required when the document's instructed currency differs from the GL entity's base currency. Specifies:

• exchangeRate — the conversion rate.
• sourceCurrency / targetCurrency — the currency pair.
• unitCurrency — which currency the rate is quoted in.

vendorCreated and vendorResourceUrl

These fields track the document's origin in your external system:

---

What You Manage vs What the System Computes

Understanding this boundary is critical for a correct integration.

The system computes:

• classification — derived from GL accounts in glEntries. Recomputed on update.
• id, organizationId, version, etag, created, updated — system-managed metadata.
• GL entry IDs — auto-generated for each entry.

You must manage:

• remainingAmount — the system does not update this when appliedDocuments change. When you apply a payment to an invoice, you must PATCH the invoice's remainingAmount yourself.
• appliedDocuments — you maintain the links between documents. The system stores them but does not validate that referenced documents exist or that amounts balance.
• reconciliationStatus — you (or the reconciliation workflow) must explicitly transition this. Creating an appliedDocuments entry does not automatically change reconciliation status.
• voided — you must explicitly mark a document as voided if it is cancelled in your ERP.

---

Reconciliation Status

The reconciliationStatus field tracks where a document stands in the reconciliation workflow:

Constraints:

• Setting status to RECONCILED requires a reconciliationMatchId to be set in the same PATCH request.
• A reconciliationMatchId is only valid when status is RECONCILED.