Access
Accounting is split into scopes by what the data is, so an app gets only what it needs:
| Scope | What it opens |
|---|---|
fiscal:read | Legal entities, fiscal documents with their PDF, tax periods, withholdings and perceptions with certificates. |
finance:read | Money accounts, categories and transactions, transfers, the accounting day rate, register shifts, gift cards, customer accounts. |
procurement:read | Suppliers with their bills and payments, offsets, purchase orders, goods receipts, supplier returns, consignment settlements. |
orders:read, payments:read, refunds:read | Sales: 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:
- Reference data: legal entities, money accounts and categories, suppliers, tax periods.
- Sales: fiscal documents, orders, payments, refunds.
- 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:
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 happened | Event |
|---|---|
| The tax authority issued a document, issuing failed, an invoice was annulled | fiscal_document.issued, fiscal_document.failed, fiscal_document.annulled |
| A tax period was closed or reopened | tax_period.status_changed |
| A money transaction was recorded, changed or deleted | money_transaction.created, money_transaction.updated, money_transaction.deleted |
| A supplier bill was posted or voided | supplier_bill.posted, supplier_bill.voided |
| A supplier payment was recorded or cancelled | supplier_bill_payment.created, supplier_bill_payment.deleted |
| A withholding was recorded or annulled | tax_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_linesof 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_linesof 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.
| Task | Where to take it from |
|---|---|
| Journal entries, VAT books, tax returns | Fiscal documents with status issued: invoices, credit and debit notes. |
| Management accounting: margin, sales by rate, a store without fiscal documents | The order and refund tax. |
| The Libro IVA Digital file for the ARCA portal | The libro_iva.export bulk operation — see "VAT books" below. |
| A sale fiscalized by an external POS | The 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):
| Field | What it is |
|---|---|
issuer | The register that issues the document: fudo, poster. |
status | pending — the bill is open in the register, issued — the register issued the document. |
number | Document 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
currencyfield next to them:150000in ARS is 1,500.00. - An accounting date is
YYYY-MM-DDin the store time zone (occurred_on,issued_on), a tax period isYYYY-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
amountin the store currency,account_amountin the account currency andexchange_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:
curl "https://api.saleya.app/v1/exchange-rates/USD?date=2026-11-03" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"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 injurisdiction: 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.