Invoices, payments and the chart of accounts. Read scopes: finance:invoices:read, finance:payments:read, finance:accounts:read; write scopes: finance:invoices:write, finance:payments:write. Every create and edit accepts an Idempotency-Key header (or requestId in the body; 8–128 chars of letters, digits, . _ : -): repeating the same key with the same content returns the first result (200, idempotentReplay: true) and creates nothing new; the same key with different content answers 409 IDEMPOTENCY_KEY_REUSED; a failed request stores nothing, so it can be retried with the same key.

List Invoices

GET /finance/invoices

Invoices with total, paid and remaining amounts.

Query Parameters

ParameterTypeDescription
searchstringText search on invoice number / customer
statusstringdraft, ready, settled, balance (has remaining balance), credit
dateFrom, dateTostringDate range, YYYY-MM-DD (Gregorian)
page, pageSizenumberPagination (pageSize max 100)

Example

curl -G "https://www.HomaCRM.com/api/v1/external/finance/invoices" \
  -H "Authorization: a1B2c3D4e5F6g7H8-i9J0k1L2m3N4o5P6-q7R8s9T0u1V2w3X4" \
  -H "Accept: application/json" \
  --data-urlencode "status=balance" \
  --data-urlencode "dateFrom=2026-06-01"

Get Invoice

GET /finance/invoices/{id}

Invoice header plus line items (quantity, unit price, discount, line total) and payments. Sensitive internal fields are omitted.

List Payments

GET /finance/payments

Payments and receipts. Query: search, invoiceId, customerId, direction=receive|pay, method=bank|cash|cheque, dateFrom, dateTo, page, pageSize (max 200). Each record has a direction of pay or receive, a methodLabel and the customerId. meta.totals = {receivedTotal, paidTotal, net} over the whole filtered set, in rial. Example: GET /finance/payments?customerId=7&direction=receive returns {"data":[{"id":88,"invoiceId":1201,"customerId":7,"amount":12500000,"methodLabel":"cash","direction":"receive","date":"2026-06-16T10:00:00.000Z"}],"meta":{"totalCount":1,"totals":{"receivedTotal":12500000,"paidTotal":0,"net":12500000}}}.

Record a Payment

POST /finance/payments

Scope finance:payments:write. Body: amount (rial), operation receive|pay, method bank|cash|cheque (bankId for bank, chequeId for cheque, fundId for cash), invoiceId or customerId, date, comments, tagNumber. A near-identical payment within 60 seconds answers 409. Example: {"amount":12500000,"operation":"receive","method":"cash","invoiceId":1201,"requestId":"pay-1201-0001"} returns 201 {"id":90,"invoiceId":1201,"amount":12500000,"direction":"receive","method":"cash","invoiceStatus":"2"}.

Create an Invoice

POST /finance/invoices

Scope finance:invoices:write. Body: customerId, items[] (1–100: productId, quantity, optional unitPrice (defaults to the price list), discountPercent, taxPercent, comments), invoiceDiscount, comments, date, status draft|ready, type: 1 sale (default), 2 purchase, 3 sale return, 5 purchase return (official type 4 is not accepted). Example: {"customerId":4521,"type":2,"items":[{"productId":310,"quantity":2,"unitPrice":5000000}],"requestId":"po-2026-0042"} returns 201 {"id":1305,"serial":412,"customerId":4521,"status":"draft","total":10000000}.

Edit an Invoice

PUT /finance/invoices/{id}

