Бухгалтерия через API

Учёт магазина — фискальные документы, деньги, закупки и налоги — читается теми же лентами изменений, что и каталог: один раз загрузите всё, а дальше держите копию в актуальном виде событиями и курсором.

Загружаем поисковый индекс…

Бухгалтерия через API

Доступ

Учёт разделён на 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, поэтому удобнее грузить справочники первыми:

  1. Справочники: юрлица, счета и статьи денег, поставщики, налоговые периоды.
  2. Продажи: фискальные документы, заказы, платежи, возвраты.
  3. Деньги и закупки: движения денег, счета поставщика, их оплаты, удержания.

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.
statuspending — счёт в кассе открыт, 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 называет каждый документ и причину: исправьте их в магазине и запустите операцию снова.

Следующий гайдОшибки