Документы

API документов — список с товарами, создание (чеки, заказы, накладные и др.), проведение и отмена проведения, удаление, печатные формы в PDF.

Содержание

Ключ, формат запросов и ответов — в статье Общие правила API. Номера типов документов (type_id) — в статье Типы документов.

Список документов

GET /api/documents — по 60 документов на странице, вместе со строками товаров.

Параметр	Значение
`page`	Номер страницы
`limit`, `offset`	Вместо страниц: сколько документов вернуть и сколько пропустить. `limit` не больше лимита кабинета, иначе ответ 413
`id`	ИД документа
`type_id`	Тип документа
`time0`, `time1`	Период: начало и конец (`ГГГГ-ММ-ДД`)
`number`	Номер документа
`fd`, `fp`	Фискальные признаки чека: ФД и ФП
`partner_id`	ИД контрагента
`store_id`	ИД склада
`ready`	`1` — только проведённые, `0` — только непроведённые
`description`	Комментарий (основание)
`test`	`1` — только тестовые операции
`order`	`id` (по умолчанию), `time`, `number`, `sum`, `partner_title`, `store_title`, `type_title`; с `DESC` — обратный порядок

Пример: GET /api/documents?type_id=3&time0=2026-11-01&time1=2026-11-30&store_id=1&order=time%20DESC&page=1

Поля документа

Поле	Значение
`id`, `number`	ИД и номер документа
`type_id`, `type_title`	Тип документа
`time`	Дата и время документа (`ГГГГ-ММ-ДД ЧЧ:ММ:СС`)
`sum`	Сумма
`payment`	Оплаты документа
`ready`, `ready_time`	Проведён ли документ и когда
`auto_flag`	ИД документа во внешней системе (поле `id` при создании через API)
`store_id`, `store_title`, `store_kpp`, `store_fias_id`, `store_balans`	Склад
`partner_id`, `partner_title`, `partner_email`	Контрагент
`branch_id`	Филиал
`worker_id`, `worker`	Сотрудник, связанный с документом
`user_id`, `user_ready`, `user_update`	Кто создал, провёл и изменил документ
`description`	Комментарий (основание)
`fd`, `fp`, `cashbox`, `change_id`, `epay`, `test`	Данные кассового чека: ФД, ФП, касса, смена, система электронной оплаты, тестовая операция
`sno`	Система налогообложения
`bonus_pay`, `bonus_add`	Оплачено и начислено баллов
`status_id`, `status_title`, `status_history`, `status_canceled`	Статус интернет-заказа и его история
`add_cashbox`	Документ ожидает удалённой фискализации на кассе
`marker_id`, `marker_title`	Метка документа
`parent_id`, `contract_id`	Документ-основание и договор
`edo`, `edo_id`	Документ ЭДО, с которым связан документ
`chz_id`	ИД документа в Честном знаке
`executor_procent`, `executor_sum`	Вознаграждение исполнителя
`ts_id`	Транспортное средство
`l_count`, `product_count`	Количество строк и разных товаров
`stock_act`	Движение товара: `1` — приход, `-1` — расход, `0` — не меняет остатки
`other_data`, `other`	Дополнительные данные документа
`date_create`, `date_update`, `date_delete`	Время создания и изменения, признак удаления
`lines`	Строки документа

Поля строки (`lines`)

Поле	Значение
`id`, `product_id`	ИД строки и товара
`title`, `product_title`	Название в документе и в справочнике
`count`, `unit`, `unit_title`, `unit_okei`	Количество и единица измерения
`price`, `product_price`	Цена в документе и в справочнике
`discount`, `writeoff_bonus`	Скидка и списанные баллы
`vat_type`, `vat`, `vat_price`	НДС
`sum`	Итог по строке
`mark`	Коды маркировки (JSON)
`description`	Комментарий
`code`, `gtd`, `country_id`, `country_code`, `country_title`	Артикул, ГТД, страна
`marking`, `egais`, `cat_title`	Маркировка, ЕГАИС, категория товара
`product_characteristic`, `product_parent`, `product_img`	Модификация и изображения товара
`massa`, `quantity`, `proteins`, `fats`, `carbohydrates`, `kkal`, `compound`, `max_discount`	Данные из карточки товара
`deleted`, `parent_id`, `other_data`	Служебные данные строки

Создание документов

POST /api/documents. Тело — JSON-массив документов: за один запрос можно передать несколько (не больше лимита кабинета, иначе ответ 413).

Важно. Созданные документы сразу проводятся: меняют остатки, деньги, баллы клиентов. Чтобы создать документ без проведения, передайте "not_ready": 1.

Поля нового документа