Scope finance:invoices:write. Edits a draft or ready invoice with the same rules as the Homa invoice form. Body (any subset): customerId, date, comments, invoiceDiscount, reference, status draft|ready, items[]. items replaces the lines: a line with id (from GET) is updated and keeps its price unless unitPrice is sent, a line without id is added at the price list price, an existing line left out is removed. Errors: 404 INVOICE_NOT_FOUND, PRODUCT_NOT_FOUND, CUSTOMER_NOT_FOUND; 409 INVOICE_LOCKED (checked), INVOICE_NOT_EDITABLE (settled, on balance or official), INVOICE_HAS_COMPANIONS; 403 PRICE_CHANGE_DENIED (changing the price of an existing line needs access code 351); 422 ITEM_NOT_IN_INVOICE. Deleting or cancelling invoices is not available through the API. Example: {"comments":"corrected","items":[{"id":5001,"productId":310,"quantity":3},{"productId":311,"quantity":1}]} returns {"id":1305,"serial":412,"status":"draft","total":15000000,"itemsCount":2,"itemIds":[5001,5002],"unit":"rial"}.

Chart of Accounts Tree

GET /finance/accounts/tree

Three-level accounting coding hierarchy: group → total (کل) → secondary (معین).

Accounting: Documents, Balances and Statements

Accounting documents (سند حسابداری), account balances and the main statements. Scopes: finance:documents:read (documents and balances) and finance:reports:read (trial balance, income statement, balance sheet). The portal always comes from the token. Amounts are in rial ("currency": "IRR", "unit": "rial"). Every range accepts Gregorian dateFrom/dateTo (YYYY-MM-DD), Jalali jalaliFrom/jalaliTo (YYYY/MM/DD) or a Jalali fiscalYear (for example 1404); responses carry both calendars.

GET /finance/documents

List accounting documents. Query: the date range, serial, search, accountId or accountCode (documents that touch the account), draft=exclude|only|all (default exclude), auto=all|only|exclude, page, pageSize (max 200). Scope finance:documents:read. Example: GET /finance/documents?jalaliFrom=1404/12/01&jalaliTo=1404/12/29&accountCode=1101 returns {"documents":[{"id":41,"serial":"7","date":"2026-03-01","dateJalali":"1404/12/10","title":"سند فروش","amount":5000000,"isDraft":false,"isAuto":false,"itemsCount":2}],"currency":"IRR","unit":"rial"} with meta pagination.

GET /finance/documents/lines

Raw ledger lines (ریزِ اسناد) to build any report or statement from: line date (Gregorian and Jalali), document serial, the account at all three levels (group, kol, moein with id, code, title), floating-detail ids (refs), description, debit, credit. Query: the date range (by line date), accountId or accountCode at any level, customerId, personId, bankId, cashId, serial, search, draft, auto, order=asc|desc, page, pageSize (max 1000). totals cover the whole filtered set, not just the page. Scope finance:documents:read. Example: GET /finance/documents/lines?fiscalYear=1404&accountCode=1101&pageSize=200 returns {"lines":[{"id":7,"documentId":41,"serial":"12","dateJalali":"1404/12/10","description":"شرح","debit":1000,"credit":0,"group":{"code":"11"},"kol":{"code":"1101"},"moein":{"code":"110101"},"refs":{"customerId":null,"bankId":8}}],"totals":{"debit":9000,"credit":9000,"difference":0},"unit":"rial"}.

POST /finance/documents

Create a manual accounting document. Body: date (YYYY-MM-DD) or dateJalali, optional time, title, comments, isDraft, and lines[] (2–500) each with accountCode or accountId (leaf/moein account), whole-rial debit or credit (one side only), comment and, where the account has a floating detail, customerId / personId / bankId / cashId matching its kind. Debit must equal credit unless isDraft. Errors: 400 validation; 422 ACCOUNT_NOT_FOUND, ACCOUNT_NOT_LEAF, ACCOUNT_INACTIVE, DETAIL_REQUIRED, DETAIL_NOT_ALLOWED, DETAIL_NOT_FOUND; 409 FISCAL_YEAR_LOCKED. Scope finance:documents:write (a read-only token never writes). The portal always comes from the token. Idempotency: send an Idempotency-Key header (or requestId in the body; 8–128 chars of letters, digits, . _ : -). Repeating the same key with the same content returns the first result (200, idempotentReplay: true) and never creates a second document; the same key with different content answers 409 IDEMPOTENCY_KEY_REUSED. Failed requests store nothing, so they can be retried with the same key. Example: {"dateJalali":"1404/12/10","title":"سند آزمایشی","lines":[{"accountCode":"110101","debit":1000},{"accountCode":"410101","credit":1000}],"requestId":"doc-2026-0001"} returns 201 {"documentId":51,"serial":17,"linesCount":2,"totals":{"debit":1000,"credit":1000,"balanced":true},"unit":"rial"}.

