Accounting through the API

Store accounting — fiscal documents, money, purchasing and taxes — reads through the same change feeds as the catalog: load everything once, then keep the copy up to date with events and the sync cursor.

Loading the search index…

Accounting through the API

Access

Accounting is split into scopes by what the data is, so an app gets only what it needs:

ScopeWhat it opens
fiscal:readLegal entities, fiscal documents with their PDF, tax periods, withholdings and perceptions with certificates.
finance:readMoney accounts, categories and transactions, transfers, the accounting day rate, register shifts, gift cards, customer accounts.
procurement:readSuppliers with their bills and payments, offsets, purchase orders, goods receipts, supplier returns, consignment settlements.
orders:read, payments:read, refunds:readSales: orders with item tax, payments and refunds.

Two scopes add fields to other resources: costs:read adds the cost of order items, customers:read adds the receptor of a fiscal document (personal data).

Writing takes separate scopes: finance:write for transactions and transfers, procurement:write for suppliers, purchase orders and supplier bills, fiscal:write for issuing invoices. Approving a bill for payment (procurement:approve), paying a bill outside the system (procurement:pay) and annulling an invoice (fiscal:annul) are separate permissions: a write scope does not include them, and the store owner turns each one on in the app access.

First load

Every list is a change feed: read it to the end and keep the sync_cursor — see pagination and sync. The feeds are independent, but documents refer to reference data by id, so it is easier to load reference data first:

  1. Reference data: legal entities, money accounts and categories, suppliers, tax periods.
  2. Sales: fiscal documents, orders, payments, refunds.
  3. Money and purchasing: money transactions, supplier bills, their payments, withholdings.

updated_since starts the load at a moment instead of the beginning of history — for example, the start of the fiscal year. It is a moment with a time zone, so store midnight in Buenos Aires is T03:00:00Z:

Request
curl "https://api.saleya.app/v1/fiscal-documents?updated_since=2026-01-01T03:00:00Z&limit=250" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"

Tax periods are kept by stores with Argentine tax accounting; for a store in another country their list answers 403 capability_disabled.

Then: events and the cursor

Subscribe an endpoint to accounting events — see webhooks. An event says that a record changed, while the list stays the source of truth: on an event, sync that list with the saved cursor.

What happenedEvent
The tax authority issued a document, issuing failed, an invoice was annulledfiscal_document.issued, fiscal_document.failed, fiscal_document.annulled
A tax period was closed or reopenedtax_period.status_changed
A money transaction was recorded, changed or deletedmoney_transaction.created, money_transaction.updated, money_transaction.deleted
A supplier bill was posted or voidedsupplier_bill.posted, supplier_bill.voided
A supplier payment was recorded or cancelledsupplier_bill_payment.created, supplier_bill_payment.deleted
A withholding was recorded or annulledtax_withholding.created, tax_withholding.annulled

Sync the feeds on a schedule too: an event may not arrive, and a list with a cursor misses nothing.

Which tax to use

The tax of a sale comes in two places, and they are two different truths:

  • the order tax — tax_lines of the items, delivery and total of an order and of a refund. The store calculates it from the tax classification of the products at the moment of sale;
  • the document tax — tax_lines of a fiscal document. The tax authority authorized it, and the regime of the issuing legal entity sets it. This tax is legally binding.

They legitimately differ: a monotributo taxpayer issues invoice C without tax even though the product is taxed, and a store with several legal entities splits sales between them — the legal_entity_id of the document names the issuer.

TaskWhere to take it from
Journal entries, VAT books, tax returnsFiscal documents with status issued: invoices, credit and debit notes.
Management accounting: margin, sales by rate, a store without fiscal documentsThe order and refund tax.
The Libro IVA Digital file for the ARCA portalThe libro_iva.export bulk operation — see "VAT books" below.
A sale fiscalized by an external POSThe POS document — see "External POS sales" below.

