Náklady

CRUD pre náklady. POST/PATCH prijíma line_items, totals dopočíta service.

Náklady (expenses) reprezentujú prijaté faktúry, bločky a iné výdavkové doklady. Sú immutable: PATCH vytvorí novú verziu, stabilný id ostane. POST/PATCH prijíma zoznam line_items a service vypočíta totals (subtotal / VAT / total).

Endpointy

Filtre pre `GET /expenses`

search – fulltext (description, number).
category_id – filter na konkrétnu kategóriu.
contact_id – filter na dodávateľa.
status – jeden z new, processing, processed, paid, failed. Pozor: pole v odpovedi je payment_status a má len hodnoty paid / unpaid.
from / to – ISO 8601 dátumový rozsah nad poľom date.
page, limit – stránkovanie (default limit=20, max 100).
sort_by, sort_order – radenie (asc / desc, default desc).

POST/api/v1/expensesexpenses:write

Vytvorí náklad zo zoznamu line_items. Service vypočíta amount_without_tax, amount_tax a amount_total.

Request

curl -X POST "https://monivio.sk/api/v1/expenses" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Kancelárske potreby",
  "issue_date": "2026-06-01",
  "due_date": "2026-06-15",
  "contact_id": "con_2hf8pq3rxn4mlkzyt9abwvve",
  "currency": "EUR",
  "line_items": [
    {
      "description": "Papier A4 (250 ks)",
      "quantity": 5,
      "unit_price": 4.5,
      "vat_rate": 23
    }
  ]
}'

Response 201json

{
  "data": {
    "id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
    "number": "FA-20260612",
    "date": "2026-06-01T00:00:00.000Z",
    "due_date": "2026-06-15T00:00:00.000Z",
    "contact": {
      "id": "con_7tnZ8wKmRvQpXjL5BcHfYsAd",
      "name": "Office Depot"
    },
    "category": {
      "id": "cat_xfzwq2hjkbpr6ny9smtv8d4l",
      "name": "Kancelárske potreby"
    },
    "currency": "EUR",
    "amount_without_tax": 22.5,
    "amount_tax": 5.18,
    "amount_total": 27.68,
    "payment_status": "unpaid",
    "description": "Papier A4 + tonery",
    "tag_ids": [
      "tag_xKZqL9bM7nT4vR8sCdHfWgYj"
    ],
    "created_at": "2026-06-01T11:24:00.000Z",
    "version": 1,
    "received_at": "2026-06-01T11:24:00.000Z",
    "payment_reference": null,
    "internal_notes": null,
    "file_id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "line_items": [
      {
        "description": "Papier A4 (250 ks)",
        "quantity": 5,
        "unit_price": 4.5,
        "vat_rate": 23,
        "amount": 27.68
      }
    ]
  }
}

GET/api/v1/expensesexpenses:read

Zoznam nákladov so stránkovaním a filtrami.

Request

curl "https://monivio.sk/api/v1/expenses?limit=10" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response 200json

{
  "data": [
    {
      "id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
      "number": "FA-20260612",
      "date": "2026-06-01T00:00:00.000Z",
      "due_date": "2026-06-15T00:00:00.000Z",
      "contact": {
        "id": "con_7tnZ8wKmRvQpXjL5BcHfYsAd",
        "name": "Office Depot"
      },
      "category": {
        "id": "cat_xfzwq2hjkbpr6ny9smtv8d4l",
        "name": "Kancelárske potreby"
      },
      "currency": "EUR",
      "amount_without_tax": 22.5,
      "amount_tax": 5.18,
      "amount_total": 27.68,
      "payment_status": "unpaid",
      "description": "Papier A4 + tonery",
      "tag_ids": [
        "tag_xKZqL9bM7nT4vR8sCdHfWgYj"
      ],
      "created_at": "2026-06-01T11:24:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 1,
    "total_pages": 1
  }
}

GET/api/v1/expenses/{id}expenses:read

Detail nákladu vrátane line_items.

Request

curl "https://monivio.sk/api/v1/expenses/con_2hf8pq3rxn4mlkzyt9abwvve" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response 200json

{
  "data": {
    "id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
    "number": "FA-20260612",
    "date": "2026-06-01T00:00:00.000Z",
    "due_date": "2026-06-15T00:00:00.000Z",
    "contact": {
      "id": "con_7tnZ8wKmRvQpXjL5BcHfYsAd",
      "name": "Office Depot"
    },
    "category": {
      "id": "cat_xfzwq2hjkbpr6ny9smtv8d4l",
      "name": "Kancelárske potreby"
    },
    "currency": "EUR",
    "amount_without_tax": 22.5,
    "amount_tax": 5.18,
    "amount_total": 27.68,
    "payment_status": "unpaid",
    "description": "Papier A4 + tonery",
    "tag_ids": [
      "tag_xKZqL9bM7nT4vR8sCdHfWgYj"
    ],
    "created_at": "2026-06-01T11:24:00.000Z",
    "version": 1,
    "received_at": "2026-06-01T11:24:00.000Z",
    "payment_reference": null,
    "internal_notes": null,
    "file_id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "line_items": [
      {
        "description": "Papier A4 (250 ks)",
        "quantity": 5,
        "unit_price": 4.5,
        "vat_rate": 23,
        "amount": 27.68
      }
    ]
  }
}

PATCH/api/v1/expenses/{id}expenses:write

Vytvorí novú verziu (id zostáva, version+1). Stačí poslať polia, ktoré meníš.

Request

curl -X PATCH "https://monivio.sk/api/v1/expenses/con_2hf8pq3rxn4mlkzyt9abwvve" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
  "line_items": [
    {
      "description": "Papier A4 (500 ks)",
      "quantity": 10,
      "unit_price": 4.5,
      "vat_rate": 23
    }
  ]
}'