GET /finance/documents/{id}

One accounting document with its lines (account, debit, credit, floating-detail ids) and a balanced check. Scope finance:documents:read. Example: GET /finance/documents/41 returns {"document":{"id":41,"serial":"7","dateJalali":"1404/12/10","title":"سند فروش"},"items":[{"id":1,"accountCode":"1101","debit":5000000,"credit":0,"refs":{"customerId":null}},{"id":2,"accountCode":"4101","debit":0,"credit":5000000}],"totals":{"debit":5000000,"credit":5000000,"balanced":true},"unit":"rial"}.

PUT /finance/documents/{id}

Replace the header and lines of a manual document (same body as POST). 404 if absent; 409 DOCUMENT_READONLY for automatic documents, DOCUMENT_LINKED when payments, cheques or invoices point at it, DOCUMENT_FINAL when you try to turn a final document back into a draft, FISCAL_YEAR_LOCKED for a closed year. Drafts are excluded from every balance until they are finalized in the Homa app. Deleting or voiding documents is not available through the API. Scope finance:documents:write. Example: {"dateJalali":"1404/12/10","title":"سند اصلاح‌شده","lines":[{"accountCode":"110101","debit":1200},{"accountCode":"410101","credit":1200}]} returns {"documentId":41,"serial":7,"linesCount":2,"previous":{"linesCount":2,"debit":1000,"credit":1000},"unit":"rial"}.

GET /finance/documents/{id}

One document with all its lines (account code and title, debit, credit, linked customer/person/bank/cash/payment/cheque/invoice ids) and totals.balanced. Scope finance:documents:read.

GET /finance/accounts/balances

Opening balance, debit/credit turnover and closing balance per account — the same numbers as the account review screen (drafts excluded). Query: the date range, level=tree|group|kol|moein, balanceScope=all|range (range = turnover of the range only), search, includeZero. Scope finance:documents:read. Example: GET /finance/accounts/balances?fiscalYear=1404&level=kol returns {"accounts":[{"id":11,"code":"1101","title":"موجودی نقد","opening":0,"debit":1700,"credit":500,"balance":1200}],"unit":"rial"}.

GET /finance/reports/trial-balance

Trial balance (تراز آزمایشی) at level=moein|kol|group with closing debit/credit columns, totals and balanced. Query: the date range, balanceScope, includeZero. Scope finance:reports:read. Example: GET /finance/reports/trial-balance?fiscalYear=1404&level=moein returns {"rows":[{"code":"110101","title":"صندوق","debit":1700,"credit":500,"closingDebit":1200,"closingCredit":0}],"totals":{"debit":1700,"credit":1700,"closingDebit":1200,"closingCredit":1200},"balanced":true,"unit":"rial"}.

GET /finance/reports/income-statement

Income statement (سود و زیان), the same report as the in-app screen. Query: fiscalYear (+ optional month 1-12) or a date range. Scope finance:reports:read. Example: GET /finance/reports/income-statement?fiscalYear=1404&month=3 returns the same statement as the Homa screen: {"summary":[],"income":{"rows":[],"total":0},"costs":{"rows":[],"total":0},"finalBenefit":0,"unit":"rial"}.

GET /finance/reports/balance-sheet