The tax line is the same in both places: {regime, kind, rate_bps, base, amount, jurisdiction}. rate_bps is the rate in basis points (2100 is 21 %), jurisdiction is the province for taxes that need one. Take amount as it is instead of recomputing it from the base and the rate: the tax is rounded the same way as in the document.

External POS sales

A sale that went to a FuDo or Poster register, or came from one, is fiscalized by that register: there is no Saleya fiscal document for it. The order carries the external_fiscal_document field (only with the fiscal:read scope):

FieldWhat it is
issuerThe register that issues the document: fudo, poster.
statuspending — the bill is open in the register, issued — the register issued the document.
numberDocument number in the register; null until it is issued or when the register does not report it.

external_fiscal_document: null means there is no register document. The legally binding tax of such a sale is in the register document, so do not look for it among Saleya fiscal documents and do not book the order tax a second time. Issuing an invoice later for such an order is refused: a second document for the same sale would double the tax.

Amounts, dates and rates

  • Amounts are integers in the minor units of the currency in the currency field next to them: 150000 in ARS is 1,500.00.
  • An accounting date is YYYY-MM-DD in the store time zone (occurred_on, issued_on), a tax period is YYYY-MM. A moment is ISO 8601 in UTC (occurred_at). A document dated the 31st stays in its month even when in UTC it is already the next one.
  • Rates and quantities are decimal strings, not floating-point numbers.
  • A money transaction on a foreign-currency account carries amount in the store currency, account_amount in the account currency and exchange_rate — the rate it was converted at.
  • source {type, id} is the record that posted the transaction (a payment, a refund, a supplier payment), document {type, id} is its primary document (an order, a supplier bill, a register shift): reconcile by them, not by amount and date.

The accounting day rate — the one the books convert foreign-currency transactions of that date with — comes from the currency rate:

Request
curl "https://api.saleya.app/v1/exchange-rates/USD?date=2026-11-03" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Response
HTTP/1.1 200 OK

{
  "currency": "USD",
  "store_currency": "ARS",
  "date": "2026-11-03",
  "rate": "1452.5",
  "rate_date": "2026-11-03",
  "source": "ar_oficial"
}

rate: null means the rate of that day is not fixed yet: the first foreign-currency operation of the day fixes it.

Withholdings on supplier payments

A store acting as a withholding agent withholds tax from a supplier payment. In a bill payment outside the system, the withholdings lines give the amount in the supplier bill currency, and it reduces what the supplier receives.

  • The withholding goes into the withholding register in the store currency at the accounting day rate of the payment, because it is remitted and declared in it. A dollar bill with a 10-dollar withholding gives a peso record at that day's rate.
  • Without a rate for the payment day the payment is rejected with 422 under withholdings, and nothing is recorded.
  • Turnover (turnover) and municipal (municipal) taxes require the province in jurisdiction: without it the withholding would reach no tax return.
  • The certificate the store gives the supplier is the withholding PDF.

The register holds both the tax the store withheld (direction: practiced — it has to be remitted) and the tax withheld from the store by a bank, a payment provider or a customer acting as agent (direction: suffered — it goes to credit).

Closed periods

A store closes a tax period once it is filed, and the documents of that period no longer change — neither in the store admin nor through the API. A write that would change a closed period gets 422 validation_error under its field — tax_period for a supplier bill — with the same text a person sees in the store admin.

A correction is made with a document of the next open period (a note), or the period is reopened in the store. The period status is in the list of periods and the tax_period.status_changed event.

VAT books and the accountant package

Statutory files come from a bulk operation, not a feed: libro_iva.export builds the Libro IVA Digital books of a legal entity for a month in the ARCA portal format, accountant_package.export builds the accountant package (books, VAT balance, withholding register and turnover tax) as one ZIP.

If a book cannot be built because of documents of the period, the operation ends failed, and error.documents names each document with its reason: fix them in the store and run the operation again.

Next guideErrors