Response 200json

{
  "data": {
    "id": "exp_5wpqzx9k3rt8nmlhvyc4bfsj",
    "number": "FA-20260612",
    "date": "2026-06-01T00:00:00.000Z",
    "due_date": "2026-06-15T00:00:00.000Z",
    "contact": {
      "id": "con_7tnZ8wKmRvQpXjL5BcHfYsAd",
      "name": "Office Depot"
    },
    "category": {
      "id": "cat_xfzwq2hjkbpr6ny9smtv8d4l",
      "name": "Kancelárske potreby"
    },
    "currency": "EUR",
    "amount_without_tax": 45,
    "amount_tax": 10.35,
    "amount_total": 55.35,
    "payment_status": "unpaid",
    "description": "Papier A4 + tonery",
    "tag_ids": [
      "tag_xKZqL9bM7nT4vR8sCdHfWgYj"
    ],
    "created_at": "2026-06-01T11:24:00.000Z",
    "version": 2,
    "received_at": "2026-06-01T11:24:00.000Z",
    "payment_reference": null,
    "internal_notes": null,
    "file_id": "fil_xKZqL9bM7nT4vR8sCdHfWgYjE2pUaQ",
    "line_items": [
      {
        "description": "Papier A4 (500 ks)",
        "quantity": 10,
        "unit_price": 4.5,
        "vat_rate": 23,
        "amount": 55.35
      }
    ]
  }
}

GET/api/v1/expenses/{id}/pdfexpenses:read

Stiahne pôvodný naskenovaný účet/faktúru priložený k nákladu (file_id). Bez priloženého súboru vracia 404.

Request

curl "https://monivio.sk/api/v1/expenses/con_2hf8pq3rxn4mlkzyt9abwvve/pdf" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

DELETE/api/v1/expenses/{id}expenses:write

Vymaže náklad. Zachováva sa v histórii pre audit.

Request

curl -X DELETE "https://monivio.sk/api/v1/expenses/con_2hf8pq3rxn4mlkzyt9abwvve" \
  -H "Authorization: Bearer mk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Objekt Expense (detail)

idreadonly

string

Stabilné CUID2 ID s prefixom exp_.

Príklad: exp_5wpqzx9k3rt8nmlhvyc4bfsj

versionreadonly

number

Verzia – PATCH zvyšuje. Stará verzia ostane v histórii.

number

string/ null

Číslo prijatej faktúry (ako ti ho dodávateľ pridelil). Pri POST a PATCH voliteľné.

Príklad: FA-20260612

descriptionrequired

string

Krátky popis nákladu (1–500 znakov).

Príklad: Papier A4 + tonery

issue_daterequired

string (ISO 8601)

Iba pri zápise – dátum vystavenia. V odpovedi sa vracia ako date.

Príklad: 2026-06-01

datereadonly

string (ISO 8601)

Dátum vystavenia v odpovedi (ISO 8601 datetime). Pri zápise sa posiela pod kľúčom issue_date.

Príklad: 2026-06-01T00:00:00.000Z

due_date

string (ISO 8601)/ null

Splatnosť faktúry.

Príklad: 2026-06-15T00:00:00.000Z

received_at

string (ISO 8601)/ null

Kedy si doklad prijal (default = teraz pri POST). Voliteľné v body POST/PATCH.

contact_id

string/ null

Iba pri zápise – ID dodávateľa (kontaktu). V odpovedi sa vracia ako objekt contact.

Príklad: con_7tnZ8wKmRvQpXjL5BcHfYsAd

contactreadonly

{ id, name } | null

Dodávateľ – kontakt v tvojej databáze.

category_id

string/ null

Iba pri zápise – ID kategórie. V odpovedi sa vracia ako objekt category.

categoryreadonly

{ id, name } | null

Kategória nákladu (z /categories?type=expense).

currency

string (ISO 4217)

Mena nákladu. 3-písmenový ISO 4217 kód. Default EUR.

Príklad: EUR

exchange_rate

number

Iba pri zápise – kurz pre prepočet do hlavnej meny organizácie. Default 1.

vat_rate_id

string/ null

Iba pri zápise – ID konkrétnej VAT rate konfigurácie (pre režimy odpočtu DPH).

is_vat_deductible

boolean

Iba pri zápise – či je DPH odpočítateľná. Default false.

amount_without_taxreadonly

number

Subtotal pred DPH (vypočítané z line_items).

amount_taxreadonly

number

Suma DPH (vypočítané z line_items).

amount_totalreadonly

number

Celková suma s DPH (vypočítané z line_items).

payment_statusreadonly

"paid" | "unpaid"

Stav úhrady v odpovedi. Pozor – list filter ?status= akceptuje aj interné stavy new, processing, processed, failed.

payment_reference

string/ null

Variabilný symbol / referencia pre úhradu.

internal_notes

string/ null

Interné poznámky (max 5000 znakov).

file_id

string/ null

ID priloženého súboru (PDF/JPG/PNG). Stiahnuteľný cez /expenses/{id}/pdf.

tag_ids

string[]

Pripnuté tagy (max 20). Voliteľné pri zápise, vždy v odpovedi.

line_itemsrequired

LineItem[]

Položky: description, quantity, unit_price, vat_rate (0–100). V odpovedi sa pridáva aj amount. Min 1, max 100 položiek.

created_atreadonly

string (ISO 8601)

Kedy bol náklad prvýkrát vytvorený.

Endpointy

Filtre pre GET /expenses

Objekt Expense (detail)

Filtre pre `GET /expenses`