Balance sheet (ترازنامه) as of asOf / asOfJalali (default today). fourColumn is Homa's own account-browse balance as a four-column trial balance at group, kol and moein level (turnoverDebit, turnoverCredit, balanceDebit, balanceCredit, cumulative up to the date). The response also splits balance-sheet accounts split by the sign of their balance (debit = assets, credit = liabilities and equity) plus the accumulated profit of profit-and-loss accounts. A simple reproducible definition, not a statutory statement. Scope finance:reports:read. Example: GET /finance/reports/balance-sheet?asOfJalali=1404/12/29 returns {"asOf":"2026-03-20","fourColumn":{"moein":{"rows":[{"code":"110101","turnoverDebit":1700,"turnoverCredit":500,"balanceDebit":1200,"balanceCredit":0}],"balanced":true}},"assets":{"total":1200},"currentProfit":1200,"unit":"rial"}.

Treasury: Banks, Funds, Cheques and Transfers

Bank accounts, cash funds and cheques. Scopes: finance:treasury:read (reads) and finance:treasury:write (transfers; administrator tokens only by default). Balances and ledgers use the same ledger rows as the account review; positive = money held. Amounts are rial.

GET /finance/treasury/banks

Bank accounts (account numbers masked to the last 4 digits). Query: activeOnly. Example response: {"data":[{"id":3,"title":"ملت","accountNumber":"****1234","branchTitle":"مرکزی","isActive":true}]}.

GET /finance/treasury/funds

Cash funds (صندوق). Query: activeOnly. Example response: {"data":[{"id":2,"title":"صندوق مرکزی","comments":null,"isActive":true}]}.

GET /finance/treasury/cheques

Cheques. Query: type=received|issued, position (comma list: inventory, in_collection_bank, collected, uncollected_relatives, uncollected_payable_docs, returned_receivable, spent_receivable, void, expensed, petty_cash, cashier, no_document, supplier), customerId, bankId, search, dueFrom/dueTo, regFrom/regTo (YYYY-MM-DD), page, pageSize (max 200). Each cheque has positionKey and positionLabel (where it is now; status is an internal number). meta.totals.totalAmount covers the whole filter. Example: GET /finance/treasury/cheques?type=received&position=in_collection_bank returns {"data":[{"id":45,"type":"received","positionKey":"in_collection_bank","positionLabel":"درجریان وصول-نزد بانک","chequeNumber":"123456","amount":50000000,"customerName":"علی رضایی","dueDate":"2026-07-10T00:00:00.000Z"}],"meta":{"totalCount":1,"totals":{"totalAmount":50000000}}}.

GET /finance/treasury/balances

Balance of every bank account and cash fund. Query: asOf / asOfJalali (default all time), kind=bank|fund|all. Example response: {"accounts":[{"kind":"bank","id":3,"title":"ملت","debit":9000,"credit":4000,"balance":5000},{"kind":"fund","id":2,"title":"صندوق مرکزی","debit":1500,"credit":300,"balance":1200}],"totals":{"banks":5000,"funds":1200,"all":6200},"unit":"rial"}.

GET /finance/treasury/banks/{id}/ledger

Ledger of one bank account (and /finance/treasury/funds/{id}/ledger for a fund): opening balance, lines with document serial, cheque and payment ids and a running balance, closing balance. Query: the date range (dateFrom/dateTo, jalaliFrom/jalaliTo or fiscalYear), page, pageSize (max 1000). 404 if the id is not in your portal. Example: GET /finance/treasury/banks/3/ledger?fiscalYear=1404 returns {"account":{"kind":"bank","id":3,"title":"ملت"},"summary":{"openingBalance":0,"debit":9000,"credit":4000,"closingBalance":5000},"lines":[{"dateJalali":"1404/12/10","documentSerial":"7","debit":9000,"credit":0,"runningBalance":9000}],"unit":"rial"}.

GET /finance/treasury/funds/{id}/ledger