Поле	Значение
`id`	ИД документа в вашей системе. Сохраняется в `auto_flag`. Если документ с тем же `id`, складом, кассой и типом уже проведён, новый сохраняется непроведённым с пометкой «Возможно дубль документа» в комментарии — поэтому повторная отправка после сбоя связи не задвоит продажу
`type_id`	Тип документа (`3` — чек прихода, `15` — чек возврата, `19` — заказ из интернет-магазина, `2` — накладная …)
`time`	Время документа, UNIX-время в секундах
`store`	ИД склада
`sum`	Сумма документа
`not_ready`	`1` — не проводить документ
`description`	Комментарий
`sno`	Система налогообложения (`01`, `02`, `04`, `10`, `20`); если не указана — берётся у склада или организации
`user_id`	ИД пользователя Агорты, от имени которого создан документ
`executor`	ИД пользователя-исполнителя (по умолчанию — `user_id`)
`partner_id`	ИД контрагента. Отрицательное значение — найти клиента по карте, телефону, ИНН или названию из `partner_data`, а если такого нет — создать нового
`not_partner`	`1` — документ без контрагента. Без него документ продажи или возврата без `partner_id` записывается на контрагента по умолчанию
`partner_data`	Данные клиента: `title`, `phone`, `card`, `inn`, `bonus` (стартовые баллы). Прежнее имя поля `partners` тоже принимается
`bonus_pay`, `bonus_add`	Оплачено баллами и начислено баллов клиенту
`paymentmethods`	Оплаты: массив `{"method": 1, "sum": 100}`, где `method` `1` — наличные, `2` — безналичные
`epay_title`	Название системы электронной оплаты
`fd`, `fp`	ФД и ФП, если чек уже напечатан на вашей кассе
`rm`, `changes`, `changes_data`	Касса, номер смены и данные смены (`id`, `cash_start`, `cash_end`, `time_start`, `time_end`) — для документов открытия и закрытия смены
`add_cashbox`	`-1` — отправить документ на удалённую фискализацию кассой Агорты
`remote`	ИД документа Агорты, который был фискализирован удалённо
`nofr`	`1` — тестовая операция
`status_id`, `payments_id`, `delivery_id`, `order_phone`, `order_email`, `order_address`	Для заказа из интернет-магазина: статус, способ оплаты, способ доставки, контакты и адрес
`slip`	Текст слипа банковского терминала
`room_title`, `table_title`	Зал и стол — для чеков в режиме «Ресторан»
`receiptlines`	Строки документа

Строки нового документа (`receiptlines`)

Поле	Значение
`product_id`	ИД товара. `0` — свободная продажа без товара из справочника, отрицательное значение — создать новый товар по данным `other_info`
`product_title`	Название
`count`	Количество
`price`	Цена без НДС и скидок
`discount`	Скидка, %
`vat_type`, `vat`	НДС
`unit_okei`	Код ОКЕИ единицы измерения (`796` — штука, `112` — литр, `166` — килограмм)
`egais`	`1` — алкоголь, `2` — пиво, `0` — не ЕГАИС
`mark`	Коды маркировки — строка с JSON-массивом
`writeoff_bonus`	Баллы, списанные в оплату строки
`other_info`	Данные нового товара: `barcode`, `ppr`, `category_id`, `print_group`

Пример запроса

[
  {
    "id": 53491,
    "type_id": 3,
    "time": 1762700000,
    "store": 1,
    "user_id": 1,
    "sno": "02",
    "sum": 960,
    "partner_id": 0,
    "not_partner": 1,
    "paymentmethods": [{"method": 2, "sum": 960}],
    "receiptlines": [
      {"product_id": 24, "product_title": "Сок яблочный 1 л", "unit_okei": 796, "egais": 0,
       "vat_type": 0, "vat": 0, "price": 200, "count": 2, "discount": 10, "mark": ""},
      {"product_id": 0, "product_title": "Упаковка", "unit_okei": 796, "egais": 0,
       "vat_type": 0, "vat": 0, "price": 600, "count": 1, "discount": 0, "mark": ""}
    ]
  }
]

Ответ: success, txt и receipts_id — массив ИД созданных документов в Агорте. Если какие-то документы не сохранились, success будет false; ИД сохранённых всё равно придут в receipts_id. Проверить, что именно загрузилось, можно списком документов с фильтром по периоду.

Совет. Сервер не проверяет, что склад, товары и суммы существуют и сходятся: документ сохранится с тем, что передано. Проверяйте данные на своей стороне, а для отладки используйте "not_ready": 1 — непроведённый документ можно удалить в личном кабинете без последствий.

Проведение и отмена проведения

GET /api/documents/ready/<ИД>?ready=1 — провести, ?ready=0 — отменить проведение. Без ready состояние переключается на противоположное. Если документ уже в нужном состоянии, ответ успешный и ничего не меняется.

Отмена проведения возможна только в пределах Времени отмены проводки документа из настроек системы; позже придёт ошибка «Отменить проводку уже не возможно».

Удаление документа

DELETE /api/documents/<ИД> — удалить документ. Проведённый документ удалить нельзя — сначала отмените проведение.

Печатные формы (PDF)

GET /api/documents/getprinttempaletes — список печатных форм документа со ссылками на PDF.

Параметр	Значение
`id`	ИД документа в Агорте
`auto_flag`	Или ИД документа в вашей системе (тогда желательно указать ещё `store_id` и `partner_id`)
`order_line`	Порядок строк: `id`, `title`, `cat_title` (с `DESC` — обратный)
`stamp`	`true` — с подписями и печатью организации

Нужен id или auto_flag. Ответ: receipt_type — название типа документа, data — формы:

Поле	Значение
`id`, `title`	ИД и название печатной формы
`pdf`	Ссылка на PDF для пользователя, вошедшего в личный кабинет
`pdf_api`	Ссылка на тот же PDF для программы — откройте её с ключом API (заголовок `Token`)

Обновлено: 09.11.2026