Документація API/Продажі/Рахунки
Рахунки
Рахунки на оплату. Статус і оплати впливають на облік, тому записи з проводками коштують більше очок. Право ролі: invoice.
Маршрути
GET
/invoiceСписок рахунків з пагінацією, фільтрами й
total.право: invoice.view2 очк.
GET
/invoice/{id}Одна картка.
право: invoice.view1 очк.
GET
/invoice/countЛише кількість за тими самими фільтрами (голе число).
право: invoice.view2 очк.
POST
/invoiceСтворити.
право: invoice.create10 очк.
PUT
/invoice/{id}Оновити.
право: invoice.update10 очк.
DELETE
/invoice/{id}Видалити.
право: invoice.delete10 очк.
GET
/invoice/document-products/{id}Позиції з доступною для відвантаження/акта кількістю.
право: invoice.view2 очк.
POST
/invoice/{id}/create-shipmentСтворити відвантаження з рахунку.
право: shipment.create5 очк.
POST
/invoice/{id}/create-actСтворити акт виконаних робіт.
право: document.create5 очк.
GET
/invoice/deleted?since=...Видалені записи, див. розділ Синхронізація.
право: invoice.view2 очк.
Усі поля
Обов’язкові provider_id і рівно одне з contact_id / account_id (обидва або жодного дає 422). Номер присвоюється автоматично. Теги й доп. поля описані в розділі Вкладені дані.
status_id береться лише зі статусів рахунків (GET /lookup?type=inv_status, поле value: draft, sent, wait, part_payment, full_payment, cancel); статус іншої сутності чи id, якого немає, дає 422. Рахунок без суми може бути лише draft або cancel; «сплачено» не ставиться ні при створенні, ні без платежів. Вихід із draft проводить борг клієнта. Автоматично статус стає «Сплачено повністю», коли рахунок оплачено і виконано (товари відвантажено, послуги закрито підписаним актом), якщо в кабінеті ввімкнено автозакриття рахунків.
Рахунок, до якого прив’язано хоча б один платіж, не видаляється: 422 «Рахунок має платежі». Спершу видаліть платежі (DELETE /payment/{id}), потім рахунок.
| Поле | Тип | Обмеження | Опис |
|---|---|---|---|
provider_idобов. | id | Ваша юрособа, від якої рахунок (/account/our). | |
external_id | рядок | ≤ 64 симв. | Ключ запису у вашій системі. Унікальний; пошук: filter[external_id;eq]. Див. «Синхронізація». |
name | рядок | ≤ 40 симв. | Назва рахунку. |
number | рядок | ≤ 100 симв. | Номер. При створенні присвоює сервер за префіксом (передане ігнорується); змінити можна PUT. |
inv_type | рядок | ≤ 20 симв. | outgoing (вихідний, клієнту; за замовчуванням) або incoming (вхідний). Інші значення повертають 422. Після створення не змінюється. |
exchange_rate | десяткове (рядок) | Курс валюти до гривні на дату документа: десяткове число рядком, напр. "41.250000". Для гривні завжди 1; якщо для валюти курс не передано, береться курс довідника. | |
created_date | дата-час | Дата рахунку. Не може бути в майбутньому. | |
promised_date | дата-час | Очікувана дата оплати. | |
actual_payment_date | дата-час | Фактична дата оплати. Не може бути в майбутньому. | |
description | рядок | ≤ 1024 симв. | Опис / коментар. |
status_id | id | Статус (/lookup?type=inv_status). Перехід із чернетки проводить дохід. | |
prefix_id | id | Префікс нумерації (/lookup?type=inv_prefix). | |
vat_id | id | Ставка ПДВ (/lookup?type=tax). | |
price_includes_vat | bool | Ціни вказано з ПДВ. | |
currency_id | id | Валюта (/currency). | |
owner_id | id | Відповідальний користувач (/user). Якщо не передано, це користувач токена. | |
contact_id | id | Платник-контакт. Має бути рівно одне з contact_id / account_id. | |
is_archived | bool | В архіві. Архівні записи приховує параметр is_archived=true. | |
recurring_id | id | Шаблон повторення. | |
stock_id | id | Склад (/stock). | |
account_id | id | Платник-контрагент. Має бути рівно одне з contact_id / account_id. | |
client_payment_detail_id | id | Реквізити клієнта (/payment-detail). | |
payment_detail_id | id | Ваші реквізити для оплати (/payment-detail). | |
order_id | id | Замовлення, з якого виставлено. | |
opportunity_id | id | Угода, з якої виставлено. | |
project_id | id | Проєкт. Задається лише при створенні; спроба змінити через PUT поверне 422. | |
project_stage_id | id | Етап проєкту (разом із project_id). Лише при створенні. | |
tags | масив Tag | Теги: [{"id": 3}] або [{"name": "VIP"}]. Передані замінюють усі теги запису. Див. «Вкладені дані». | |
idлише читання | ціле | Ідентифікатор запису. | |
costлише читання | ціле, копійки | Сума позицій у копійках, рахує сервер. | |
paymentлише читання | ціле, копійки | Сплачено, у копійках; рахує сервер за платежами. | |
created_atлише читання | дата-час | Час створення. | |
updated_atлише читання | дата-час | Час останньої зміни, на ньому будується інкрементальна синхронізація. | |
created_by_idлише читання | id | Хто створив запис. | |
deleted_atлише читання | дата-час | Час видалення (у звичайних відповідях завжди null). | |
shop_idлише читання | id | Магазин (філія), ставиться з профілю користувача. | |
updated_userлише читання | об’єкт User | Хто змінив запис останнім. | |
tasksлише читання | масив Task | Завдання запису (лише у відповіді). | |
subлише читання | рядок | Службове поле, ігноруйте. |
Вкладені масиви
invoice_extra_fields: пишеться в тілі POST/PUT, формат див. у розділі Вкладені дані.
Повʼязані обʼєкти для ?expand= (18)
Без expand приходять як null; писати їх не можна, передавайте відповідне *_id.
Status → LookupPrefix → LookupVat → LookupCurrency → CurrencyOwner → UserCreatedBy → UserContact → ContactRecurring → InvoiceRecurringStock → StockAccount → AccountClientPaymentDetail → PaymentDetailPaymentDetail → PaymentDetailProvider → AccountOrder → OrderOpportunity → OpportunityProject → ProjectProjectStage → ProjectStageShop → Shop
Службові поля у відповіді, ігноруйте: OldInvoice.
Позиції документа
Товари й послуги документа. Власного права в позицій немає: читати їх може той, хто бачить документ, а змінювати той, хто може змінювати документ. Сума документа перераховується автоматично.
GET
/invoice/{id}/itemsПозиції з товаром і одиницею, з
total.право: invoice.view2 очк.
POST
/invoice/{id}/itemsДодати позицію.
право: invoice.update10 очк.
PUT
/invoice/{id}/items/{item_id}Змінити кількість, ціну, знижку.
право: invoice.update10 очк.
DELETE
/invoice/{id}/items/{item_id}Видалити позицію.
право: invoice.update10 очк.
| Поле | Тип | Обмеження | Опис |
|---|---|---|---|
entity_typeобов.лише читання | рядок | Тип документа, береться зі шляху. | |
entity_idобов.лише читання | id | Id документа, береться зі шляху. | |
product_idобов. | id | Товар. Для kind=custom не потрібен. | |
name | рядок | ≤ 120 симв. | Назва рядка. Для kind=custom обов’язкова, для товару береться з картки. |
kind | рядок | product | custom, ≤ 10 симв. | product (товар) або custom (довільний рядок без товару, напр. доставка чи послуга). |
cost_price | ціле, копійки | Собівартість одиниці, копійки. Вводиться лише для kind=custom; у товарного рядка береться з партій і в запиті ігнорується. | |
cost_source | рядок | none | manual | product | batch, ≤ 10 симв. | Звідки собівартість: none, manual, product, batch. |
unit_label | рядок | ≤ 30 симв. | Підпис одиниці. |
input_unit_id | id | Одиниця введення / упаковка (/product/{id}/units). | |
input_quantity | ціле, ×1000 | Кількість в упаковках, ×1000. | |
input_price | ціле, копійки | Ціна упаковки, копійки. | |
price | ціле, копійки | Ціна за одиницю, копійки. При додаванні ставиться базова ціна товару; змінюйте PUT рядка. | |
quantity | ціле, ×1000 | Кількість, ×1000. | |
discount_amount | ціле, копійки | Знижка сумою, копійки. | |
discount | ціле | ≤ 10000 | Знижка, соті частки % (1000 = 10 %). Якщо не передано, діє персональна знижка клієнта. |
exchange_rate | десяткове (рядок) | Курс перерахунку ціни товару у валюту документа (службове). | |
reason_id | id | Причина (для повернень). | |
price_book_id | id | Прайс-лист, з якого взято ціну. | |
status | рядок | Статус рядка (службове). | |
description | рядок | ≤ 255 симв. | Коментар до рядка. |
idлише читання | ціле | Ідентифікатор запису. | |
unit_idлише читання | id | Одиниця товару (лише у відповіді). | |
input_factorлише читання | десяткове (рядок) | Скільки базових одиниць в упаковці, береться з картки товару. | |
product_unitsлише читання | масив ProductUnit | Одиниці товару (лише у відповіді). | |
totalлише читання | ціле, копійки | Підсумок рядка, рахує сервер. | |
created_atлише читання | дата-час | Час створення. | |
updated_atлише читання | дата-час | Час останньої зміни, на ньому будується інкрементальна синхронізація. | |
updated_userлише читання | об’єкт User | Хто змінив запис останнім. | |
subлише читання | рядок | Службове поле, ігноруйте. | |
versionлише читання | ціле | Службовий лічильник змін запису. |
Вкладені масиви
batches: лише у відповіді (expand=Batches).serial_numbers: лише у відповіді (expand=SerialNumbers).
Повʼязані обʼєкти для ?expand= (4)
Без expand приходять як null; писати їх не можна, передавайте відповідне *_id.
InputUnit → LookupProduct → ProductReason → LookupPriceBook → PriceBook
Службові поля у відповіді, ігноруйте: UserId, OldEntityProduct.
Додати товар
POST /api/v1/invoice/85/items
Idempotency-Key: invoice-85-add-258
{ "product_id": 258, "quantity": 3000 }Змінити ціну й знижку рядка
PUT /api/v1/invoice/85/items/323
{ "price": 145000, "discount": 500 }Документ і рядок беруться зі шляху:
entity_type / entity_id у тілі ігноруються. Рядок чужого документа в цьому шляху дає 404. Закритий обліковий період, недостатній залишок чи вже проведений документ дають 422 з поясненням (див. Помилки).Приклад
Рахунки клієнта, неоплачені повністю
GET /api/v1/invoice?filter[account_id;eq]=12&filter[status_id;neq]=31&fields=id,number,cost,payment,promised_date
Оплату рахунку фіксує платіж з invoice_id.