Ledger of one cash fund; same query and response shape as the bank ledger with account.kind = fund. Example: GET /finance/treasury/funds/2/ledger?jalaliFrom=1404/12/01 returns {"account":{"kind":"fund","id":2,"title":"صندوق مرکزی"},"summary":{"openingBalance":0,"debit":1500,"credit":300,"closingBalance":1200},"lines":[{"dateJalali":"1404/12/05","documentSerial":"3","debit":1500,"credit":0,"runningBalance":1500}],"unit":"rial"}.

POST /finance/treasury/transfers

Scope finance:treasury:write. Moves money between two bank accounts or cash funds by posting a balanced two-line accounting document (debit the destination, credit the source). Body: from and to as {"type":"bank"|"fund","id":N}, amount (whole rial), date or dateJalali, optional time and comment. Errors: 400 validation (same account both sides, non-positive amount); 422 DETAIL_NOT_FOUND (bank or fund not in your portal), TREASURY_ACCOUNT_NOT_CONFIGURED; 409 FISCAL_YEAR_LOCKED. Idempotency-Key header (or requestId in the body) is required: without it the call answers 400 IDEMPOTENCY_KEY_REQUIRED, so a client retry can never move money twice. A repeat returns the first transfer (200, idempotentReplay); the same key with different content answers 409. Example: {"from":{"type":"fund","id":2},"to":{"type":"bank","id":3},"amount":5000000,"dateJalali":"1404/12/10","comment":"واریز به بانک","requestId":"xfer-2026-0001"} returns 201 {"documentId":52,"serial":18,"linesCount":2,"amount":5000000,"from":{"type":"fund","id":2},"to":{"type":"bank","id":3},"unit":"rial"}. Cheque life-cycle operations (collect, bounce, endorse) are not available yet.

Counterparties: Balances, Statement and Aging

Customers and suppliers (طرف‌حساب) with the same definition as Homa's persons sub-ledger. Positive balance = the counterparty owes us. Scope finance:reports:read. Amounts are rial.

GET /finance/counterparties/balances

Balance per counterparty. Query: asOf / asOfJalali (default today), direction=debtor|creditor|all, minAbsBalance, search (name, company, mobile), includeZero, sort=balance_desc|balance_asc|name|last_activity, page, pageSize (max 500). totals (debtors, creditors, net) cover the whole filter. Example response: {"counterparties":[{"customerId":7,"name":"علی رضایی","debit":1000,"credit":100,"balance":900,"direction":"debtor","lastActivityJalali":"1404/12/10"}],"totals":{"debtors":900,"creditors":200,"net":700},"unit":"rial"}

GET /finance/counterparties/{customerId}/statement

Statement of one counterparty: opening balance, lines with document serial, invoice serial and running balance, closing balance. Query: the date range (dateFrom/dateTo, jalaliFrom/jalaliTo or fiscalYear), page, pageSize (max 1000). 404 if the id is not in your portal. Example: GET /finance/counterparties/7/statement?fiscalYear=1404 returns {"summary":{"openingBalance":500,"debit":300,"credit":100,"closingBalance":700},"lines":[{"dateJalali":"1404/12/10","documentSerial":"7","invoiceSerial":"88","debit":300,"credit":0,"runningBalance":800}]}.

GET /finance/counterparties/aging

Receivables aging: open debit per counterparty by age. Credits are applied to the oldest debits first; leftover credit is unappliedCredit. Query: asOf / asOfJalali, buckets (ascending day boundaries, default 30,60,90, 1-6 values), search, limit (max 500). Example response: {"buckets":[{"label":"0-30","amount":250},{"label":"31-60","amount":0},{"label":"61-90","amount":0},{"label":"91+","amount":0}],"totalReceivable":250,"unappliedCredit":40,"counterparties":[{"customerId":7,"buckets":[250,0,0,0],"total":250}],"unit":"rial"}

HomaCRM External API

For support, create a ticket via /support/tickets endpoint.

Using WordPress? The HomaCRM WordPress plugin connects SMS and CRM without code.