Разработчикам
Журнал изменений API
Каждое изменение контракта /v1: новые методы и поля, исправления и устаревания. Изменение внутри /v1 не ломает клиента, который пропускает незнакомые поля.
Политика версий
Внутри /v1 ничего не удаляется и не переименовывается, и то, что работало, продолжает работать. Ломающее изменение выходит новой версией, о которой здесь объявляется заранее.
Версии API →Следите за изменениями
Подпишитесь на ленту Atom в читалке или в рабочем чате: новая запись появляется в ней в день публикации.
Лента Atom
Исправлено
Ленты отдают записи, ссылку которых обнулило удаление
Когда удаление связанной записи обнуляло ссылку в записи списка (tax_class_id товара после удаления налогового класса, location_id счёта денег после удаления точки) или стирало её вложенную строку (строку счёта поставщика, приёмки, возврата поставщику, акта реализации, категорию товара), запись не двигалась в ленте изменений и не давала событие .updated, и копия интеграции оставалась со старым значением. Теперь такая запись приходит в следующей синхронизации по курсору, а у ресурсов с событием .updated — и событием. Изменения до этой даты лента не повторит: если ваша копия хранит эти ссылки или вложенные строки, один раз прочитайте перечисленные списки заново без курсора.
Методы
- get
/ordersЗаказы, изменённые с указанного момента: позиции, суммы, статус заказа и статус оплаты - get
/paymentsПлатежи по заказам, изменённые с указанного момента - get
/refundsВозвраты по заказам, изменённые с указанного момента: позиции и проводки по платежам - get
/customersПокупатели, изменённые с указанного момента: контакты, согласие на рассылки, адреса и группы; поиск по телефону, email и группе - get
/locationsТочки магазина, доступные приложению - get
/categoriesКатегории каталога, изменённые с указанного момента - get
/productsТовары: категории, опции и фото, без вариантов - get
/variantsВарианты товаров: артикул, штрихкоды, цены и единицы - get
/modifier-groupsГруппы модификаторов с опциями, изменённые с указанного момента - get
/recommendation-rulesПравила рекомендаций, изменённые с указанного момента - get
/media-importsЗагрузки фото по адресу, изменённые с указанного момента: ждут, загружены или отказ - get
/lotsПартии товара: номер, срок годности и статус, изменённые с указанного момента - get
/location-transfersАкты перемещения товара между точками со строками, изменённые с указанного момента - get
/fiscal-documentsФискальные документы, изменённые с указанного момента: фактуры, кредит- и дебет-ноты во всех статусах - get
/money-accountsДенежные счета магазина с текущим остатком: касса, банк, эквайринг, кошелёк - get
/money-categoriesСтатьи движений денег: дерево приходов и расходов с кодами системных статей - get
/pos-cash-movementsЖурнал денежного ящика: продажи и возвраты налом, внесения, выдачи, сдача в сейф, размен и сторно - get
/gift-cardsПодарочные карты: номинал, остаток и долг магазина по каждой карте - get
/gift-card-transactionsЖурнал подарочных карт: выпуск, погашение, возврат на карту, корректировка, аннулирование, блокировка и перенос остатка - get
/supplier-billsСчета поставщиков: фактуры, ноты и долги по поставкам без фактуры с налогом и строками - get
/goods-receiptsПриёмки: приход от поставщика со строками, ценами накладной и корректировками - get
/supplier-returnsВозвраты поставщику: отгруженный обратно товар и компенсация за него - get
/consignment-settlementsАкты реализации: проданный, списанный за счёт магазина и переоценённый товар на реализации за период
- get
Изменено
Удержания при оплате счёта поставщика: юрисдикция и валюта
В POST /v1/supplier-bills/{supplier_bill}/payments/out-of-band строка удержания turnover или municipal без jurisdiction теперь отклоняется 422: такое удержание не попадало ни в одну декларацию провинции. Сумма удержания по-прежнему в валюте счёта и вычитается из оплаты поставщику. У счёта в чужой валюте лента tax-withholdings получает эквивалент суммы и базы в валюте магазина по курсу дня оплаты, а раньше получала число в валюте счёта. Нет курса на этот день — оплата с удержаниями отклоняется 422.
Методы
Добавлено
Перемещения между магазинами группы в журнале склада
В журнале движений склада появились причины group_transfer_out (отгрузка в другой магазин группы), group_transfer_in (приёмка из него) и group_transfer_return (недостача перемещения вернулась на склад отправителя) и вид документа group_transfer — копия перемещения этого магазина. Отбор document_type=group_transfer отдаёт движения одного перемещения. Отдельного ресурса перемещений в /v1 нет.
Методы
Добавлено
Документ внешней кассы в заказе
У заказа появилось поле external_fiscal_document — документ продажи во внешней кассе (FuDo, Poster), которая выпускает его вместо нас: касса (issuer), статус pending или issued и номер. Поле приходит со scope fiscal:read; по таким заказам фискальных документов нет. Появление и выпуск документа двигают заказ в ленте и приходят событием order.updated; заказы с историей получают поле одной догрузкой и тоже проходят по ленте заново. В массовой выгрузке orders.export поле есть, если операцию создали со scope fiscal:read.
Методы
Добавлено
Запись фискальных документов
Новые scopes fiscal:write и fiscal:annul. Под fiscal:write POST /v1/orders/{order}/invoice выпускает фактуру по закрытой продаже, POST /v1/fiscal-documents/{document}/reissue перевыпускает документ после сбоя или отказа налоговой (у отклонённой фактуры — с исправленным receptor или refresh_receptor), POST /v1/fiscal-documents/{document}/dismiss снимает отклонённый документ с контроля. Под fiscal:annul POST /v1/fiscal-documents/{document}/annul аннулирует выпущенную фактуру кредит-нотой с причиной reason. Выпуск идёт в налоговую в фоне: ответ 202 и документ, итог — событиями fiscal_document.issued и fiscal_document.failed. У команд, идущих в налоговую, заголовок Idempotency-Key обязателен — без него 422 idempotency_key_required. Новые отказы invoice_issue_refused, fiscal_document_reissue_refused, fiscal_document_dismiss_refused и fiscal_document_annul_refused. У фискального документа появился объект dismissal, у annulment — поле comment; annulment.reason теперь order_cancelled, advance_applied или manual: прежний перечень описывал не те причины.
Методы
- post
/orders/{order}/invoiceВыпустить фактуру по закрытой продаже: выпуск идёт в фоне, итог — событием - post
/fiscal-documents/{document}/reissueПеревыпустить документ после сбоя или отказа налоговой - post
/fiscal-documents/{document}/dismissСнять отклонённый документ с контроля: выпускать его не будут - post
/fiscal-documents/{document}/annulАннулировать выпущенную фактуру кредит-нотой
- post
Добавлено
Оптовые прайс-листы
Новый scope orders:wholesale — условия опта, право панели «вести опт»; включает orders:read, catalog:read и costs:read. Под ним POST /v1/price-lists заводит оптовый лист, DELETE /v1/price-lists/{price_list} удаляет его под If-Match (лист, назначенный покупателям, — с согласием wholesale_price_list_buyers), а PATCH и команды строк пишут оптовый лист; у оптового PATCH правит и name. POST /v1/customers/{customer}/wholesale-price-list назначает покупателю оптовый лист под его If-Match — нужен ещё customers:write. Команды записи листа принимают любой из scopes catalog:write и orders:wholesale, а нужен scope вида листа — его называет отказ insufficient_scope; у метода с несколькими scopes отказ перечисляет их в accepted_scopes.
Методы
Добавлено
Запись прайс-листов
Под catalog:write прайс-лист пишется под If-Match его версии: PATCH /v1/price-lists/{price_list} меняет правило — adjustment_bp и округление rounding; команды POST /v1/price-lists/{price_list}/items и …/items/remove задают и снимают ручные цены вариантов, …/modifier-items и …/modifier-items/remove — ручные надбавки опций, до 1000 строк за запрос одной операцией. Ответ — лист с новой версией, а пачка шлёт одно событие price_list.updated. Строка в деньгах магазина пишется полями price и compare_at_price, в валюте прайса — list_price и list_compare_at_price. Лист точки приложение ведёт, если все его точки приложению доступны; оптовый лист этими командами не пишется.
Методы
- patch
/price-lists/{price_list}Изменить прайс-лист: процент и округление, у оптового — и имя; правило листа точки меняет цены во всех его точках - post
/price-lists/{price_list}/itemsЗадать ручные цены вариантов в прайс-листе пачкой - post
/price-lists/{price_list}/items/removeСнять ручные цены вариантов в прайс-листе пачкой - post
/price-lists/{price_list}/modifier-itemsЗадать ручные надбавки опций в прайс-листе пачкой - post
/price-lists/{price_list}/modifier-items/removeСнять ручные надбавки опций в прайс-листе пачкой
- patch
Добавлено
Прайс-листы
Под catalog:read появились прайс-листы (GET /v1/price-lists) — листы точек и оптовые, с правилом adjustment_bp и округлением rounding, — их ручные цены вариантов (GET /v1/price-list-items) и ручные надбавки опций (GET /v1/price-list-modifier-items). Оптовый лист считает цену от себестоимости и виден только с costs:read; лист точки — приложению, которому доступна хотя бы одна его точка. У точки появилось поле price_list_id, у покупателя — wholesale_price_list_id и фильтр ленты покупателей по нему. Правка ручной цены или надбавки сдвигает версию листа. События price_list.created, price_list.updated, price_list.deleted.
Методы
- get
/price-listsПрайс-листы магазина: листы точек и оптовые, их правило и округление - get
/price-lists/{price_list}Прайс-лист - get
/price-list-itemsРучные цены вариантов в прайс-листах, изменённые с указанного момента - get
/price-list-items/{price_list_item}Ручная цена варианта в прайс-листе - get
/price-list-modifier-itemsРучные надбавки опций модификаторов в прайс-листах, изменённые с указанного момента - get
/price-list-modifier-items/{price_list_modifier_item}Ручная надбавка опции в прайс-листе - get
/locationsТочки магазина, доступные приложению - get
/customersПокупатели, изменённые с указанного момента: контакты, согласие на рассылки, адреса и группы; поиск по телефону, email и группе - get
/customers/{customer}Покупатель
- get
Добавлено
Группы покупателей
Под customers:read появились группы покупателей (GET /v1/customer-groups) — имя, описание и активность, — а у покупателя поле group_ids и фильтр group_id ленты покупателей. Под customers:write группы создаются, правятся под If-Match и удаляются; удаление отвязывает группу от правил скидок и рассылок, опустевшая аудитория выключает правило. Покупателей добавляют в группу и снимают с неё командами POST /v1/customer-groups/{customer_group}/members и …/members/remove. Членство не двигает версию покупателя: его смена сдвигает покупателя в ленте и шлёт customer.updated. События customer_group.created, customer_group.updated, customer_group.deleted.
Методы
- get
/customer-groupsГруппы покупателей магазина: имя, описание и активность - get
/customer-groups/{customer_group}Группа покупателей - post
/customer-groupsСоздать группу покупателей - patch
/customer-groups/{customer_group}Изменить имя, описание или активность группы - delete
/customer-groups/{customer_group}Удалить группу: членство уходит с ней, правила скидок и рассылки от неё отвязываются - post
/customer-groups/{customer_group}/membersДобавить покупателей в группу - post
/customer-groups/{customer_group}/members/removeСнять покупателей с группы - get
/customersПокупатели, изменённые с указанного момента: контакты, согласие на рассылки, адреса и группы; поиск по телефону, email и группе - get
/customers/{customer}Покупатель
- get
Добавлено
Номер отслеживания у службы без интеграции
POST /v1/orders/{order}/shipment/tracking под orders:write записывает номер отслеживания, ссылку и название службы у заказа, который везёт служба доставки без интеграции; POST …/shipment/tracking/clear снимает его. Номер — в shipment заказа: carrier получил значение courier_service, у shipment и previous_shipments появилось поле carrier_name — служба, как её назвал магазин. Покупатель видит номер на странице заказа и получает сообщением, если заказ уже у службы. Новый отказ shipment_tracking_refused.
Методы
- post
/orders/{order}/shipment/trackingЗаписать номер отслеживания у службы доставки без интеграции: номер, ссылку и название службы - post
/orders/{order}/shipment/tracking/clearСнять номер отслеживания, записанный вручную - get
/ordersЗаказы, изменённые с указанного момента: позиции, суммы, статус заказа и статус оплаты - get
/orders/{order}Заказ
- post
Добавлено
Выпуск отправления через API
POST /v1/orders/{order}/shipment выпускает отправление у перевозчика заказа под orders:write: ответ 202 и заказ, выпуск идёт в фоне, итог приходит событием order.updated; отправление уже есть — 200. shipment_attempt получил состояния queued и failed и поле error — код и текст причины отказа. Новые отказы shipment_refused, shipment_in_progress и shipment_outcome_unknown.
Методы
Добавлено
Цена варианта в валюте прайса
У варианта появились поля list_price и list_price_currency — цена, как её назначил владелец, и её валюта, когда магазин ведёт прайс в чужой валюте. У такой позиции price в деньгах учёта считает система по курсу прайса и во входе его не принимает: цену назначают полем list_price (валюта — прайса магазина или currency). null в list_price_currency — цена назначена в деньгах учёта, как раньше.
Методы
- get
/variantsВарианты товаров: артикул, штрихкоды, цены и единицы - get
/variants/{variant}Вариант товара - get
/variants/by-external-id/{external_id}Вариант товара по внешнему id - post
/variantsДобавить вариант в товар - patch
/variants/{variant}Изменить вариант товара - patch
/variants/by-external-id/{external_id}Создать или изменить вариант по внешнему id - get
/productsТовары: категории, опции и фото, без вариантов - get
/products/{product}Товар - get
/products/by-external-id/{external_id}Товар по внешнему id - post
/productsСоздать товар вместе с вариантами - patch
/products/{product}Изменить карточку товара: поля, категории, внешний id - patch
/products/by-external-id/{external_id}Создать или изменить товар вместе с вариантами по внешнему id
- get
Добавлено
Расписание продажи товара
У товара появилось поле sale_schedule — окна недели в часовом поясе магазина, когда позицию можно заказать: список {days, from, to}, где days — дни ISO (1 — понедельник), from и to — «HH:MM», «24:00» только концом; окно, кончающееся раньше начала, идёт через полночь и принадлежит дню начала. null — позицию заказывают всегда. Это не публикация: вне окна товар виден и кладётся в корзину, а оформление сверяет расписание со временем исполнения заказа. Записать поле можно в создании, правке и upsert товара; null стирает расписание.
Методы
- get
/productsТовары: категории, опции и фото, без вариантов - get
/products/{product}Товар - get
/products/by-external-id/{external_id}Товар по внешнему id - post
/productsСоздать товар вместе с вариантами - patch
/products/{product}Изменить карточку товара: поля, категории, внешний id - patch
/products/by-external-id/{external_id}Создать или изменить товар вместе с вариантами по внешнему id
- get
Добавлено
Отправление у перевозчика в заказе
Заказ получил отправление у перевозчика: shipment — перевозчик, номер и страница отслеживания, последний статус из закрытого набора и история статусов с текстом перевозчика; previous_shipments — отправления, заменённые перевыпуском; shipment_attempt — выпуск идёт или его исход неизвестен. Наклейка отправления — GET /v1/orders/{order}/shipment/label, PDF под orders:read и customers:read: на ней данные получателя. Новые отказы shipment_label_unavailable и carrier_unavailable. Опрос перевозчика без нового статуса больше не сдвигает заказ в ленте и не шлёт order.updated.
Методы
Добавлено
Состав скидок заказа
Заказ получил состав скидок: applied_discounts — журнал скидок на товары (откуда скидка, за что, имя правила, промокод, причина ручной скидки, позиция при уценке одной позиции, сумма), delivery_discounts — скидки доставки, items[].discount_allocations — из каких строк журнала сложилась скидка позиции. Суммы сходятся: Σ applied_discounts = discount, Σ delivery_discounts = delivery_discount, Σ раскладки позиции = её discount. Скидка внешней кассы приходит строкой source = external_pos. Заказ сдвигается в ленте и шлёт order.updated и тогда, когда его состав меняется без правки самого заказа: журнал скидок или себестоимость позиций.
Методы
Добавлено
Перемещения и ревизии
Под inventory:read появились акты перемещения между точками (GET /v1/location-transfers) со строками — вариант, партия, количество — и ревизии (GET /v1/stocktakes) со статусом, охватом и признаком слепого счёта. Строки ревизий — своей лентой GET /v1/stocktake-lines: учёт, факт, расхождение, применённая коррекция и остаток точки после проведения; у слепой ревизии в черновике учёт и расхождение — null. Документ движения склада вида location_transfer и stocktake теперь читается этими ресурсами. События location_transfer.created, location_transfer.updated, stocktake.created, stocktake.status_changed, stocktake.updated.
Методы
- get
/location-transfersАкты перемещения товара между точками со строками, изменённые с указанного момента - get
/location-transfers/{location_transfer}Акт перемещения - get
/stocktakesРевизии остатков: охват, статус и даты, изменённые с указанного момента - get
/stocktakes/{stocktake}Ревизия остатков - get
/stocktake-linesСтроки ревизий: учёт, факт, расхождение и коррекция, изменённые с указанного момента - get
/stocktake-lines/{stocktake_line}Строка ревизии
- get
Изменено
Привязка курса в счёте платежа
Режим курса tender.exchange_rate.mode получил значение pegged: магазин привязал валюту способа к другой валюте (например, 1 USDT = 1 USD), и курс — её курс, умноженный на коэффициент. Новое поле tender.exchange_rate.peg {currency, rate} называет привязку; null — курс не привязан. Цены, назначенные в валюте привязки, входят в счёт как есть.
Методы
Добавлено
Журнал движений склада и партии
Под inventory:read появились журнал движений склада (GET /v1/stock-movements) — изменение физического остатка точки со знаком, остаток после, причина, графа ведомости и первичный документ — и партии (GET /v1/lots) с номером, сроком годности и статусом. Строки приёмок, возвратов поставщику и актов реализации получили lot_id. События stock_movement.created, stock_movement.updated, lot.created, lot.updated, lot.deleted.
Методы
- get
/stock-movementsЖурнал движений склада: каждое изменение физического остатка точки - get
/stock-movements/{stock_movement}Движение склада - get
/lotsПартии товара: номер, срок годности и статус, изменённые с указанного момента - get
/lots/{lot}Партия товара - get
/goods-receiptsПриёмки: приход от поставщика со строками, ценами накладной и корректировками - get
/goods-receipts/{goods_receipt}Приёмка - get
/supplier-returnsВозвраты поставщику: отгруженный обратно товар и компенсация за него - get
/supplier-returns/{supplier_return}Возврат поставщику - get
/consignment-settlementsАкты реализации: проданный, списанный за счёт магазина и переоценённый товар на реализации за период - get
/consignment-settlements/{consignment_settlement}Акт реализации
- get
Добавлено
Книги Libro IVA и пакет бухгалтера файлом
У массовых операций появился третий род — файл. Вид libro_iva.export собирает книги Libro IVA Digital юрлица за месяц: в params — legal_entity_id, period вида YYYY-MM и books (ventas, compras или обе; к покупкам — файлы импорта). Вид accountant_package.export собирает пакет бухгалтера. Нужны bulk:write и fiscal:read, налоговый учёт Аргентины у магазина и доступ приложения ко всем точкам. Результат — ZIP с теми же файлами, что в панели; он появляется целиком у completed, а до этого GET …/result отвечает новым 409 bulk_operation_result_unavailable. Отказ сборки — failed с кодом libro_iva_not_applicable или libro_iva_incomplete; у второго error.documents перечисляет документы и причины.
Методы
Добавлено
Оплата счетов поставщика вне системы
Новый scope procurement:pay — по умолчанию не выдаётся и включает procurement:read, но не запись и не одобрение. POST /v1/supplier-bills/{supplier_bill}/payments/out-of-band под If-Match отмечает одобренный счёт оплаченным вне системы: долг закрывается без денежного счёта магазина, у юрлица — агента удержаний состав withholdings обязателен. Ответ — созданная оплата, 201 с Location. DELETE /{supplier_bill}/payments/{supplier_bill_payment} под If-Match отменяет оплату деньгами или вне системы вместе с её удержаниями; остальные виды снимает свой документ — новый отказ supplier_bill_payment_locked. Оплата и отмена приходят событиями supplier_bill_payment.created и .deleted, остаток счёта — supplier_bill.updated.
Методы
Добавлено
Утверждение счетов поставщика к оплате
Новый scope procurementSaleyarove — по умолчанию не выдаётся и включает procurement:read, но не запись. POST /v1/supplier-bills/{supplier_bill}/approve одобряет проведённый счёт к оплате под If-Match: без одобрения счёт не оплачивается, а аванс по заказу счёта гасит его сразу. POST /{supplier_bill}/revoke-approval отзывает одобрение, пока по счёту не было оплат. Отказ по состоянию счёта — supplier_bill_refused. Одобрение и отзыв приходят событием supplier_bill.updated с полем approved_at.
Методы
Добавлено
Мера нетто штуки варианта
У варианта появилось поле net_content — мера нетто одной штуки {quantity, unit}: пачка 500 г, бутылка 1000 мл. В ответе — действующая мера: у упаковки из нескольких единиц другого варианта она выводится из него, у фасованной штуки — из её меры. Записать её можно в создании и правке варианта и товара с вариантами — только у обычного штучного варианта; null стирает. По ней акция-набор засчитывает пачки в позицию «от 1 кг», а фиды витрин показывают цену за килограмм.
Методы
- get
/variantsВарианты товаров: артикул, штрихкоды, цены и единицы - get
/variants/{variant}Вариант товара - get
/variants/by-external-id/{external_id}Вариант товара по внешнему id - post
/variantsДобавить вариант в товар - patch
/variants/{variant}Изменить вариант товара - patch
/variants/by-external-id/{external_id}Создать или изменить вариант по внешнему id - get
/productsТовары: категории, опции и фото, без вариантов - get
/products/{product}Товар - get
/products/by-external-id/{external_id}Товар по внешнему id - post
/productsСоздать товар вместе с вариантами - patch
/products/{product}Изменить карточку товара: поля, категории, внешний id - patch
/products/by-external-id/{external_id}Создать или изменить товар вместе с вариантами по внешнему id
- get
Добавлено
Запись счетов поставщика
Под procurement:write: черновик счёта поставщика (POST /v1/supplier-bills), правка черновика под If-Match (PATCH /v1/supplier-bills/{supplier_bill}), удаление черновика (DELETE), проведение POST /{supplier_bill}/post и аннулирование POST /{supplier_bill}/void. Поля — как в ответе: налоговый период YYYY-MM, курс строкой, налоги сверх НДС — additional_taxes, реквизиты ARCA — в ar. В ответе и записи появился ar.import — реквизиты импорта товаров или услуг. Проведение может потребовать согласия vendor_tax_id или close_returns. Новый отказ supplier_bill_refused: команда не подходит состоянию счёта.
Методы
- post
/supplier-billsСоздать черновик счёта поставщика - patch
/supplier-bills/{supplier_bill}Изменить черновик счёта поставщика - delete
/supplier-bills/{supplier_bill}Удалить черновик счёта поставщика - post
/supplier-bills/{supplier_bill}/postПровести счёт поставщика: он войдёт в кредиторку и книгу покупок - post
/supplier-bills/{supplier_bill}/voidАннулировать счёт поставщика вместе с его оплатами и зачётами
- post
Добавлено
Запись заказов поставщику
Под procurement:write: черновик заказа поставщику (POST /v1/purchase-orders), правка под If-Match (PATCH /v1/purchase-orders/{purchase_order}) — черновика целиком, размещённого — строк, даты и примечания с ревизией и сообщением поставщику, — удаление черновика (DELETE) и переходы POST /{purchase_order}/place, /cancel, /close. Количество и единица цены строки — строкой в базовой единице варианта, как в ответе. Работает у магазина с включёнными закупками, иначе 403 capability_disabled. Новый отказ purchase_order_refused: команда не подходит состоянию заказа.
Методы
- post
/purchase-ordersСоздать черновик заказа поставщику - patch
/purchase-orders/{purchase_order}Изменить заказ поставщику: черновик целиком, размещённый — строки, дату и примечание с ревизией - delete
/purchase-orders/{purchase_order}Удалить черновик заказа поставщику - post
/purchase-orders/{purchase_order}/placeОтметить черновик размещённым у поставщика - post
/purchase-orders/{purchase_order}/cancelОтменить размещённый заказ поставщику - post
/purchase-orders/{purchase_order}/closeЗакрыть принятый заказ поставщику
- post
Добавлено
Модификаторы
Группы модификаторов с опциями под catalog:read и catalog:write: лента GET /v1/modifier-groups, группа по id и по id в вашей системе, создание, правка под If-Match, upsert PATCH /v1/modifier-groups/by-external-id/{external_id} и архив с согласием modifier_group_archive. Опции — набор группы: строка находит опцию по id или external_id, опция, которой нет в наборе, уходит в архив. Правка, снижающая минимум выбора у товаров, просит согласия modifier_product_minimum. GET и PUT /v1/products/{product}/modifier-groups читают и заменяют группы товара с правилом выбора и надбавками опций по вариантам; карточка товара получила поле modifier_groups. Тех-карта варианта получила option_recipes — закладки опций с расходом по блюду. Потолок групп магазина — record_limit_reached.
Методы
- get
/modifier-groupsГруппы модификаторов с опциями, изменённые с указанного момента - get
/modifier-groups/{group}Группа модификаторов с опциями - get
/modifier-groups/by-external-id/{external_id}Группа модификаторов по внешнему id - post
/modifier-groupsСоздать группу модификаторов с опциями - patch
/modifier-groups/{group}Изменить группу модификаторов и её набор опций - patch
/modifier-groups/by-external-id/{external_id}Создать или изменить группу модификаторов по внешнему id - delete
/modifier-groups/{group}Архивировать группу модификаторов - get
/productsТовары: категории, опции и фото, без вариантов - get
/products/{product}Товар - get
/products/by-external-id/{external_id}Товар по внешнему id - post
/productsСоздать товар вместе с вариантами - patch
/products/{product}Изменить карточку товара: поля, категории, внешний id - patch
/products/by-external-id/{external_id}Создать или изменить товар вместе с вариантами по внешнему id - put
/products/{product}/optionsЗаменить опции товара целиком и разложить по ним его варианты - get
/products/{product}/modifier-groupsГруппы модификаторов товара и надбавки их опций по вариантам - put
/products/{product}/modifier-groupsЗаменить группы модификаторов товара и надбавки их опций по вариантам - get
/variants/{variant}/recipeТех-карта варианта: состав и выход заготовки - put
/variants/{variant}/recipeЗаменить тех-карту варианта: состав и выход заготовки
- get
Добавлено
Запись поставщиков
Новый scope procurement:write. Создание поставщика (POST /v1/suppliers), правка под If-Match (PATCH /v1/suppliers/{supplier}) и создание или правка по id в вашей системе (PATCH /v1/suppliers/by-external-id/{external_id}); найти поставщика по нему — GET /v1/suppliers/by-external-id/{external_id} под procurement:read. Пишутся те же поля, что приходят в ответе, кроме customer_id. У поставщика появилось поле external_id. Новый отказ record_limit_reached: магазин достиг потолка записей этого вида, который не зависит от тарифа, — его возвращают POST /v1/suppliers и POST /v1/recommendation-rules.
Методы
- get
/suppliersПоставщики магазина: реквизиты и условия расчётов - get
/suppliers/{supplier}Поставщик - get
/suppliers/by-external-id/{external_id}Поставщик по внешнему id - post
/suppliersСоздать поставщика: реквизиты и условия расчётов - patch
/suppliers/{supplier}Изменить реквизиты, условия расчётов и внешний id поставщика - patch
/suppliers/by-external-id/{external_id}Создать или изменить поставщика по внешнему id - post
/recommendation-rulesСоздать правило рекомендаций - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде
- get
Добавлено
Сырьё, заготовки и тех-карты
POST /v1/products и upsert заводят сырьё и заготовки (type ingredient, prep) с stock_unit — базовой единицей остатков и тех-карт и тарой закупки; stock_unit есть в каждом ответе товара. GET и PUT /v1/variants/{variant}/recipe читают и заменяют тех-карту варианта: состав с закладкой в единице каждого компонента и выход заготовки, под версией товара. Норма труда, шаги производства, метод списания и побочные выходы остаются в панели магазина: API их не трогает.
Методы
- get
/productsТовары: категории, опции и фото, без вариантов - get
/products/{product}Товар - get
/products/by-external-id/{external_id}Товар по внешнему id - post
/productsСоздать товар вместе с вариантами - patch
/products/{product}Изменить карточку товара: поля, категории, внешний id - patch
/products/by-external-id/{external_id}Создать или изменить товар вместе с вариантами по внешнему id - put
/products/{product}/optionsЗаменить опции товара целиком и разложить по ним его варианты - get
/variants/{variant}/recipeТех-карта варианта: состав и выход заготовки - put
/variants/{variant}/recipeЗаменить тех-карту варианта: состав и выход заготовки
- get
Добавлено
Удержания и перцепции
Под fiscal:read: реестр удержаний и перцепций (GET /v1/tax-withholdings, фильтр direction) — налог, удержанный у магазина (suffered: провайдер расчёта, банк, покупатель-агент), и удержанный магазином при оплате поставщику (practiced): вид, налог и юрисдикция, сумма, база и ставка, контрагент, налог и месяц зачёта, номер сертификата, источник и аннулирование. Сертификат, который магазин выдаёт контрагенту, — GET /v1/tax-withholdings/{tax_withholding}/certificate (PDF). Запись журнала счёта покупателя вида withholding получила tax_withholding_id — справку в реестре. Новые события: tax_withholding.created, tax_withholding.updated, tax_withholding.annulled и tax_withholding.deleted.
Методы
- get
/tax-withholdingsУдержания и перцепции, изменённые с указанного момента: удержанное у магазина к зачёту и удержанное магазином к перечислению - get
/tax-withholdings/{tax_withholding}Удержание или перцепция - get
/tax-withholdings/{tax_withholding}/certificatePDF сертификата удержания, который магазин выдаёт контрагенту - get
/customer-account-entriesЖурнал счетов покупателей: продажа в долг, погашение, возврат, списание, взаимозачёт, удержание и сторно - get
/customer-account-entries/{customer_account_entry}Запись журнала счёта покупателя - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Акты реализации
Под procurement:read: акты реализации (GET /v1/consignment-settlements, фильтр supplier_id) — что из товара на реализации продано за период, списано за счёт магазина и доплачено за цену, исправленную корректировкой приёмки: подытоги разделов и строки с вариантом, приёмкой, количеством в базовой единице варианта и ценой поставки — в валюте акта и в валюте магазина. Счёт поставщика уже ссылается на акт полем consignment_settlement_id. Новые события: consignment_settlement.created, consignment_settlement.updated, consignment_settlement.posted и consignment_settlement.voided.
Методы
- get
/consignment-settlementsАкты реализации: проданный, списанный за счёт магазина и переоценённый товар на реализации за период - get
/consignment-settlements/{consignment_settlement}Акт реализации - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Заказы поставщику, приёмки и возвраты поставщику
Под procurement:read: заказы поставщику (GET /v1/purchase-orders, фильтр supplier_id) — строки с заказанным, подтверждённым поставщиком и принятым количеством; приёмки (GET /v1/goods-receipts, фильтры supplier_id и purchase_order_id) — строки с ценой накладной, ценой в валюте магазина и себестоимостью после налога, корректировки «было → стало»; возвраты поставщику (GET /v1/supplier-returns, фильтры supplier_id и goods_receipt_id) — строки, ожидаемая и полученная компенсация, корректировки. Количества — строкой в базовой единице варианта. Счёт поставщика получил goods_receipt_ids, purchase_order_ids и supplier_return_ids. Новые события: purchase_order.created, purchase_order.updated, purchase_order.status_changed, purchase_order.deleted, goods_receipt.created, goods_receipt.updated, goods_receipt.voided, supplier_return.created, supplier_return.updated, supplier_return.status_changed и supplier_return.deleted.
Методы
- get
/purchase-ordersЗаказы поставщику: заказано, подтверждено поставщиком и принято по строкам - get
/purchase-orders/{purchase_order}Заказ поставщику - get
/goods-receiptsПриёмки: приход от поставщика со строками, ценами накладной и корректировками - get
/goods-receipts/{goods_receipt}Приёмка - get
/supplier-returnsВозвраты поставщику: отгруженный обратно товар и компенсация за него - get
/supplier-returns/{supplier_return}Возврат поставщику - get
/supplier-billsСчета поставщиков: фактуры, ноты и долги по поставкам без фактуры с налогом и строками - get
/supplier-bills/{supplier_bill}Счёт поставщика - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Сальдо, акт сверки и взаимозачёты
Под procurement:read: сальдо поставщика (GET /v1/suppliers/{id}/balance) — семь слагаемых долга, раскладка просрочки и итог; акт сверки (GET /v1/suppliers/{id}/statement) — сальдо на начало и конец периода и строки с нарастающим остатком; оба со срезом legal_entity_id. Взаимозачёты (GET /v1/settlement-offsets), их строки отдельной лентой (GET /v1/settlement-offset-lines) и соглашения о зачёте (GET /v1/settlement-agreements). Счёт поставщика получил paid_total и outstanding в валюте документа. Запись книги долгов покупателей получила settlement_offset_id. customer_id поставщика теперь только под customers:read. Новые события: settlement_agreement.created, settlement_agreement.updated, settlement_agreement.deleted, settlement_offset.created, settlement_offset.updated и settlement_offset.voided.
Методы
- get
/suppliers/{supplier}/balanceСальдо поставщика: сколько магазин должен сейчас, по слагаемым и срокам оплаты - get
/suppliers/{supplier}/statementАкт сверки с поставщиком за период: сальдо на начало и конец, строки с нарастающим остатком - get
/suppliersПоставщики магазина: реквизиты и условия расчётов - get
/suppliers/{supplier}Поставщик - get
/settlement-agreementsСоглашения о взаимозачёте: стороны, вид, реквизиты договора, срок и расписание - get
/settlement-agreements/{settlement_agreement}Соглашение о взаимозачёте - get
/settlement-offsetsВзаимозачёты: встречные долги покупателя и поставщика, закрытые документом зачёта - get
/settlement-offsets/{settlement_offset}Взаимозачёт - get
/settlement-offset-linesСтроки взаимозачётов: зачтённые долги покупателя и счета поставщика - get
/settlement-offset-lines/{settlement_offset_line}Строка взаимозачёта - get
/supplier-billsСчета поставщиков: фактуры, ноты и долги по поставкам без фактуры с налогом и строками - get
/supplier-bills/{supplier_bill}Счёт поставщика - get
/customer-account-entriesЖурнал счетов покупателей: продажа в долг, погашение, возврат, списание, взаимозачёт, удержание и сторно - get
/customer-account-entries/{customer_account_entry}Запись журнала счёта покупателя - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Поставщики и счета поставщиков
Новый scope procurement:read. Поставщики (GET /v1/suppliers) — реквизиты и условия расчётов, без контактного лица и заметок. Счета поставщиков (GET /v1/supplier-bills, фильтр supplier_id) — фактуры, ноты и долги по поставкам без фактуры (fiscal: false) с НДС общей налоговой строкой, перцепциями и удержаниями списком additional_taxes, строками и реквизитами ARCA в ar. Оплаты счетов (GET /v1/supplier-bill-payments, фильтр supplier_bill_id) — деньгами, зачётом, нотой кредита, авансом по заказу, расходом журнала или вне системы. Новые события: supplier.created, supplier.updated, supplier.deleted, supplier_bill.created, supplier_bill.updated, supplier_bill.posted, supplier_bill.voided, supplier_bill.deleted, supplier_bill_payment.created, supplier_bill_payment.updated и supplier_bill_payment.deleted.
Методы
- get
/suppliersПоставщики магазина: реквизиты и условия расчётов - get
/suppliers/{supplier}Поставщик - get
/supplier-billsСчета поставщиков: фактуры, ноты и долги по поставкам без фактуры с налогом и строками - get
/supplier-bills/{supplier_bill}Счёт поставщика - get
/supplier-bill-paymentsОплаты счетов поставщиков: деньгами, зачётом, нотой кредита, авансом, расходом журнала или вне системы - get
/supplier-bill-payments/{supplier_bill_payment}Оплата счёта поставщика - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Запись журнала денег и погашение долгов
Новый scope finance:write. Ручной доход или расход (POST /v1/money-transactions), правка и удаление движения под If-Match: у движения с документом-источником меняются только статья, контрагент и описание, остальное — 409 money_transaction_locked. Суммы в валюте счёта — десятичной строкой, лишние знаки — 422. Перевод между счетами — POST, GET, PATCH и DELETE /v1/money-transfers. Массовые операции money_transactions.create и money_transactions.update — проводка и разноска журнала пачкой. Погашение долга покупателя деньгами, которые уже пришли, — POST /v1/customer-accounts/{customer_account}/payments, со справками об удержаниях. У журнала счетов покупателей — фильтр order_id: записи погашения связаны с заказом-погашением, а не с платежом.
Методы
- post
/money-transactionsРучной доход или расход по денежному счёту - patch
/money-transactions/{transaction}Правка движения денег: у движения с документом-источником — только статья, контрагент и описание - delete
/money-transactions/{transaction}Удаление ручного движения денег с возвратом остатка счёта - post
/money-transfersПеревод между денежными счетами, с комиссией или без - get
/money-transfers/{money_transfer}Перевод между денежными счетами - patch
/money-transfers/{money_transfer}Правка перевода целиком на месте: счета, суммы, комиссия, дата и описание - delete
/money-transfers/{money_transfer}Удаление перевода со всеми его частями - post
/customer-accounts/{customer_account}/paymentsПогашение долга покупателя деньгами, которые уже пришли: запись в книгу долгов со справками об удержаниях - get
/customer-account-entriesЖурнал счетов покупателей: продажа в долг, погашение, возврат, списание, взаимозачёт, удержание и сторно - post
/bulk-operationsНачать массовую операцию по загрузке или адресу входа, выгрузку ленты или сборку файла - get
/bulk-operationsМассовые операции приложения, изменённые с указанного момента: прогресс и исходы - get
/bulk-operations/{operation}Массовая операция
- post
Добавлено
Книга долгов покупателей
Под finance:read появились счета покупателей (GET /v1/customer-accounts) — остаток, равный сумме записей счёта, кредитный лимит (null — без лимита) и срок оплаты, — журнал счетов (GET /v1/customer-account-entries, фильтры customer_account_id и payment_id) с суммой со знаком, сроком оплаты начисления и связями с заказом, платежом и возвратом, и выписка за период (GET /v1/customer-accounts/{customer_account}/statement) с нарастающим остатком и открытыми долгами со сроками. Покупатель customer_id и заметка о нём — под customers:read. Новые события: customer_account.created, customer_account.updated, customer_account_entry.created и customer_account_entry.updated — перенос записи на счёт оставшегося покупателя при слиянии покупателей.
Методы
- get
/customer-accountsСчета покупателей в книге долгов: остаток, кредитный лимит и срок оплаты - get
/customer-accounts/{customer_account}Счёт покупателя - get
/customer-accounts/{customer_account}/statementВыписка по счёту покупателя за период: долг на начало и конец, движения с нарастающим остатком и открытые долги со сроками - get
/customer-account-entriesЖурнал счетов покупателей: продажа в долг, погашение, возврат, списание, взаимозачёт, удержание и сторно - get
/customer-account-entries/{customer_account_entry}Запись журнала счёта покупателя - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Подарочные карты и их журнал
Под finance:read появились подарочные карты (GET /v1/gift-cards) — номинал, остаток и outstanding, долг магазина по карте: у неоплаченной карты он 0, у заблокированной и истёкшей равен остатку, — и журнал карт (GET /v1/gift-card-transactions, фильтры gift_card_id и payment_id) с суммой со знаком и остатком после строки. Владелец карты customer_id — под customers:read. Новые события: gift_card.created, gift_card.updated и gift_card_transaction.created.
Методы
- get
/gift-cardsПодарочные карты: номинал, остаток и долг магазина по каждой карте - get
/gift-cards/{card}Подарочная карта - get
/gift-card-transactionsЖурнал подарочных карт: выпуск, погашение, возврат на карту, корректировка, аннулирование, блокировка и перенос остатка - get
/gift-card-transactions/{entry}Строка журнала подарочной карты - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Кассовые смены и журнал денежного ящика
Под finance:read появились кассовые смены (GET /v1/pos-shifts) со сверкой ящика по каждой валюте — фонд открытия, ожидание, пересчёт, расхождение и оставленный размен, — журнал денежного ящика (GET /v1/pos-cash-movements, фильтр shift_id) и справочник причин внесения и выдачи (GET /v1/pos-cash-reasons). У платежей и возвратов — поле и фильтр pos_shift_id: смена, принявшая деньги, по ней сверяется выручка смены. Новые события: pos_shift.opened, pos_shift.closed, pos_shift.updated и pos_cash_movement.created.
Методы
- get
/pos-shiftsКассовые смены, изменённые с указанного момента: сверка денежного ящика по каждой валюте - get
/pos-shifts/{shift}Кассовая смена - get
/pos-cash-movementsЖурнал денежного ящика: продажи и возвраты налом, внесения, выдачи, сдача в сейф, размен и сторно - get
/pos-cash-movements/{movement}Движение денежного ящика - get
/pos-cash-reasonsПричины внесения и выдачи наличных со статьёй журнала денег - get
/paymentsПлатежи по заказам, изменённые с указанного момента - get
/payments/{payment}Платёж по заказу - post
/payments/{payment}/confirmПодтвердить, что деньги по ожидающему счёту получены - get
/refundsВозвраты по заказам, изменённые с указанного момента: позиции и проводки по платежам - get
/refunds/{refund}Возврат по заказу - post
/orders/{order}/refundsВернуть позиции и доставку заказа: деньги — по способам оплаты, товар — на склад - post
/refunds/{refund}/confirmПодтвердить, что деньги возврата отданы вне системы - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Курс дня учёта
Новая операция GET /v1/exchange-rates/{currency} под finance:read отдаёт курс дня учёта на дату — тот, по которому журнал денег пересчитывает в валюту магазина движения по счёту в этой валюте: десятичной строкой, с днём фиксации (rate_date) и источником рыночного курса из правила магазина.
Методы
Добавлено
Денежный журнал: счета, статьи и движения
Новый scope finance:read открывает денежные счета магазина с остатком в валюте счёта, статьи движений с кодами системных статей и журнал движений — с суммой проводки в валюте магазина и в валюте счёта, учётной датой, записью-источником (source) и первичным документом (document); ноги перевода связывает transfer_id. Новые события: money_transaction.created, money_transaction.updated и money_transaction.deleted.
Методы
- get
/money-accountsДенежные счета магазина с текущим остатком: касса, банк, эквайринг, кошелёк - get
/money-accounts/{account}Денежный счёт - get
/money-categoriesСтатьи движений денег: дерево приходов и расходов с кодами системных статей - get
/money-transactionsДвижения денег, изменённые с указанного момента: приходы и расходы по счетам с источником и первичным документом - get
/money-transactions/{transaction}Движение денег - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Комиссия провайдера и удержанный налог платежа
Платёж получает provider_fee_amount и provider_withheld_tax_amount — комиссию платёжного провайдера и налог, который он удержал как агент, — и их доли, возвращённые провайдером при возврате покупателю: refunded_provider_fee_amount и refunded_provider_withheld_tax_amount.
Методы
- get
/paymentsПлатежи по заказам, изменённые с указанного момента - get
/payments/{payment}Платёж по заказу - post
/payments/{payment}/confirmПодтвердить, что деньги по ожидающему счёту получены - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Деньги платежа, юрлицо продажи и события платежей и возвратов
Платёж получает tender — оплату в чужой валюте с курсом, его режимом, источником, рыночной базой и надбавкой магазина, — received_asset (монету, которая пришла на самом деле) и legal_entity_id; заказ — legal_entity_id. Новые события: payment.created, payment.succeeded, payment.status_changed, payment.updated, refund.completed, refund.status_changed и refund.updated.
Методы
- get
/paymentsПлатежи по заказам, изменённые с указанного момента - get
/payments/{payment}Платёж по заказу - post
/payments/{payment}/confirmПодтвердить, что деньги по ожидающему счёту получены - get
/ordersЗаказы, изменённые с указанного момента: позиции, суммы, статус заказа и статус оплаты - get
/orders/{order}Заказ - post
/orders/{order}/cancelОтменить заказ - post
/orders/{order}/statusПеревести заказ в другой статус магазина - post
/draft-orders/{draft}/completeОформить заказ из черновика: выставить счёт покупателю или записать оплату полученной - get
/bulk-operations/{operation}/resultРезультат массовой операции — NDJSON, строка на строку входа или элемент выгрузки, либо ZIP операции-файла; докачка — по Range - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Юрлица, фискальные документы и налоговые периоды
Новый scope fiscal:read открывает юрлица магазина, фискальные документы во всех статусах — с налогом, авторизованным налоговой, учётной датой, реквизитами ARCA и PDF — и налоговые периоды юрлиц у магазинов Аргентины. Получатель документа — со scope customers:read. Новые события: fiscal_document.created, fiscal_document.updated, fiscal_document.issued, fiscal_document.failed, fiscal_document.annulled и tax_period.status_changed.
Методы
- get
/legal-entitiesЮрлица магазина: эмитенты фискальных документов и владельцы налоговых периодов - get
/fiscal-documentsФискальные документы, изменённые с указанного момента: фактуры, кредит- и дебет-ноты во всех статусах - get
/fiscal-documents/{document}Фискальный документ - get
/fiscal-documents/{document}/pdfPDF фискального документа — тот же файл, что получает покупатель - get
/tax-periodsНалоговые периоды юрлиц: какие месяцы закрыты и окончательны - get
/eventsСобытия магазина за 30 дней: что изменилось в заказах, платежах, возвратах, фискальных документах, налоговых периодах, товарах, остатках и покупателях — с записью в её нынешнем виде - post
/webhook-endpointsДобавить адрес вебхука и подписать его на типы событий - patch
/webhook-endpoints/{endpoint}Изменить адрес вебхука: URL, подпись, типы событий, включение
- get
Добавлено
Налог продажи и себестоимость позиций заказа
Заказ получает tax_lines, delivery_tax_lines и tax_lines каждой позиции, возврат — tax_lines: налог продажи по классификации товаров в одной форме TaxLine. Со scope costs:read позиции заказа получают cost_amount и cost_basis.
Методы
- get
/ordersЗаказы, изменённые с указанного момента: позиции, суммы, статус заказа и статус оплаты - get
/orders/{order}Заказ - post
/orders/{order}/cancelОтменить заказ - post
/orders/{order}/statusПеревести заказ в другой статус магазина - post
/draft-orders/{draft}/completeОформить заказ из черновика: выставить счёт покупателю или записать оплату полученной - get
/refundsВозвраты по заказам, изменённые с указанного момента: позиции и проводки по платежам - get
/refunds/{refund}Возврат по заказу - post
/orders/{order}/refundsВернуть позиции и доставку заказа: деньги — по способам оплаты, товар — на склад - post
/refunds/{refund}/confirmПодтвердить, что деньги возврата отданы вне системы - get
/bulk-operations/{operation}/resultРезультат массовой операции — NDJSON, строка на строку входа или элемент выгрузки, либо ZIP операции-файла; докачка — по Range
- get
Добавлено
Налоговые классы товаров
Новый адрес /v1/tax-classes отдаёт налоговые классы магазина: природу налога (taxed, exempt, untaxed) и ставку в базисных пунктах. У товара новое поле tax_class_id — его читают и пишут при создании, правке и upsert; null — класс магазина по умолчанию. Раньше товар, созданный через API, всегда получал класс по умолчанию.
Методы
- get
/tax-classesНалоговые классы магазина: природа и ставка налога, с которыми продаётся товар - get
/productsТовары: категории, опции и фото, без вариантов - get
/products/{product}Товар - get
/products/by-external-id/{external_id}Товар по внешнему id - post
/productsСоздать товар вместе с вариантами - patch
/products/{product}Изменить карточку товара: поля, категории, внешний id - patch
/products/by-external-id/{external_id}Создать или изменить товар вместе с вариантами по внешнему id - put
/products/{product}/optionsЗаменить опции товара целиком и разложить по ним его варианты
- get
Добавлено
Согласие на рекламу по каналам
У покупателя новое поле marketing_consents — согласие на рекламу по каналам (email, telegram, whatsapp, instagram): строка канала, где покупатель явно согласился (subscribed) или отказался (unsubscribed), и момент последнего явного согласия. Отказ в одном канале больше не снимает рекламу в остальных. В WhatsApp магазин пишет рекламу только при subscribed, в любом режиме согласия.
Методы
- get
/customersПокупатели, изменённые с указанного момента: контакты, согласие на рассылки, адреса и группы; поиск по телефону, email и группе - get
/customers/{customer}Покупатель - get
/customers/by-external-id/{external_id}Покупатель по внешнему id - post
/customersСоздать покупателя: имя и хотя бы один контакт - patch
/customers/{customer}Изменить имя, язык и внешний id покупателя - patch
/customers/by-external-id/{external_id}Создать или изменить покупателя по внешнему id
- get
Устарело
accepts_marketing и marketing_consent_at устарели
Поля покупателя accepts_marketing и marketing_consent_at устарели и теперь значат согласие на рекламу по почте. Согласие по каналам — marketing_consents. Поля работают, пока работает /v1.
Методы
- get
/customersПокупатели, изменённые с указанного момента: контакты, согласие на рассылки, адреса и группы; поиск по телефону, email и группе - get
/customers/{customer}Покупатель - get
/customers/by-external-id/{external_id}Покупатель по внешнему id - post
/customersСоздать покупателя: имя и хотя бы один контакт - patch
/customers/{customer}Изменить имя, язык и внешний id покупателя - patch
/customers/by-external-id/{external_id}Создать или изменить покупателя по внешнему id
- get
Добавлено
Счёт продления абонемента
У заказа новая системная причина отмены cancel_reason = membership_renewal_void: счёт продления абонемента погашен, потому что абонемент отменили или он закончился без оплаты. Денег по такому счёту не было.
Методы
Добавлено
Валюта итога при оформлении черновика
Оформление черновика принимает необязательное поле currency — валюту, в которой приложение прочитало итог. Магазин без заказов может сменить валюту, и итог совпал бы числом в другой валюте; теперь такое оформление получает 422, и заказ не создаётся.
Методы
Добавлено
Сгорание пакета визитов
Визиты пакета, срок которого вышел, становятся продажей дня — заказом, оплаченным способом service_package. Продление срока отменяет такую продажу системой: у заказа появляется причина отмены service_package_term_extended, визиты возвращаются в пакет.
Методы
Добавлено
Отказы у каждого метода
У каждого метода в спецификации появилось поле x-problem-types — типы отказов, которые возвращает именно он: свои отказы метода и те, что следуют из его устройства (ключ идемпотентности, версия в If-Match, курсор ленты, диапазон результата, удаление, согласие на последствия). Общие отказы — токен, доступ, проверка входа, лимит запросов, сбои сервера — может вернуть любой метод, их по-прежнему перечисляет каталог x-problem-types документа. Тип stocktake_location_occupied убран из каталога: ни один метод его не возвращал. Методы, которые отвечают конфликтом без ключа идемпотентности, теперь описывают ответ 409.
Изменено
Лимит отклонённых запросов
Запросы, отклонённые на входе, — 401 и 403 неразрешённого адреса или тарифа без API — теперь считаются по адресу. Сверх лимита rejected_requests_per_minute адрес получает 429 too_many_requests с policy равным rejected и заголовком Retry-After до конца минуты. Запросы с действующим токеном не считаются, и этот лимит их не отклоняет.
Добавлено
Визиты из пакетов
Способ оплаты service_package — визит, погашенный пакетом визитов клиента: строку заказа оплатил визит, купленный раньше вместе с пакетом. Деньги за него магазин получил при продаже пакета, поэтому в кассу и на счета этот платёж не приходит, а выручкой заказа визит становится сейчас. Возврат такой строки возвращает визит в пакет — проводка возврата с целью service_package, денег она не двигает.
Методы
- get
/paymentsПлатежи по заказам, изменённые с указанного момента - get
/payments/{payment}Платёж по заказу - get
/refundsВозвраты по заказам, изменённые с указанного момента: позиции и проводки по платежам - get
/refunds/{refund}Возврат по заказу - post
/orders/{order}/refundsВернуть позиции и доставку заказа: деньги — по способам оплаты, товар — на склад - post
/orders/{order}/refunds/calculateРассчитать возврат по заказу и остаток к возврату — ничего не пишет - get
/ordersЗаказы, изменённые с указанного момента: позиции, суммы, статус заказа и статус оплаты - get
/orders/{order}Заказ - post
/draft-orders/{draft}/completeОформить заказ из черновика: выставить счёт покупателю или записать оплату полученной
- get
Добавлено
Пакеты визитов
Вид товара service_package — пакет визитов: набор визитов услуг, который магазин продаёт вперёд. У заказа появилось поле service_package_issue_amount — сумма проданных в нём пакетов. Пакет — обязательство магазина визитами, а не выручка: выручкой становится визит, погашенный пакетом. Вычитайте поле из итога вместе с gift_card_issue_amount, reservation_deposit_amount и account_payment_amount.
Методы
- get
/ordersЗаказы, изменённые с указанного момента: позиции, суммы, статус заказа и статус оплаты - get
/orders/{order}Заказ - post
/orders/{order}/statusПеревести заказ в другой статус магазина - post
/orders/{order}/cancelОтменить заказ - post
/draft-orders/{draft}/completeОформить заказ из черновика: выставить счёт покупателю или записать оплату полученной - get
/bulk-operations/{operation}/resultРезультат массовой операции — NDJSON, строка на строку входа или элемент выгрузки, либо ZIP операции-файла; докачка — по Range - get
/productsТовары: категории, опции и фото, без вариантов - post
/productsСоздать товар вместе с вариантами - get
/products/{product}Товар - patch
/products/{product}Изменить карточку товара: поля, категории, внешний id - get
/products/by-external-id/{external_id}Товар по внешнему id - patch
/products/by-external-id/{external_id}Создать или изменить товар вместе с вариантами по внешнему id - put
/products/{product}/optionsЗаменить опции товара целиком и разложить по ним его варианты
- get
Выпуск
API для интеграций v1
Первая версия контракта: магазин и его точки, каталог, остатки, заказы и их статусы, черновики заказов, платежи и возвраты, покупатели, загрузки и массовые операции, события и вебхуки. Каждое следующее изменение контракта появится в этом журнале.