Доступ
Учёт разделён на scopes по смыслу данных, и приложение получает только нужные:
| Scope | Что открывает |
|---|---|
fiscal:read | Юрлица, фискальные документы с PDF, налоговые периоды, удержания и перцепции с сертификатами. |
finance:read | Счета, статьи и движения денег, переводы, курс дня учёта, кассовые смены, подарочные карты, долги покупателей. |
procurement:read | Поставщики, их счета и оплаты, взаимозачёты, заказы поставщику, приёмки, возвраты поставщику, акты реализации. |
orders:read, payments:read, refunds:read | Продажи: заказы с налогом позиций, платежи и возвраты. |
Два scope добавляют поля в чужие ресурсы: costs:read — себестоимость позиций заказа, customers:read — получателя фискального документа (это персональные данные).
Запись — отдельные scopes: finance:write для движений и переводов, procurement:write для поставщиков, заказов и счетов поставщика, fiscal:write для выпуска фактур. Утверждение счёта к оплате (procurement:approve), оплата счёта вне системы (procurement:pay) и аннулирование фактуры (fiscal:annul) — отдельные полномочия: scope записи их не даёт, владелец магазина включает каждое в доступе приложения.
Первая загрузка
Каждый список — лента изменений: прочитайте его до конца и сохраните sync_cursor — см. страницы и синхронизацию. Ленты независимы, но документы ссылаются на справочники по id, поэтому удобнее грузить справочники первыми:
- Справочники: юрлица, счета и статьи денег, поставщики, налоговые периоды.
- Продажи: фискальные документы, заказы, платежи, возвраты.
- Деньги и закупки: движения денег, счета поставщика, их оплаты, удержания.
updated_since начинает загрузку с момента, а не с начала истории — например, с начала учётного года. Это момент с часовым поясом, поэтому полночь магазина в Буэнос-Айресе — 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"Налоговые периоды ведутся у магазинов с налоговым учётом Аргентины; магазину другой страны их список отвечает 403 capability_disabled.
Дальше — события и курсор
Подпишите адрес на события учёта — см. вебхуки. Событие говорит, что запись изменилась, а источником правды остаётся список: по событию запустите синхронизацию этого списка с сохранённым курсором.
| Что произошло | Событие |
|---|---|
| Налоговая выпустила документ, выпуск не удался, фактура аннулирована | fiscal_document.issued, fiscal_document.failed, fiscal_document.annulled |
| Налоговый период закрыт или открыт снова | tax_period.status_changed |
| Движение денег записано, изменено или удалено | money_transaction.created, money_transaction.updated, money_transaction.deleted |
| Счёт поставщика проведён или аннулирован | supplier_bill.posted, supplier_bill.voided |
| Оплата поставщику записана или отменена | supplier_bill_payment.created, supplier_bill_payment.deleted |
| Удержание записано или аннулировано | tax_withholding.created, tax_withholding.annulled |
Синхронизируйте ленты и по расписанию: событие могло не дойти, а список с курсором ничего не пропускает.
Какой налог брать
Налог продажи приходит в двух местах, и это разные правды:
- налог заказа —
tax_linesпозиций, доставки и итога заказа и возврата. Его считает магазин по налоговой классификации товаров на момент продажи; - налог документа —
tax_linesфискального документа. Его авторизовала налоговая, а определяет режим юрлица-эмитента. Этот налог юридически значим.
Они расходятся законно: монотрибутист выпускает фактуру C без налога, хотя товар облагается, а магазин с несколькими юрлицами распределяет продажи между ними — эмитента называет legal_entity_id документа.
| Задача | Откуда брать |
|---|---|
| Проводки, книги IVA, декларации | Фискальные документы в статусе issued: фактуры, кредит- и дебет-ноты. |
| Управленческий учёт: маржа, продажи по ставкам, магазин без фискализации | Налог заказа и возврата. |
| Файл Libro IVA Digital для портала ARCA | Массовая операция libro_iva.export — раздел «Книги IVA» ниже. |
| Продажа, которую фискализировала внешняя касса | Документ кассы — раздел «Продажи внешней кассы» ниже. |
Налоговая строка в обоих местах одна: {regime, kind, rate_bps, base, amount, jurisdiction}. rate_bps — ставка в базисных пунктах (2100 — это 21 %), jurisdiction — провинция у налогов, которым она нужна. Берите amount как есть, а не пересчитывайте из базы и ставки: налог округлён так же, как в документе.
Продажи внешней кассы
Продажу, которая ушла в кассу FuDo или Poster или пришла из неё, фискализирует сама касса: фискального документа Saleya по ней нет. Заказ несёт поле external_fiscal_document (только со scope fiscal:read):
| Поле | Что это |
|---|---|
issuer | Касса, выпускающая документ: fudo, poster. |
status | pending — счёт в кассе открыт, issued — касса выпустила документ. |
number | Номер документа в кассе; null, пока он не выпущен или касса его не сообщает. |
external_fiscal_document: null — документа кассы нет. Юридически значимый налог такой продажи — в документе кассы, поэтому не ищите его в фискальных документах Saleya и не ставьте в книгу налог заказа второй раз. Поздний выпуск фактуры по такому заказу отказывает: второй документ на ту же продажу удвоил бы налог.
Суммы, даты и курсы
- Суммы — целые числа в минорных единицах валюты из соседнего поля
currency:150000в ARS — 1 500,00. - Учётная дата —
YYYY-MM-DDв часовом поясе магазина (occurred_on,issued_on), налоговый период —YYYY-MM. Момент — ISO 8601 в UTC (occurred_at). Документ от 31-го числа по учётной дате остаётся в своём месяце, даже если по UTC это уже следующий. - Курсы и количества — десятичные строки, а не числа с плавающей точкой.
- Движение денег по счёту в чужой валюте несёт
amountв валюте магазина,account_amount— в валюте счёта иexchange_rate— курс, по которому его пересчитали. source {type, id}— запись, которая провела движение (платёж, возврат, оплата поставщику),document {type, id}— его первичный документ (заказ, счёт поставщика, смена кассы): сверяйте по ним, а не по сумме и дате.
Курс дня учёта — тот, которым журнал пересчитывает валютные движения за эту дату, — отдаёт курс валюты:
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 — курс этого дня ещё не зафиксирован: его фиксирует первая валютная операция дня.
Удержания при оплате поставщику
Магазин-агент удерживает налог из оплаты поставщику. В оплате счёта вне системы строки withholdings задают сумму в валюте счёта поставщика, и она уменьшает то, что получает поставщик.
- В реестр удержаний удержание попадает в валюте магазина по курсу дня учёта оплаты — потому что в ней его перечисляют и декларируют. Счёт в долларах с удержанием 10 долларов даст запись в песо по курсу этого дня.
- Нет курса на день оплаты — оплата отклоняется 422 под
withholdings, ничего не записав. - У налога с оборота (
turnover) и муниципального (municipal) провинцияjurisdictionобязательна: без неё удержание не попало бы ни в одну декларацию. - Сертификат, который магазин выдаёт поставщику, — PDF удержания.
В реестре и налог, удержанный магазином (direction: practiced — его нужно перечислить), и налог, удержанный у магазина банком, провайдером оплат или покупателем-агентом (direction: suffered — он идёт к зачёту).
Закрытые периоды
Сданный налоговый период магазин закрывает, и документы этого периода больше не меняются — ни в панели, ни через API. Запись, которая изменила бы закрытый период, получает 422 validation_error под своим полем: у счёта поставщика — tax_period, тем же текстом, что видит человек в панели.
Исправление оформляют документом следующего открытого периода (нотой), либо период открывают в магазине снова. Статус периода — в списке периодов и событии tax_period.status_changed.
Книги IVA и пакет бухгалтера
Регламентные файлы собирает массовая операция, а не лента: libro_iva.export — книги Libro IVA Digital юрлица за месяц в формате портала ARCA, accountant_package.export — пакет бухгалтера (книги, сальдо IVA, реестр удержаний и налог с оборота) одним ZIP.
Если книгу не собрать из-за документов периода, операция заканчивается failed, а error.documents называет каждый документ и причину: исправьте их в магазине и запустите операцию снова.